+ * {@code Compass} provides a single, discoverable access point to the library’s + * default parsers and default validators. + * It is intentionally lightweight and stateless, exposing only factory-style + * accessors grouped by concern. + *
+ * + *{@code
+ * // Parse a Level 2 Link Set
+ * var parser = Compass.parsers().linksetJson();
+ * List links = parser.parse(inputStream);
+ *
+ * // Validate using Level 2 recipe routing
+ * var validator = Compass.validators().level2Recipes();
+ * SignPostingResult result = validator.validate(links);
+ * }
+ *
+ * + * {@code Compass} itself performs no parsing or validation logic. All stateful + * behavior is delegated to the returned parser and validator instances. + *
+ * + *+ * Advanced users may bypass this facade entirely and work directly with: + *
+ *+ * This class exists solely as a convenience and does not restrict extensibility + * or customization. + *
+ * + * @since 1.0.0 + * @author Sven Fillinger + */ +public final class Compass { + + private Compass() {} + + /** + * Provides access to the default FAIR Signposting parsers. + * + *+ * The returned object acts as a logical namespace grouping all supported + * {@link LinkSetParser} implementations shipped with this library. + *
+ * + * @return a singleton accessor for parser factories + */ + public static Parsers parsers() { + return Parsers.INSTANCE; + } + + /** + * Provides access to the default FAIR Signposting validators. + * + *+ * The returned object acts as a logical namespace grouping all supported + * {@link SignPostingValidator} implementations shipped with this library. + *
+ * + * @return a singleton accessor for validator factories + */ + public static Validators validators() { + return Validators.INSTANCE; + } + + /** + * Namespace for FAIR Signposting parser factories. + * + *+ * Parsers are responsible for transforming serialized representations + * (e.g. HTTP {@code Link} headers, Link Set JSON) into {@link WebLink} + * objects suitable for validation and inspection. + *
+ * + *+ * All parsers returned by this class are stateless and may be reused + * across multiple parsing operations. + *
+ */ + public static final class Parsers { + + private static final Parsers INSTANCE = new Parsers(); + + private Parsers() {} + + /** + * Creates a parser for RFC 9264 JSON Link Sets. + * + *+ * This parser is intended for FAIR Signposting Level 2 discovery, + * where links for multiple resource contexts are provided together + * in a Link Set document. + *
+ * + * @return a {@link LinkSetParser} for JSON Link Sets + */ + public LinkSetParser linksetJson() { + return LinkSetJsonParser.create(); + } + + /** + * Creates a parser for inline {@code Link} headers and HTML {@code } elements. + * + *+ * This parser is typically used for FAIR Signposting Level 1, + * where typed links are provided directly with the resource response. + *
+ * + * @return a {@link LinkSetParser} for inline link representations + */ + public LinkSetParser linksetInline() { + return LinkSetInlineParser.create(); + } + } + + /** + * Namespace for FAIR Signposting validator factories. + * + *+ * Validators operate on parsed {@link WebLink} collections and produce + * {@link SignPostingResult} instances + * describing validation outcomes. + *
+ * + *+ * Validators returned by this class are independent and stateless; + * clients may freely compose or replace them. + *
+ */ + public static final class Validators { + + private static final Validators INSTANCE = new Validators(); + + private Validators() {} + + /** + * Creates a validator for FAIR Signposting Level 1. + * + *+ * This validator enforces the mandatory Level 1 landing page + * recipe and emits warnings for recommended relations. + *
+ * + * @return a Level 1 {@link SignPostingValidator} + */ + public SignPostingValidator level1() { + return Level1SignPostingValidator.create(); + } + + /** + * Creates a validator that routes FAIR Signposting Level 2 recipes + * automatically per origin (anchor). + * + *+ * This validator detects landing page, metadata resource, and content + * resource recipes using heuristics and delegates validation to the + * appropriate specialized validator. + *
+ * + * @return a Level 2 recipe-routing {@link SignPostingValidator} + */ + public SignPostingValidator level2Recipes() { + return Level2RecipeValidator.create(); + } + + /** + * Creates a validator for the FAIR Signposting Level 2 landing page recipe. + * + *+ * This validator should be used when the landing page context is known + * a priori and no heuristic routing is required. + *
+ * + * @return a landing page {@link SignPostingValidator} + */ + public SignPostingValidator level2LandingPage() { + return Level2LandingPageValidator.create(); + } + + /** + * Creates a validator for the FAIR Signposting Level 2 metadata resource recipe. + * + * @return a metadata resource {@link SignPostingValidator} + */ + public SignPostingValidator level2MetadataResource() { + return Level2MetadataResourceValidator.create(); + } + + /** + * Creates a validator for the FAIR Signposting Level 2 content resource recipe. + * + * @return a content resource {@link SignPostingValidator} + */ + public SignPostingValidator level2ContentResource() { + return Level2ContentResourceValidator.create(); + } + } +} diff --git a/src/main/java/life/qbic/compass/SignPostingProcessor.java b/src/main/java/life/qbic/compass/SignPostingProcessor.java index 9595818..cebe657 100644 --- a/src/main/java/life/qbic/compass/SignPostingProcessor.java +++ b/src/main/java/life/qbic/compass/SignPostingProcessor.java @@ -61,11 +61,63 @@ private SignPostingProcessor(List+ * Each validator is executed independently and receives the same + * input list. Validators are not allowed to mutate the input. + *
+ * + *+ * The processor is non-destructive with respect to non-null links. + * It does not reorder or modify WebLinks. However, {@code null} elements are + * filtered out before validation and before creating the returned + * {@link SignPostingView}, because {@code null} values cannot be represented safely + * in the view API. + *
+ * + *+ * As a result, the returned {@link SignPostingView} contains all non-null WebLinks + * from the input list, in their original order. + *
+ * This processor intentionally does not merge or expose any + * {@link life.qbic.compass.model.Level2LinksetView} instances returned by + * individual validators. If Level 2 structural views are required, + * clients should invoke the corresponding validator directly + * (e.g. {@code Level2RecipeValidator}). + * + * + *+ * Validators are executed in the order they are added to the builder. + *
+ * + *+ * If no validators are explicitly configured, the processor defaults to + * using {@link Level1SignPostingValidator}. + *
+ */ public static final class Builder { private List+ * Validators are appended in the order provided. + *
+ * + * @param validators one or more {@link SignPostingValidator}s + * @return this builder for fluent chaining + * @throws NullPointerException if {@code validators} is {@code null} + */ Builder withValidators(SignPostingValidator... validators) { return this.withValidators(Arrays.stream(validators).toList()); } + /** + * Adds a list of validators to this processor. + * + *+ * The provided list is not defensively copied until {@link #build()} is called. + *
+ * + * @param validators validators to add + * @return this builder for fluent chaining + * @throws NullPointerException if {@code validators} is {@code null} + */ Builder withValidators(List+ * If no validators were added, the processor is created with a single + * {@link Level1SignPostingValidator} as a sensible default. + *
+ * + * @return a configured {@link SignPostingProcessor} + */ SignPostingProcessor build() { if (validators.isEmpty()) { return new SignPostingProcessor(List.of(Level1SignPostingValidator.create())); diff --git a/src/main/java/life/qbic/compass/parsing/LinkSetInlineParser.java b/src/main/java/life/qbic/compass/parsing/LinkSetInlineParser.java index 20684f7..e6bfad9 100644 --- a/src/main/java/life/qbic/compass/parsing/LinkSetInlineParser.java +++ b/src/main/java/life/qbic/compass/parsing/LinkSetInlineParser.java @@ -2,7 +2,6 @@ import java.io.InputStream; import java.io.Reader; -import java.nio.charset.Charset; import java.util.List; import life.qbic.compass.spi.LinkSetParser; import life.qbic.linksmith.model.WebLink; @@ -12,7 +11,13 @@ * * @since* Implementations of this interface perform semantic checks on already parsed and - * RFC 8288–compliant WebLinks. They do not perform HTTP requests, content - * negotiation, or dereferencing of link targets. + * RFC 8288–compliant WebLinks. Validators do not perform HTTP requests, + * content negotiation, dereferencing of link targets, or parsing of {@code Link} headers / Link + * Sets. *
* - *- * A {@code SignPostingValidator}: - *
+ *- * Validators must be side effect free and should not modify the - * supplied list of WebLinks. + * Different validators may target different Signposting levels or recipes + * (e.g. Level 1, Level 2 Landing Page / Metadata Resource / Content Resource, + * or Level 2 discovery) and can be applied independently or in sequence by client code. *
* *- * Different validators may target different Signposting levels or profiles - * (e.g. Level 1, Level 2 discovery, or domain-specific extensions) and - * can be applied independently or in sequence by client code. + * Validators that operate on Level 2 Link Sets (i.e. collections of links describing + * multiple resource origins) may populate the optional + * {@link SignPostingResult#level2LinksetView()}. + * If present, it provides a structured, recipe-aware representation of the validated + * Link Set as a {@link life.qbic.compass.model.Level2LinksetView}. *
*/ public interface SignPostingValidator { diff --git a/src/main/java/life/qbic/compass/validation/Level1SignPostingValidator.java b/src/main/java/life/qbic/compass/validation/Level1SignPostingValidator.java index 632e59d..ecef617 100644 --- a/src/main/java/life/qbic/compass/validation/Level1SignPostingValidator.java +++ b/src/main/java/life/qbic/compass/validation/Level1SignPostingValidator.java @@ -68,7 +68,7 @@ * * @author Sven Fillinger */ -public class Level1SignPostingValidator implements SignPostingValidator { +public final class Level1SignPostingValidator implements SignPostingValidator { private Level1SignPostingValidator() { } diff --git a/src/main/java/life/qbic/compass/validation/Level2ContentResourceValidator.java b/src/main/java/life/qbic/compass/validation/Level2ContentResourceValidator.java index 0012c33..56bb9f7 100644 --- a/src/main/java/life/qbic/compass/validation/Level2ContentResourceValidator.java +++ b/src/main/java/life/qbic/compass/validation/Level2ContentResourceValidator.java @@ -66,7 +66,7 @@ * @since 1.0.0 * @author Sven Fillinger */ -public class Level2ContentResourceValidator implements SignPostingValidator { +public final class Level2ContentResourceValidator implements SignPostingValidator { /** Relation type {@code cite-as} used by FAIR Signposting. */ public static final String CITE_AS = "cite-as"; diff --git a/src/main/java/life/qbic/compass/validation/Level2DiscoveryValidator.java b/src/main/java/life/qbic/compass/validation/Level2DiscoveryValidator.java index ef6fa8c..b39d045 100644 --- a/src/main/java/life/qbic/compass/validation/Level2DiscoveryValidator.java +++ b/src/main/java/life/qbic/compass/validation/Level2DiscoveryValidator.java @@ -62,7 +62,7 @@ * * @author Sven Fillinger */ -public class Level2DiscoveryValidator implements SignPostingValidator { +public final class Level2DiscoveryValidator implements SignPostingValidator { private Level2DiscoveryValidator() { } diff --git a/src/main/java/life/qbic/compass/validation/Level2LandingPageValidator.java b/src/main/java/life/qbic/compass/validation/Level2LandingPageValidator.java index 30bfc19..a4b38ad 100644 --- a/src/main/java/life/qbic/compass/validation/Level2LandingPageValidator.java +++ b/src/main/java/life/qbic/compass/validation/Level2LandingPageValidator.java @@ -62,7 +62,7 @@ * @author Sven Fillinger * @since 1.0.0 */ -public class Level2LandingPageValidator implements SignPostingValidator { +public final class Level2LandingPageValidator implements SignPostingValidator { /** * Relation type {@code cite-as}. diff --git a/src/main/java/life/qbic/compass/validation/Level2MetadataResourceValidator.java b/src/main/java/life/qbic/compass/validation/Level2MetadataResourceValidator.java index 724418e..0a51537 100644 --- a/src/main/java/life/qbic/compass/validation/Level2MetadataResourceValidator.java +++ b/src/main/java/life/qbic/compass/validation/Level2MetadataResourceValidator.java @@ -75,7 +75,7 @@ * @author Sven Fillinger * @since 1.0.0 */ -public class Level2MetadataResourceValidator implements SignPostingValidator { +public final class Level2MetadataResourceValidator implements SignPostingValidator { /** * The relation type required by the Level 2 metadata resource recipe. diff --git a/src/main/java/life/qbic/compass/validation/Level2RecipeValidator.java b/src/main/java/life/qbic/compass/validation/Level2RecipeValidator.java index 98c51b8..3e9c1dd 100644 --- a/src/main/java/life/qbic/compass/validation/Level2RecipeValidator.java +++ b/src/main/java/life/qbic/compass/validation/Level2RecipeValidator.java @@ -14,8 +14,8 @@ import life.qbic.compass.model.Level2LinksetView; import life.qbic.compass.model.MetadataResourceView; import life.qbic.compass.model.MissingOriginLink; -import life.qbic.compass.model.SignPostingView; import life.qbic.compass.model.SignPostingResult; +import life.qbic.compass.model.SignPostingView; import life.qbic.compass.spi.SignPostingValidator; import life.qbic.linksmith.model.WebLink; import life.qbic.linksmith.spi.WebLinkValidator.Issue; @@ -111,6 +111,27 @@ * * * + *+ * The following aspects are not considered part of the stable API contract and may + * change between releases without notice: + *
+ *