From 83c650a2ad5e0d3931ad01b1f2e3d892ae243730 Mon Sep 17 00:00:00 2001 From: Laird Nelson Date: Fri, 10 Jan 2025 14:09:22 -0800 Subject: [PATCH] Adds documentation Signed-off-by: Laird Nelson --- pom.xml | 5 +- .../event/EventQualifiersMatcher.java | 46 ++++++++++- .../org/microbean/event/EventTypeMatcher.java | 59 ++++++++++++++ .../java/org/microbean/event/EventTypes.java | 81 ++++++++++++++++++- 4 files changed, 186 insertions(+), 5 deletions(-) diff --git a/pom.xml b/pom.xml index 5a1d207..52063f9 100644 --- a/pom.xml +++ b/pom.xml @@ -80,6 +80,7 @@ ${project.organization.name}. All rights reserved.]]> <a href="${project.url}" target="_top"><span style="font-family:Lobster, cursive;">µb</span> ${project.artifactId}</a> ${project.version} + https://microbean.github.io/microbean-assign/apidocs/,https://microbean.github.io/microbean-construct/apidocs/,https://microbean.github.io/microbean-qualifier/apidocs/ 2 @@ -134,9 +135,9 @@ org.microbean microbean-assign - 0.0.1-SNAPSHOT + 0.0.1 - + org.microbean microbean-construct diff --git a/src/main/java/org/microbean/event/EventQualifiersMatcher.java b/src/main/java/org/microbean/event/EventQualifiersMatcher.java index a78499d..b1c1408 100644 --- a/src/main/java/org/microbean/event/EventQualifiersMatcher.java +++ b/src/main/java/org/microbean/event/EventQualifiersMatcher.java @@ -24,12 +24,56 @@ import static org.microbean.assign.Qualifiers.defaultQualifiers; import static org.microbean.assign.Qualifiers.qualifiers; -public final class EventQualifiersMatcher implements Matcher>, Collection>> { +/** + * A {@link Matcher} encapsulating CDI-compatible event + * qualifier matching rules. + * + * @author Laird Nelson + * + * @see #test(Collection, Collection) + */ +public final class EventQualifiersMatcher + implements Matcher>, Collection>> { + + + /* + * Constructors. + */ + + /** + * Creates a new {@link EventQualifiersMatcher}. + */ public EventQualifiersMatcher() { super(); } + + /* + * Instance methods. + */ + + + /** + * Returns {@code true} if and only if either the {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) + * qualifiers present} in {@code receiverAttributes} are {@linkplain Collection#isEmpty() empty}, or if the collection + * of {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code + * payloadAttributes} {@linkplain Collection#containsAll(Collection) contains all} of the {@linkplain + * org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code receiverAttributes}. + * + * @param receiverAttributes a {@link Collection} of {@link NamedAttributeMap}s; must not be {@code null} + * + * @param payloadAttributes a {@link Collection} of {@link NamedAttributeMap}s; must not be {@code null} + * + * @return {@code true} if and only if either the {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) + * qualifiers present} in {@code receiverAttributes} are {@linkplain Collection#isEmpty() empty}, or if the collection + * of {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code + * payloadAttributes} {@linkplain Collection#containsAll(Collection) contains all} of the {@linkplain + * org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code receiverAttributes} + * + * @exception NullPointerException if either argument is {@code null} + */ @Override // Matcher>, Collection>> public final boolean test(final Collection> receiverAttributes, final Collection> payloadAttributes) { diff --git a/src/main/java/org/microbean/event/EventTypeMatcher.java b/src/main/java/org/microbean/event/EventTypeMatcher.java index fef9716..626d420 100644 --- a/src/main/java/org/microbean/event/EventTypeMatcher.java +++ b/src/main/java/org/microbean/event/EventTypeMatcher.java @@ -32,12 +32,65 @@ import org.microbean.construct.Domain; +/** + * An {@link AbstractTypeMatcher} encapsulating CDI-compatible event type + * matching rules. + * + * @author Laird Nelson + * + * @see #test(TypeMirror, TypeMirror) + */ public final class EventTypeMatcher extends AbstractTypeMatcher { + + /* + * Constructors. + */ + + + /** + * Creates a new {@link EventTypeMatcher}. + * + * @param domain a {@link Domain}; must not be {@code null} + * + * @exception NullPointerException if {@code domain} is {@code null} + * + * @see Domain + */ public EventTypeMatcher(final Domain domain) { super(domain); } + + /* + * Instance methods. + */ + + + /** + * Returns {@code true} if and only if the supplied {@code payload} argument (normally an event type) matches the + * supplied {@code receiver} argument (normally an observed event type), according to the rules defined by + * section 2.8.3 of the + * CDI specification. + * + * @param receiver the left hand side of an event type assignment (normally an observed event type); must not be + * {@code null} + * + * @param payload the right hand side of an event type assignment (normally an event type); must not be {@code null} + * + * @return {@code true} if and only if the supplied {@code payload} argument matches the supplied + * {@code receiver} argument, according to the rules defined by section 2.8.3 of the CDI + * specification; {@code false} otherwise + * + * @exception NullPointerException if either argument is {@code null} + * + * @exception IllegalArgumentException if either type is any type other than an {@linkplain TypeKind#ARRAY array + * type}, a {@link TypeKind#isPrimitive() primitive type}, or a {@linkplain TypeKind#DECLARED declared type} + */ @Override // Matcher public final boolean test(final TypeMirror receiver, final TypeMirror payload) { // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution @@ -230,6 +283,12 @@ private final boolean assignable(final DeclaredType receiver, final DeclaredType }; // end switch(payload) } + + /* + * Static methods. + */ + + // Returns a new IllegalArgumentException describing an illegal payload type. private static IllegalArgumentException illegalPayload(final TypeMirror payload) { return new IllegalArgumentException("Illegal payload kind: " + payload.getKind() + "; payload: " + payload); diff --git a/src/main/java/org/microbean/event/EventTypes.java b/src/main/java/org/microbean/event/EventTypes.java index 0ac90eb..ecafb3f 100644 --- a/src/main/java/org/microbean/event/EventTypes.java +++ b/src/main/java/org/microbean/event/EventTypes.java @@ -34,7 +34,15 @@ import static java.lang.System.Logger.Level.WARNING; -// Experimental and basically located in the wrong package and module. +/** + * A utility for working with event types. + * + * @author Laird Nelson + * + * @see #eventTypes(TypeMirror) + * + * @see #legalEventType(TypeMirror) + */ public final class EventTypes extends Types { @@ -51,6 +59,13 @@ public final class EventTypes extends Types { */ + /** + * Creates a new {@link EventTypes}. + * + * @param domain a {@link Domain}; must not be {@code null} + * + * @exception NullPointerException if {@code domain} is {@code null} + */ public EventTypes(final Domain domain) { super(domain); } @@ -61,6 +76,25 @@ public EventTypes(final Domain domain) { */ + /** + * Returns an immutable {@link List} of {@linkplain #legalEventType(TypeMirror) legal event types} that the supplied + * {@link TypeMirror} bears. + * + *

The returned {@link List} may be empty.

+ * + * @param t a {@link TypeMirror}; must not be {@code null} + * + * @return an immutable {@link List} of {@linkplain #legalEventType(TypeMirror) legal event types} that the supplied + * {@link TypeMirror} bears; never {@code null} + * + * @exception NullPointerException if {@code t} is {@code null} + * + * @microbean.nullability This method never returns {@code null}. + * + * @microbean.idempotency This method is idempotent and returns determinate values. + * + * @microbean.threadsafety This method is safe for concurrent use by multiple threads. + */ public final List eventTypes(final TypeMirror t) { // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types if (t.getKind() == TypeKind.DECLARED) { @@ -84,6 +118,32 @@ public final List eventTypes(final TypeMirror t) { */ + /** + * Returns {@code true} if and only if the supplied {@link TypeMirror} is a legal event type. + * + *

Legal event types are, exactly:

+ * + *
    + * + *
  1. {@linkplain TypeKind#ARRAY Array} types whose {@linkplain ArrayType#getComponentType() component type}s are + * legal event types
    2. + * + *
  2. {@linkplain TypeKind#DECLARED Declared} types that contain no {@linkplain TypeKind#WILDCARD wildcard type}s for + * every level of containment
    3. + * + *
+ * + * @param t a {@link TypeMirror}; must not be {@code null} + * + * @return {@code true} if and only if {@code t} is a legal bean type; {@code false} otherwise + * + * @exception NullPointerException if {@code t} is {@code null} + * + * @microbean.idempotency This method is idempotent and deterministic. + * + * @microbean.threadsafety This method itself is safe for concurrent use by multiple threads, but {@link TypeMirror} + * implementations and {@link Domain} implementations may not be safe for such use. + */ public static final boolean legalEventType(final TypeMirror t) { // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types return switch (t.getKind()) { @@ -128,6 +188,24 @@ public static final boolean legalEventType(final TypeMirror t) { } + /** + * Returns {@code true} if and only if the supplied {@link TypeMirror} is a legal observed event type. + * + *

A legal observed event type is any Java type + * that a method parameter may bear. + * + * @param t a {@link TypeMirror}; must not be {@code null} + * + * @return {@code true} if and only if {@code t} is a legal observed event type; {@code false} otherwise + * + * @exception NullPointerException if {@code t} is {@code null} + * + * @microbean.idempotency This method is idempotent and deterministic. + * + * @microbean.threadsafety This method itself is safe for concurrent use by multiple threads, but {@link TypeMirror} + * implementations and {@link Domain} implementations may not be safe for such use. + */ public static final boolean legalObservedEventType(final TypeMirror t) { // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types // "Any Java type [that a method parameter element may bear] may be an observed event type." @@ -137,5 +215,4 @@ public static final boolean legalObservedEventType(final TypeMirror t) { }; } - }