KbKnowledgeSource.java
/*
* Copyright © 2026 IKE Network (support@ike.network)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package network.ike.plugin;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* One artifact a new knowledge base loads, by Maven coordinate: a protobuf knowledge source
* ({@code groupId:artifactId:zip:classifier:version}) or a source release
* ({@code groupId:artifactId:extension[:classifier]:version}). A knowledge source starts as
* requested and is then pinned (IKE-Network/ike-issues#1370, decision 9): a snapshot is
* fixed to the exact timestamped deploy Nexus holds, so a later deploy under the same
* snapshot version cannot change what the knowledge base is built from.
*
* @param groupId the group
* @param artifactId the artifact
* @param extension the file extension, such as {@code zip}
* @param classifier the classifier, or an empty string for none
* @param version the version as requested
* @param pinnedVersion the exact version to build from: a release as requested, a snapshot
* by its timestamp; equal to {@code version} until pinned
* @param sizeBytes the artifact's size on the repository, or {@code -1} when not known
*/
record KbKnowledgeSource(String groupId, String artifactId, String extension, String classifier,
String version, String pinnedVersion, long sizeBytes) {
/** The starter set's group: every knowledge base is built on it. */
static final String STARTER_SET_GROUP = "network.ike.foundation";
/** The starter set's artifact. */
static final String STARTER_SET_ARTIFACT = "ike-starter-set";
/** The classifier of an unclassified protobuf. */
static final String UNREASONED = "unreasoned-pb";
/** The classifier of a classified, standalone protobuf. */
static final String REASONED = "reasoned-pb";
/** A snapshot fixed to one deploy: {@code <base>-yyyyMMdd.HHmmss-<build>}. */
private static final Pattern TIMESTAMPED = Pattern.compile("^(.+)-(\\d{8}\\.\\d{6})-(\\d+)$");
/** The parts of a coordinate: no whitespace, no empty part. */
private static final Pattern PART = Pattern.compile("[^:\\s]+");
/**
* Validates the parts.
*
* @throws IllegalArgumentException if a required part is blank
*/
KbKnowledgeSource {
for (String part : new String[]{groupId, artifactId, extension, version, pinnedVersion}) {
if (part == null || part.isBlank()) {
throw new IllegalArgumentException("A coordinate needs a groupId, artifactId,"
+ " extension and version: " + groupId + ":" + artifactId + ":"
+ extension + ":" + classifier + ":" + version);
}
}
classifier = classifier == null ? "" : classifier;
}
/**
* Reads a coordinate: {@code groupId:artifactId:extension:version} or
* {@code groupId:artifactId:extension:classifier:version}.
*
* @param spec the coordinate
* @return the unpinned knowledge source
* @throws IllegalArgumentException if the spec is not such a coordinate
*/
static KbKnowledgeSource parse(String spec) {
if (spec == null || spec.isBlank()) {
throw new IllegalArgumentException("An empty coordinate");
}
String[] parts = spec.strip().split(":", -1);
for (String part : parts) {
if (!PART.matcher(part).matches()) {
throw new IllegalArgumentException("Not a Maven coordinate: " + spec);
}
}
return switch (parts.length) {
case 4 -> new KbKnowledgeSource(parts[0], parts[1], parts[2], "", parts[3], parts[3], -1);
case 5 -> new KbKnowledgeSource(parts[0], parts[1], parts[2], parts[3], parts[4], parts[4], -1);
default -> throw new IllegalArgumentException("Not groupId:artifactId:extension[:classifier]:version: " + spec);
};
}
/**
* Whether a spec reads as a Maven coordinate rather than a file path.
*
* @param spec the spec
* @return {@code true} for a coordinate
*/
static boolean isCoordinate(String spec) {
if (spec == null || spec.contains("/") || spec.contains("\\")) {
return false;
}
try {
parse(spec);
return true;
} catch (IllegalArgumentException notACoordinate) {
return false;
}
}
/**
* This knowledge source pinned to an exact version, with its size.
*
* @param exactVersion the exact version
* @param bytes the size on the repository
* @return the pinned knowledge source
*/
KbKnowledgeSource pinned(String exactVersion, long bytes) {
return new KbKnowledgeSource(groupId, artifactId, extension, classifier, version, exactVersion, bytes);
}
/**
* Whether the requested version is a snapshot, timestamped or not.
*
* @return {@code true} for a snapshot
*/
boolean snapshot() {
return version.endsWith("-SNAPSHOT") || TIMESTAMPED.matcher(version).matches();
}
/**
* Whether the requested version already names one deploy.
*
* @return {@code true} for a release or a timestamped snapshot
*/
boolean exact() {
return !version.endsWith("-SNAPSHOT");
}
/**
* The folder a version lives in on a Maven repository: a timestamped snapshot lives
* under its {@code -SNAPSHOT} base version.
*
* @param anyVersion a version of this artifact
* @return the folder's version
*/
static String baseVersion(String anyVersion) {
Matcher timestamped = TIMESTAMPED.matcher(anyVersion);
return timestamped.matches() ? timestamped.group(1) + "-SNAPSHOT" : anyVersion;
}
/**
* The repository path of the artifact's folder for its requested version, ending in
* {@code /}.
*
* @return such as {@code network/ike/data/snomedct-kb/20260601.2-SNAPSHOT/}
*/
String folderPath() {
return groupId.replace('.', '/') + "/" + artifactId + "/" + baseVersion(version) + "/";
}
/**
* The repository path of the artifact's file at its pinned version.
*
* @return such as {@code network/ike/data/snomedct-kb/20260601.2-SNAPSHOT/snomedct-kb-20260601.2-20261111.020518-1-unreasoned-pb.zip}
*/
String filePath() {
return folderPath() + artifactId + "-" + pinnedVersion
+ (classifier.isEmpty() ? "" : "-" + classifier) + "." + extension;
}
/**
* The coordinate at the pinned version, as a {@code kb-assemble} input names it.
*
* @return {@code groupId:artifactId:extension[:classifier]:pinnedVersion}
*/
String coordinate() {
return coordinate("${" + versionProperty() + "}");
}
/**
* The coordinate with a chosen version text.
*
* @param versionText the version, or a property reference to it
* @return {@code groupId:artifactId:extension[:classifier]:versionText}
*/
String coordinate(String versionText) {
return groupId + ":" + artifactId + ":" + extension
+ (classifier.isEmpty() ? "" : ":" + classifier) + ":" + versionText;
}
/**
* The typed-marker property that pins this knowledge source's version, as
* {@code ike-version-management-extension} names it.
*
* @return {@code <groupId>__GA__<artifactId>__VERSION}
*/
String versionProperty() {
return groupId + "__GA__" + artifactId + "__VERSION";
}
/**
* Whether this knowledge source is the IKE starter set.
*
* @return {@code true} for {@code network.ike.foundation:ike-starter-set}
*/
boolean starterSet() {
return STARTER_SET_GROUP.equals(groupId) && STARTER_SET_ARTIFACT.equals(artifactId);
}
/**
* Whether this knowledge source is a classified, standalone protobuf.
*
* @return {@code true} for the {@code reasoned-pb} classifier
*/
boolean reasoned() {
return REASONED.equals(classifier);
}
/**
* Whether this knowledge source is an unclassified protobuf.
*
* @return {@code true} for the {@code unreasoned-pb} classifier
*/
boolean unreasoned() {
return UNREASONED.equals(classifier);
}
}