KbAssembleMojo.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 network.ike.knowledge.spi.ArtifactInput;
import network.ike.knowledge.spi.AssembleRequest;
import network.ike.knowledge.spi.AssembleResult;
import network.ike.knowledge.spi.IkeServiceBootstrap;
import network.ike.knowledge.spi.KnowledgeBaseAssembler;
import network.ike.knowledge.spi.ViewSpec;
import org.apache.maven.api.ProducedArtifact;
import org.apache.maven.api.Project;
import org.apache.maven.api.Session;
import org.apache.maven.api.di.Inject;
import org.apache.maven.api.model.DistributionManagement;
import org.apache.maven.api.services.ProjectManager;
import org.apache.maven.api.plugin.MojoException;
import org.apache.maven.api.plugin.annotations.Mojo;
import org.apache.maven.api.plugin.annotations.Parameter;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Properties;
/**
* Assembles a knowledge base from ordered knowledge artifacts — base data plus change
* sets into a store, classified by default — optionally exports the classified store
* as a standalone {@code reasoned-pb} artifact (IKE-Network/ike-issues#933), and
* optionally installs it into a
* data-source directory a knowledge browser reads. The full-cycle goal: a starter set
* becomes an openable, navigable KB in one build (IKE-Network/ike-issues#848, #850).
*
* <p>The goal is a thin face over the knowledge-pipeline SPI: it builds a typed
* {@link AssembleRequest}, and the {@link KnowledgeBaseAssembler} implementation is
* resolved by ServiceLoader from the <em>project's</em> runtime classpath inside a
* forked seam — declare {@code network.ike.knowledge:ike-knowledge-provider} at the use
* site (or rely on the parent POM's default wiring).
*
* <p>Inputs are ordered {@code ROLE spec} entries: the role is {@code STORE_SEED}
* (first position only), {@code PB}, {@code CHANGESET}, or {@code SOURCE}; the spec is
* either a Maven coordinate ({@code groupId:artifactId[:extension[:classifier]]:version},
* resolved from the repositories) or a file path — captured verification change sets
* feed the next iteration as file inputs. A {@code SOURCE} entry is
* {@code SOURCE importer spec [name=value ...]}: a source release (a file, a directory,
* or a coordinate) written into the store by the named knowledge importer
* ({@code dev.ikm.tinkar:importer-api}), which the project's runtime classpath carries:
*
* <pre>{@code
* <inputs>
* <input>PB network.ike.foundation:ike-starter-set:zip:unreasoned-pb:1-SNAPSHOT</input>
* <input>SOURCE snomed-rf2 ${snomed.release} release=full</input>
* <input>CHANGESET ${project.basedir}/../my-changeset/target/my-changeset.zip</input>
* </inputs>
* }</pre>
*
* @since 235
*/
@Mojo(name = IkeGoal.NAME_KB_ASSEMBLE,
defaultPhase = "package")
public class KbAssembleMojo implements org.apache.maven.api.plugin.Mojo {
/** Creates this goal instance. */
public KbAssembleMojo() {}
@Inject
private org.apache.maven.api.plugin.Log log;
/**
* Access the Maven logger.
*
* @return the logger
*/
protected org.apache.maven.api.plugin.Log getLog() {
return log;
}
@Inject
private Session session;
@Inject
private Project project;
/**
* The ordered knowledge inputs, each {@code ROLE spec} — role
* {@code STORE_SEED | PB | CHANGESET | SOURCE} (a source adds its importer before the
* spec and options after it), spec a Maven coordinate
* ({@code g:a[:extension[:classifier]]:v}) or a file path. List order is load
* order; the base comes first.
*/
@Parameter
List<String> inputs = List.of();
/**
* The store root to assemble into.
*/
@Parameter(property = "ike.kbAssemble.storeRoot",
defaultValue = "${project.build.directory}/kb")
String storeRoot;
/**
* Delete the store root before assembling — the default, so every build assembles
* the declared knowledge-state from scratch.
*/
@Parameter(property = "ike.kbAssemble.cleanStart", defaultValue = "true")
boolean cleanStart;
/**
* Run classification as the final assembly step — the default posture; the
* assembled KB is navigable the moment a browser opens it.
*/
@Parameter(property = "ike.kbAssemble.classify", defaultValue = "true")
boolean classify;
/**
* The reasoner service's simple class name, when the classpath carries several.
*/
@Parameter(property = "ike.kbAssemble.reasonerService")
String reasonerService;
/**
* A directory to install the assembled store into — for example a data-source
* directory a knowledge browser reads ({@code ${user.home}/Solor/<name>}).
* Replaced wholesale on each install; change sets captured in it are harvested first
* (see {@link #changeSetDirectory}) or the install is refused.
*/
@Parameter(property = "ike.kbAssemble.installDirectory")
String installDirectory;
/**
* The project directory that keeps the change sets authored in the installed knowledge
* base. Before the install is replaced, every change set captured there that the
* directory lacks is copied into it; then every change set it keeps is replayed, in
* name order, as a {@code CHANGESET} input after the configured inputs. Commit the
* directory: it is the knowledge base's extension, the content no source release carries.
*/
@Parameter(property = "ike.kbAssemble.changeSetDirectory")
String changeSetDirectory;
/**
* Replace an installed knowledge base holding captured change sets without harvesting
* them, when no {@link #changeSetDirectory} is set. The change sets are lost.
*/
@Parameter(property = "ike.kbAssemble.discardChangeSets", defaultValue = "false")
boolean discardChangeSets;
/**
* The extension's modules, by UUID. When set, only a captured change set whose stamps
* reference one of them is harvested; the rest (what a browser writes on its own: plugin
* bootstraps, assistant conversations) are parked in {@code <installDirectory>-sessions}
* beside the store, kept but not replayed. Unset, every captured change set is harvested.
*/
@Parameter
List<String> changeSetModules = List.of();
/**
* Replay the change sets {@link #changeSetDirectory} keeps. Off when another module
* merges them into an artifact this assembly loads as an input: the directory is then
* only where captured change sets are harvested, which still guards the install.
*/
@Parameter(property = "ike.kbAssemble.replayChangeSets", defaultValue = "true")
boolean replayChangeSets;
/**
* Write the koncepts YAML of the assembled knowledge base's extension here: the concepts
* and patterns with a version in one of {@link #konceptsModules}, read from the whole
* classified store so a concept authored under a release's concept keeps its parent's
* name. Commit it beside the extension: it is the extension's readable form.
*/
@Parameter(property = "ike.kbAssemble.konceptsYmlFile")
String konceptsYmlFile;
/** The extension's modules, by UUID, for {@link #konceptsYmlFile}. */
@Parameter
List<String> konceptsModules = List.of();
/**
* Export what the {@code SOURCE} inputs wrote, and only that, to this file: every version
* under a stamp an import created, unclassified, its references to the inputs before it by
* public id. One source's artifact, layered on its base; attached under
* {@link #sourceDeltaClassifier}.
*/
@Parameter(property = "ike.kbAssemble.sourceDeltaFile")
String sourceDeltaFile;
/** The classifier the source delta is attached under; blank leaves it unattached. */
@Parameter(property = "ike.kbAssemble.sourceDeltaClassifier", defaultValue = "unreasoned-pb")
String sourceDeltaClassifier;
/**
* Export the classified store as a full standalone reasoned protobuf — the
* {@code reasoned-pb} classifier form, inferred results baked in, ready to open
* without a reasoner run (IKE-Network/ike-issues#933). Requires {@link #classify}.
*/
@Parameter(property = "ike.kbAssemble.reasonedPb", defaultValue = "false")
boolean reasonedPb;
/**
* The reasoned-protobuf export file. When unset and {@link #reasonedPb} is true,
* defaults to {@code <buildDirectory>/<artifactId>-<version>-reasoned-pb.zip}.
* Setting this implies {@link #reasonedPb}.
*/
@Parameter(property = "ike.kbAssemble.reasonedPbFile")
String reasonedPbFile;
/**
* Attach the reasoned-protobuf export to the project under the
* {@code reasoned-pb} classifier (extension {@code zip}), so it installs and
* deploys with the module.
*/
@Parameter(property = "ike.kbAssemble.attachReasonedPb", defaultValue = "true")
boolean attachReasonedPb;
/**
* The view specification's dotted dimension keys (IKE-KNOWLEDGE-VIEW), stating only
* what differs from the implementation's defaults.
*/
@Parameter
Map<String, String> view = Map.of();
/**
* The knowledge-service implementation's simple class name, when the classpath
* carries several.
*/
@Parameter(property = "ike.kbAssemble.implementation")
String implementation;
/**
* Fork the seam (the default posture). Disable only for debugging.
*/
@Parameter(property = "ike.kbAssemble.fork", defaultValue = "true")
boolean fork;
/**
* Extra child-JVM arguments for the forked seam (heap, flags). The child inherits
* {@code --enable-preview} from the Maven JVM automatically.
*/
@Parameter
List<String> forkJvmArguments = List.of();
/**
* The project's classes/resources directory, included on the seam classpath.
*/
@Parameter(property = "ike.kbAssemble.classesDirectory",
defaultValue = "${project.build.outputDirectory}")
String classesDirectory;
/**
* The build directory hosting the seam's request/result files.
*/
@Parameter(property = "ike.kbAssemble.buildDirectory",
defaultValue = "${project.build.directory}")
String buildDirectory;
/**
* Write what the store is into it, in the files any Maven or JDK tool reads: the Maven
* descriptor {@code META-INF/maven/<groupId>/<artifactId>/pom.properties} and
* {@code pom.xml}, the {@code Ike-*} attributes of {@code META-INF/MANIFEST.MF}, and the
* knowledge-base descriptor {@code META-INF/ike/knowledge-base.properties} (level 1) with its
* icon. Written into the store root, so every zip made from it carries them, and into the
* install directory; the descriptor and icon are attached as {@code properties:kb-descriptor}
* and {@code png:icon}.
*/
@Parameter(property = "ike.kbAssemble.descriptor", defaultValue = "true")
boolean descriptor;
/**
* The groupId of the coordinate the store is a build of, for its Maven descriptor.
*/
@Parameter(property = "ike.kbAssemble.descriptorGroupId", defaultValue = "${project.groupId}")
String descriptorGroupId;
/**
* The artifactId of the coordinate the store is a build of, for its Maven descriptor —
* the project its zips publish under, as {@code ike:knowledge-attach}'s
* {@code targetArtifactId} names it when a subproject assembles the store. Its version and
* POM are that reactor project's.
*/
@Parameter(property = "ike.kbAssemble.descriptorArtifactId", defaultValue = "${project.artifactId}")
String descriptorArtifactId;
/**
* Who may download the knowledge base, for its descriptor: {@code public} or
* {@code restricted}. When unset, restricted when the project deploys to a repository whose id
* or URL says restricted, as licensed knowledge bases do, else public.
*/
@Parameter(property = "ike.kbAssemble.access")
String access;
/**
* The collection the knowledge base belongs to, for its descriptor, such as {@code SOLOR}: the
* knowledge bases one pipeline builds and publishes together, which the IKE Dashboard keeps at
* hand whether or not they are downloaded. Set once per project as the
* {@code ike.kbAssemble.collection} property, so every store it assembles says the same. When
* unset, the descriptor names none.
*/
@Parameter(property = "ike.kbAssemble.collection")
String collection;
/**
* Skip knowledge-base assembly.
*/
@Parameter(property = "ike.kbAssemble.skip", defaultValue = "false")
boolean skip;
/**
* Resolves the ordered inputs, builds the typed assembly request, and runs the
* {@link KnowledgeBaseAssembler} across the forked seam.
*
* @throws MojoException if an input cannot be parsed or resolved, the seam fails,
* or the store was not produced
*/
@Override
public void execute() {
if (skip) {
getLog().info("ike:kb-assemble skipped (ike.kbAssemble.skip=true)");
return;
}
if (inputs.isEmpty()) {
throw new MojoException("ike:kb-assemble requires at least one <inputs><input> entry"
+ " (ROLE followed by a Maven coordinate or file path)");
}
Optional<Path> reasonedPbTarget = reasonedPbTarget();
List<ArtifactInput> resolvedInputs = new ArrayList<>(resolveInputs());
resolvedInputs.addAll(changeSetInputs());
AssembleRequest request = new AssembleRequest(
Path.of(storeRoot), cleanStart, resolvedInputs, ViewSpec.of(view), classify,
Optional.ofNullable(reasonerService).filter(s -> !s.isBlank()),
Optional.ofNullable(installDirectory).filter(s -> !s.isBlank()).map(Path::of),
reasonedPbTarget,
Optional.ofNullable(konceptsYmlFile).filter(s -> !s.isBlank()).map(Path::of),
konceptsModules.stream().map(String::strip).collect(java.util.stream.Collectors.toSet()),
Optional.ofNullable(sourceDeltaFile).filter(s -> !s.isBlank()).map(Path::of));
Properties wire = request.toProperties();
if (implementation != null && !implementation.isBlank()) {
wire.setProperty(IkeServiceBootstrap.IMPLEMENTATION_KEY, implementation);
}
Properties resultWire = new KnowledgeServiceRunner(getLog()).run(
KnowledgeBaseAssembler.class.getName(), wire, seamClasspath(),
Path.of(buildDirectory, "ike-knowledge"), fork, forkJvmArguments);
AssembleResult result = AssembleResult.fromProperties(resultWire);
if (!Files.isDirectory(Path.of(storeRoot))) {
throw new MojoException("Knowledge-base assembly produced no store at " + storeRoot);
}
// A source's importer reports what it wrote in the summary's name, not entities by kind.
result.loads().forEach(load -> getLog().info(load.counts().total() == 0
? "Imported " + load.artifact()
: "Loaded " + load.artifact() + " — "
+ load.counts().total() + " entities (" + load.counts().concepts()
+ " concepts, " + load.counts().semantics() + " semantics, "
+ load.counts().patterns() + " patterns, " + load.counts().stamps() + " stamps)"));
result.classification().ifPresentOrElse(
summary -> getLog().info("Classified by " + summary.service() + ": "
+ summary.conceptCount() + " concepts, " + summary.inferredChanges()
+ " inferred changes, " + summary.navigationChanges()
+ " navigation changes in " + summary.elapsedMillis() + " ms"),
() -> getLog().info("Classification skipped by request"));
result.effectiveViewReport().ifPresent(report ->
getLog().info("Effective view reported: " + report));
List<KnowledgeBaseDescriptor.Input> assembledFrom = descriptor ? describe(result, resolvedInputs)
: descriptorInputs(resolvedInputs, descriptorGroupId, descriptorArtifactId, project.getVersion());
if (installDirectory != null && !installDirectory.isBlank()) {
getLog().info("Knowledge base installed: " + installDirectory);
}
if (sourceDeltaFile != null && !sourceDeltaFile.isBlank()) {
Path delta = Path.of(sourceDeltaFile);
if (!Files.isRegularFile(delta)) {
throw new MojoException("Source delta export produced no file at " + delta);
}
getLog().info("Source delta exported: " + delta.getFileName());
if (sourceDeltaClassifier != null && !sourceDeltaClassifier.isBlank()) {
ProducedArtifact artifact = session.createProducedArtifact(project.getGroupId(),
project.getArtifactId(), project.getVersion(), sourceDeltaClassifier, "zip", "zip");
session.getService(ProjectManager.class).attachArtifact(project, artifact, delta);
getLog().info("Attached source delta " + delta.getFileName() + " (classifier: " + sourceDeltaClassifier + ")");
}
}
if (reasonedPbTarget.isPresent()) {
Path produced = result.reasonedPbFile().orElseThrow(() -> new MojoException(
"Reasoned-protobuf export was requested but the assembly reported none"));
if (!Files.isRegularFile(produced)) {
throw new MojoException("Reasoned-protobuf export produced no file at " + produced);
}
getLog().info("Reasoned knowledge set exported: " + produced.getFileName());
try {
// A store loaded from the export names these as its own inputs (descriptorInputs).
Path record = KnowledgeBaseDescriptor.writeInputs(produced, assembledFrom);
getLog().info("Recorded what it was assembled from: " + record.getFileName()
+ " (" + assembledFrom.size() + " input(s))");
} catch (IOException e) {
throw new MojoException("Cannot record the inputs of " + produced, e);
}
if (attachReasonedPb) {
ProducedArtifact artifact = session.createProducedArtifact(
project.getGroupId(), project.getArtifactId(), project.getVersion(),
"reasoned-pb", "zip", "zip");
session.getService(ProjectManager.class).attachArtifact(project, artifact, produced);
getLog().info("Attached reasoned knowledge export " + produced.getFileName()
+ " (classifier: reasoned-pb, extension: zip)");
}
}
}
/**
* The heap the assembly measured of itself, for the build log: the seam passes on only the
* provider's warnings, so the measurement is reported here, from the manifest attributes it left.
*
* @param memory the memory facts, by descriptor entry ({@link KnowledgeBaseDescriptor#memory})
* @return the report, or empty when the assembly measured no heap
*/
static Optional<String> heapReport(Map<String, Long> memory) {
Long loaded = memory.get("loadedHeapBytes");
if (loaded == null) {
return Optional.empty();
}
StringBuilder report = new StringBuilder("Heap measured: ").append(loaded >> 20)
.append(" MB live with the store loaded");
Optional.ofNullable(memory.get("reasonerHeapBytes")).ifPresentOrElse(
reasoner -> report.append(", ").append(reasoner >> 20)
.append(" MB more while the reasoner holds its model"),
() -> report.append(", the reasoner not measured"));
Optional.ofNullable(memory.get("reasonerHeapUpperBytes")).ifPresent(upper -> report
.append(" (at most ").append(upper >> 20).append(" MB after any collection while it ran)"));
Optional.ofNullable(memory.get("statedAxiomBytes")).ifPresent(stated -> report
.append("; stated axioms ").append(stated >> 20).append(" MB"));
return Optional.of(report.toString());
}
/**
* Writes the Maven descriptor, the manifest, and the knowledge-base descriptor with its icon
* into the store root and the install directory, and attaches the descriptor and the icon so
* they deploy beside the store zips. The coordinate is the reactor project
* {@link #descriptorArtifactId} names; when that project is not in this build ({@code -pl}
* alone), this project's version stands in and no POM is copied.
*
* @param result what the assembly reported
* @param assembledFrom the inputs the assembly took, in order
* @return the inputs as the descriptor records them
*/
private List<KnowledgeBaseDescriptor.Input> describe(AssembleResult result, List<ArtifactInput> assembledFrom) {
Project described = project.getGroupId().equals(descriptorGroupId)
&& project.getArtifactId().equals(descriptorArtifactId)
? project
: session.getProjects().stream()
.filter(candidate -> candidate.getGroupId().equals(descriptorGroupId)
&& candidate.getArtifactId().equals(descriptorArtifactId))
.findFirst().orElse(null);
if (described == null) {
getLog().warn("Descriptor project " + descriptorGroupId + ":" + descriptorArtifactId
+ " is not in this build; describing the store with this project's version and no POM");
}
String version = described != null ? described.getVersion() : project.getVersion();
Optional<Path> pom = Optional.ofNullable(described).map(Project::getPomPath).filter(Files::isRegularFile);
Project owner = described != null ? described : project;
Instant assembledAt = Instant.now();
Map<String, String> attributes = new LinkedHashMap<>();
attributes.put(StoreDescriptor.LAUNCH_INTERFACE_VERSION, StoreDescriptor.LAUNCH_INTERFACE);
attributes.put(StoreDescriptor.ASSEMBLED_AT, assembledAt.toString());
result.classification().ifPresent(summary -> attributes.put(StoreDescriptor.REASONER, summary.service()));
// What only the implementation knows about the store (its controller, layout, the
// assembly it registered) is reported in the result and wins over the goal's own.
attributes.putAll(result.storeAttributes());
String displayName = Optional.ofNullable(owner.getModel().getName()).map(String::strip)
.filter(name -> !name.isEmpty()).orElse(descriptorArtifactId);
KnowledgeBaseDescriptor.Fields fields = new KnowledgeBaseDescriptor.Fields(descriptorGroupId,
descriptorArtifactId, version, displayName, entityFormat(attributes), assembledAt, access(owner),
KnowledgeBaseDescriptor.memory(attributes), Optional.ofNullable(collection),
descriptorInputs(assembledFrom, descriptorGroupId, descriptorArtifactId, version));
heapReport(fields.memory()).ifPresent(getLog()::info);
Path icon = knowledgeBaseIcon(owner, displayName);
List<Path> stores = new ArrayList<>(List.of(Path.of(storeRoot)));
Optional.ofNullable(installDirectory).filter(s -> !s.isBlank()).map(Path::of)
.filter(Files::isDirectory).ifPresent(stores::add);
String createdBy = createdBy();
Path written = null;
for (Path store : stores) {
try {
StoreDescriptor.write(store, descriptorGroupId, descriptorArtifactId, version, pom, createdBy,
attributes);
Path file = KnowledgeBaseDescriptor.write(store, fields, icon);
written = written == null ? file : written;
} catch (IOException e) {
throw new MojoException("Cannot describe the store at " + store, e);
}
}
getLog().info("Described the store as " + descriptorGroupId + ":" + descriptorArtifactId + ":" + version
+ " (" + attributes.size() + " manifest attributes; knowledge-base descriptor level "
+ KnowledgeBaseDescriptor.LEVEL + ", " + fields.access().value()
+ fields.collection().map(name -> ", collection " + name).orElse("") + ", "
+ fields.inputs().size() + " input(s))");
attachOnce(owner, KnowledgeBaseDescriptor.CLASSIFIER, "properties", written);
attachOnce(owner, KnowledgeBaseDescriptor.ICON_CLASSIFIER, "png", icon);
return fields.inputs();
}
/**
* The entity format the store was written in: as the assembly reported it, else as the store's
* own files record it.
*/
private int entityFormat(Map<String, String> attributes) {
String reported = attributes.get("Ike-Entity-Format");
try {
if (reported != null) {
return Integer.parseInt(reported.strip());
}
return KnowledgeBaseDescriptor.recordedEntityFormat(Path.of(storeRoot)).orElseThrow(() -> new MojoException(
"The assembly reported no entity format and the store at " + storeRoot + " records none;"
+ " the knowledge-base descriptor requires one"));
} catch (NumberFormatException e) {
throw new MojoException("The assembly reported an entity format that is not a number: " + reported, e);
} catch (IOException e) {
throw new MojoException("Cannot read the store's format at " + storeRoot, e);
}
}
/**
* Who may download the knowledge base: {@link #access} when set, else restricted when the
* project deploys to a restricted repository, as licensed knowledge bases do, else public.
*/
private KnowledgeBaseDescriptor.Access access(Project owner) {
if (access != null && !access.isBlank()) {
try {
return KnowledgeBaseDescriptor.Access.valueOf(access.strip().toUpperCase(java.util.Locale.ROOT));
} catch (IllegalArgumentException e) {
throw new MojoException("ike.kbAssemble.access is public or restricted, not " + access, e);
}
}
DistributionManagement distribution = owner.getModel().getDistributionManagement();
boolean restricted = distribution != null && java.util.stream.Stream
.of(distribution.getRepository(), distribution.getSnapshotRepository())
.filter(java.util.Objects::nonNull)
.anyMatch(repository -> mentionsRestricted(repository.getId()) || mentionsRestricted(repository.getUrl()));
return restricted ? KnowledgeBaseDescriptor.Access.RESTRICTED : KnowledgeBaseDescriptor.Access.PUBLIC;
}
private static boolean mentionsRestricted(String text) {
return text != null && text.toLowerCase(java.util.Locale.ROOT).contains("restricted");
}
/**
* The knowledge base's icon: the project's own at {@code src/main/kb/icon.png}, else a
* monogram of its display name, drawn into the build directory.
*/
private Path knowledgeBaseIcon(Project owner, String displayName) {
Optional<Path> own = KnowledgeBaseDescriptor.icon(owner.getBasedir());
if (own.isPresent()) {
return own.get();
}
try {
return KnowledgeBaseMonogram.write(Path.of(buildDirectory, "ike-kb-icon"), displayName, descriptorArtifactId);
} catch (IOException e) {
throw new MojoException("Cannot draw the knowledge base's monogram icon", e);
}
}
/**
* Attaches a file as {@code <artifactId>:<version>:<extension>:<classifier>}, so it deploys
* beside the store zips; a project that assembles more than one store attaches it once, from
* the first.
*/
private void attachOnce(Project owner, String classifier, String extension, Path file) {
ProjectManager projectManager = session.getService(ProjectManager.class);
boolean attached = projectManager.getAttachedArtifacts(owner).stream()
.anyMatch(artifact -> classifier.equals(artifact.getClassifier()) && extension.equals(artifact.getExtension()));
if (!attached) {
ProducedArtifact artifact = session.createProducedArtifact(owner.getGroupId(),
owner.getArtifactId(), owner.getVersion(), classifier, extension, extension);
projectManager.attachArtifact(owner, artifact, file);
getLog().info("Attached " + file.getFileName() + " (classifier: " + classifier + ", extension: " + extension + ")");
}
}
/**
* This plugin and its version, for the store manifest's {@code Created-By}; the name alone
* when the plugin runs from classes rather than its jar, which carries the version.
*/
private static String createdBy() {
try {
return "ike-maven-plugin " + StarterSetCreateSupport.pluginVersion();
} catch (MojoException e) {
return "ike-maven-plugin";
}
}
/**
* The reasoned-protobuf export target: the explicit {@link #reasonedPbFile} when
* set, the conventional {@code <artifactId>-<version>-reasoned-pb.zip} under the
* build directory when {@link #reasonedPb} asked for one, empty otherwise.
*
* @return the export target, when an export was requested
*/
private Optional<Path> reasonedPbTarget() {
if (reasonedPbFile != null && !reasonedPbFile.isBlank()) {
return Optional.of(Path.of(reasonedPbFile));
}
if (reasonedPb) {
return Optional.of(Path.of(buildDirectory).resolve(
project.getArtifactId() + "-" + project.getVersion() + "-reasoned-pb.zip"));
}
return Optional.empty();
}
/**
* The inputs as the knowledge-base descriptor records them: each coordinate as written, with
* the version it resolved to when that differs, and each file by name. A file an earlier
* assembly exported, such as the reasoned protobuf a store is loaded from, is recorded as
* what that assembly took ({@link KnowledgeBaseDescriptor#recordedInputs}), so every store of
* a knowledge base names the same knowledge bases and sources. Without that record, a file
* that is an artifact of the described knowledge base itself is recorded as that artifact's
* coordinate.
*
* @param inputs the inputs, in the order the assembly took them
* @param groupId the described knowledge base's groupId
* @param artifactId the described knowledge base's artifactId
* @param version the described knowledge base's version
* @return the descriptor's inputs
*/
static List<KnowledgeBaseDescriptor.Input> descriptorInputs(List<ArtifactInput> inputs, String groupId,
String artifactId, String version) {
String ownPrefix = artifactId + "-" + version + "-";
List<KnowledgeBaseDescriptor.Input> recorded = new ArrayList<>();
for (ArtifactInput input : inputs) {
String reference;
Optional<String> resolved = Optional.empty();
if (input.coordinate().isPresent()) {
reference = input.coordinate().get();
resolved = input.resolvedVersion().filter(resolvedVersion -> !reference.endsWith(":" + resolvedVersion));
} else {
List<KnowledgeBaseDescriptor.Input> exportedFrom;
try {
exportedFrom = KnowledgeBaseDescriptor.recordedInputs(input.path());
} catch (IOException e) {
throw new MojoException("Cannot read the inputs recorded beside " + input.path(), e);
}
if (!exportedFrom.isEmpty()) {
recorded.addAll(exportedFrom);
continue;
}
String name = input.path().getFileName().toString();
reference = name.startsWith(ownPrefix) && name.endsWith(".zip")
? groupId + ":" + artifactId + ":zip:"
+ name.substring(ownPrefix.length(), name.length() - ".zip".length()) + ":" + version
: "file:" + name;
}
recorded.add(new KnowledgeBaseDescriptor.Input(input.role().name(), reference, resolved, input.importer()));
}
return recorded;
}
/**
* Harvests the installed knowledge base's captured change sets into the change-set
* directory, and returns every change set kept there as an input. Without a change-set
* directory, an install holding captured change sets is refused unless discarding them
* was asked for: the install replaces the store, and them with it.
*/
private List<ArtifactInput> changeSetInputs() {
List<Path> captured = Optional.ofNullable(installDirectory).filter(s -> !s.isBlank()).map(Path::of)
.map(ChangeSetHarvest::captured).orElse(List.of());
if (changeSetDirectory == null || changeSetDirectory.isBlank()) {
if (!captured.isEmpty() && !discardChangeSets) {
throw new MojoException("The installed knowledge base " + installDirectory + " holds "
+ captured.size() + " captured change set(s) the install would destroy: " + captured
+ ". Set <changeSetDirectory> to harvest and replay them, or"
+ " -Dike.kbAssemble.discardChangeSets=true to replace the store without them.");
}
return List.of();
}
Path directory = Path.of(changeSetDirectory);
if (!changeSetModules.isEmpty() && !captured.isEmpty()) {
Path parking = Path.of(installDirectory + "-sessions");
List<Path> extension = ChangeSetHarvest.sortOut(captured,
changeSetModules.stream().map(String::strip).collect(java.util.stream.Collectors.toSet()), parking);
if (extension.size() < captured.size()) {
getLog().info("Parked " + (captured.size() - extension.size()) + " change set(s) with no content in "
+ changeSetModules + " in " + parking);
}
captured = extension;
}
List<Path> harvested = ChangeSetHarvest.harvest(captured, directory);
harvested.forEach(file -> getLog().info("Harvested change set " + file.getFileName() + " into " + directory));
if (!replayChangeSets) {
return List.of();
}
List<Path> kept = ChangeSetHarvest.kept(directory);
if (!kept.isEmpty()) {
getLog().info("Replaying " + kept.size() + " change set(s) from " + directory);
}
return kept.stream().map(file -> new ArtifactInput(ArtifactInput.Role.CHANGESET, file)).toList();
}
private List<ArtifactInput> resolveInputs() {
List<ArtifactInput> resolved = new ArrayList<>();
for (String entry : inputs) {
String stripped = entry.strip();
int space = stripped.indexOf(' ');
if (space <= 0) {
throw new MojoException("Input entry needs \"ROLE spec\": " + entry);
}
ArtifactInput.Role role;
try {
role = ArtifactInput.Role.valueOf(stripped.substring(0, space));
} catch (IllegalArgumentException e) {
throw new MojoException("Unknown input role in \"" + entry
+ "\" — use STORE_SEED, PB, CHANGESET, or SOURCE", e);
}
String spec = stripped.substring(space + 1).strip();
if (role == ArtifactInput.Role.SOURCE) {
resolved.add(resolveSource(entry, spec));
} else {
resolved.add(withCoordinate(new ArtifactInput(role, resolveSpec(spec)), spec));
}
}
return resolved;
}
/**
* A source entry after its role: {@code importer spec [name=value ...]} — the knowledge
* importer's name, the release (a Maven coordinate, a file, or a directory), and the
* importer's options; a value with spaces is double-quoted ({@code author="IHTSDO SNOMED CT Author"}).
*/
private ArtifactInput resolveSource(String entry, String rest) {
String[] words = words(rest);
if (words.length < 2) {
throw new MojoException("A SOURCE input needs \"SOURCE importer spec [name=value ...]\": " + entry);
}
Map<String, String> options = new LinkedHashMap<>();
for (int i = 2; i < words.length; i++) {
int equals = words[i].indexOf('=');
if (equals <= 0) {
throw new MojoException("A SOURCE option is name=value, not \"" + words[i] + "\": " + entry);
}
options.put(words[i].substring(0, equals), words[i].substring(equals + 1));
}
String spec = words[1];
Path release = isCoordinate(spec) || !Files.isDirectory(Path.of(spec))
? resolveSpec(spec)
: Path.of(spec);
return withCoordinate(ArtifactInput.source(words[0], release, options), spec);
}
/**
* The input with the coordinate it was resolved from, when its spec is one: the assembly
* records it in the knowledge base (IKE-Network/ike-issues#1304).
*/
private ArtifactInput withCoordinate(ArtifactInput input, String spec) {
if (!isCoordinate(spec)) {
return input;
}
String version = resolvedVersions.get(spec);
return version != null ? input.withCoordinate(spec, version) : input.withCoordinate(spec);
}
/** The version each coordinate resolved to, by the coordinate as written. */
private final Map<String, String> resolvedVersions = new LinkedHashMap<>();
private static boolean isCoordinate(String spec) {
return spec.chars().filter(c -> c == ':').count() >= 2;
}
/**
* Splits on whitespace, keeping a double-quoted stretch whole and dropping its quotes:
* {@code a b="c d"} is {@code a} and {@code b=c d}.
*/
static String[] words(String text) {
List<String> words = new ArrayList<>();
StringBuilder word = new StringBuilder();
boolean quoted = false;
boolean any = false;
for (char c : text.strip().toCharArray()) {
if (c == '"') {
quoted = !quoted;
any = true;
} else if (Character.isWhitespace(c) && !quoted) {
if (any) {
words.add(word.toString());
word.setLength(0);
any = false;
}
} else {
word.append(c);
any = true;
}
}
if (quoted) {
throw new MojoException("Unbalanced quote in \"" + text + "\"");
}
if (any) {
words.add(word.toString());
}
return words.toArray(String[]::new);
}
/**
* A spec with two or more colons is a Maven coordinate
* ({@code g:a[:extension[:classifier]]:v}); anything else is a file path.
*/
private Path resolveSpec(String spec) {
if (isCoordinate(spec)) {
try {
org.apache.maven.api.DownloadedArtifact artifact =
session.resolveArtifact(session.createArtifactCoordinates(spec));
resolvedVersions.put(spec, artifact.getVersion().toString());
return artifact.getPath();
} catch (Exception e) {
throw new MojoException("Cannot resolve knowledge input " + spec, e);
}
}
Path file = Path.of(spec);
if (!Files.isRegularFile(file)) {
throw new MojoException("Knowledge input file does not exist: " + file
+ " — captured change sets must be present before assembly");
}
return file;
}
private List<Path> seamClasspath() {
// Resolution goes through the plugin's serialized entry point — Maven 4 rc-5's
// resolver cache is not thread-safe under -T (IKE-Network/ike-issues#901).
List<Path> classpath = new ArrayList<>();
Path classesDir = Path.of(classesDirectory);
if (Files.isDirectory(classesDir)) {
classpath.add(classesDir);
}
classpath.addAll(RuntimeClasspathResolver.mainRuntimePaths(session, project));
return classpath;
}
}