Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add String- and Class-accepting shortcuts #252

Merged
merged 1 commit into from
Sep 1, 2022
Merged

Add String- and Class-accepting shortcuts #252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 236 additions & 0 deletions core/src/main/java/org/jboss/jandex/AnnotationTarget.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

package org.jboss.jandex;

import java.lang.annotation.Annotation;
import java.util.Collection;

/**
Expand Down Expand Up @@ -139,6 +140,32 @@ public enum Kind {
*/
boolean hasAnnotation(DotName name);

/**
* Returns whether an annotation instance with given name is declared on this annotation target or any of its
* nested annotation targets.
*
* @param name name of the annotation type to look for, must not be {@code null}
* @return {@code true} if the annotation is present, {@code false} otherwise
* @since 3.0
* @see #annotation(DotName)
*/
default boolean hasAnnotation(String name) {
return hasAnnotation(DotName.createSimple(name));
}

/**
* Returns whether an annotation instance of given type is declared on this annotation target or any of its
* nested annotation targets.
*
* @param clazz the annotation type to look for, must not be {@code null}
* @return {@code true} if the annotation is present, {@code false} otherwise
* @since 3.0
* @see #annotation(DotName)
*/
default boolean hasAnnotation(Class<? extends Annotation> clazz) {
return hasAnnotation(DotName.createSimple(clazz.getName()));
}

/**
* Returns the annotation instance with given name declared on this annotation target or any of its nested
* annotation targets. The {@code target()} method of the returned annotation instance may be used to determine
Expand All @@ -154,6 +181,40 @@ public enum Kind {
*/
AnnotationInstance annotation(DotName name);

/**
* Returns the annotation instance with given name declared on this annotation target or any of its nested
* annotation targets. The {@code target()} method of the returned annotation instance may be used to determine
* the exact location of the annotation instance.
* <p>
* In case an annotation with given name occurs more than once, the result of this method is not deterministic.
* For such situations, {@link #annotations(DotName)} is preferable.
*
* @param name name of the annotation type to look for, must not be {@code null}
* @return the annotation instance, or {@code null} if not found
* @since 3.0
* @see #annotations(DotName)
*/
default AnnotationInstance annotation(String name) {
return annotation(DotName.createSimple(name));
}

/**
* Returns the annotation instance of given type declared on this annotation target or any of its nested
* annotation targets. The {@code target()} method of the returned annotation instance may be used to determine
* the exact location of the annotation instance.
* <p>
* In case an annotation with given name occurs more than once, the result of this method is not deterministic.
* For such situations, {@link #annotations(DotName)} is preferable.
*
* @param clazz the annotation type to look for, must not be {@code null}
* @return the annotation instance, or {@code null} if not found
* @since 3.0
* @see #annotations(DotName)
*/
default AnnotationInstance annotation(Class<? extends Annotation> clazz) {
return annotation(DotName.createSimple(clazz.getName()));
}

/**
* Returns the annotation instances with given name declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
Expand All @@ -167,6 +228,36 @@ public enum Kind {
*/
Collection<AnnotationInstance> annotations(DotName name);

/**
* Returns the annotation instances with given name declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
* of the respective annotation instance.
*
* @param name name of the annotation type, must not be {@code null}
* @return immutable collection of annotation instances, never {@code null}
* @since 3.0
* @see #annotationsWithRepeatable(DotName, IndexView)
* @see #annotations()
*/
default Collection<AnnotationInstance> annotations(String name) {
return annotations(DotName.createSimple(name));
}

/**
* Returns the annotation instances of given type declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
* of the respective annotation instance.
*
* @param clazz the annotation type, must not be {@code null}
* @return immutable collection of annotation instances, never {@code null}
* @since 3.0
* @see #annotationsWithRepeatable(DotName, IndexView)
* @see #annotations()
*/
default Collection<AnnotationInstance> annotations(Class<? extends Annotation> clazz) {
return annotations(DotName.createSimple(clazz.getName()));
}

/**
* Returns the annotation instances with given name declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
Expand All @@ -187,6 +278,50 @@ public enum Kind {
*/
Collection<AnnotationInstance> annotationsWithRepeatable(DotName name, IndexView index);

/**
* Returns the annotation instances with given name declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
* of the respective annotation instance.
* <p>
* If the specified annotation is repeatable, the result also contains all values from the container annotation
* instance. In this case, the {@link AnnotationInstance#target()} returns the target of the container annotation
* instance.
*
* @param name name of the annotation type, must not be {@code null}
* @param index index used to obtain the annotation type, must not be {@code null}
* @return immutable collection of annotation instances, never {@code null}
* @throws IllegalArgumentException if the index is {@code null}, if the index does not contain the annotation type
* or if {@code name} does not identify an annotation type
* @since 3.0
* @see #annotations(DotName)
* @see #annotations()
*/
default Collection<AnnotationInstance> annotationsWithRepeatable(String name, IndexView index) {
return annotationsWithRepeatable(DotName.createSimple(name), index);
}

/**
* Returns the annotation instances of given type declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
* of the respective annotation instance.
* <p>
* If the specified annotation is repeatable, the result also contains all values from the container annotation
* instance. In this case, the {@link AnnotationInstance#target()} returns the target of the container annotation
* instance.
*
* @param clazz the annotation type, must not be {@code null}
* @param index index used to obtain the annotation type, must not be {@code null}
* @return immutable collection of annotation instances, never {@code null}
* @throws IllegalArgumentException if the index is {@code null}, if the index does not contain the annotation type
* or if {@code name} does not identify an annotation type
* @since 3.0
* @see #annotations(DotName)
* @see #annotations()
*/
default Collection<AnnotationInstance> annotationsWithRepeatable(Class<? extends Annotation> clazz, IndexView index) {
return annotationsWithRepeatable(DotName.createSimple(clazz.getName()), index);
}

/**
* Returns the annotation instances declared on this annotation target and nested annotation targets.
* The {@code target()} method of the returned annotation instances may be used to determine the exact location
Expand All @@ -209,6 +344,34 @@ public enum Kind {
*/
boolean hasDeclaredAnnotation(DotName name);

/**
* Returns whether an annotation instance with given name is declared on this annotation target.
* <p>
* Unlike {@link #hasAnnotation(DotName)}, this method ignores annotations declared on nested annotation targets.
*
* @param name name of the annotation type to look for, must not be {@code null}
* @return {@code true} if the annotation is present, {@code false} otherwise
* @since 3.0
* @see #hasAnnotation(DotName)
*/
default boolean hasDeclaredAnnotation(String name) {
return hasDeclaredAnnotation(DotName.createSimple(name));
}

/**
* Returns whether an annotation instance of given type is declared on this annotation target.
* <p>
* Unlike {@link #hasAnnotation(DotName)}, this method ignores annotations declared on nested annotation targets.
*
* @param clazz the annotation type to look for, must not be {@code null}
* @return {@code true} if the annotation is present, {@code false} otherwise
* @since 3.0
* @see #hasAnnotation(DotName)
*/
default boolean hasDeclaredAnnotation(Class<? extends Annotation> clazz) {
return hasDeclaredAnnotation(DotName.createSimple(clazz.getName()));
}

/**
* Returns the annotation instance with given name declared on this annotation target.
* <p>
Expand All @@ -221,6 +384,34 @@ public enum Kind {
*/
AnnotationInstance declaredAnnotation(DotName name);

/**
* Returns the annotation instance with given name declared on this annotation target.
* <p>
* Unlike {@link #annotation(DotName)}, this method doesn't return annotations declared on nested annotation targets.
*
* @param name name of the annotation type to look for, must not be {@code null}
* @return the annotation instance, or {@code null} if not found
* @since 3.0
* @see #annotation(DotName)
*/
default AnnotationInstance declaredAnnotation(String name) {
return declaredAnnotation(DotName.createSimple(name));
}

/**
* Returns the annotation instance of given type declared on this annotation target.
* <p>
* Unlike {@link #annotation(DotName)}, this method doesn't return annotations declared on nested annotation targets.
*
* @param clazz the annotation type to look for, must not be {@code null}
* @return the annotation instance, or {@code null} if not found
* @since 3.0
* @see #annotation(DotName)
*/
default AnnotationInstance declaredAnnotation(Class<? extends Annotation> clazz) {
return declaredAnnotation(DotName.createSimple(clazz.getName()));
}

/**
* Returns the annotation instances with given name declared on this annotation target.
* <p>
Expand All @@ -241,6 +432,51 @@ public enum Kind {
*/
Collection<AnnotationInstance> declaredAnnotationsWithRepeatable(DotName name, IndexView index);

/**
* Returns the annotation instances with given name declared on this annotation target.
* <p>
* If the specified annotation is repeatable, the result also contains all values from the container annotation
* instance. In this case, the {@link AnnotationInstance#target()} returns the target of the container annotation
* instance.
* <p>
* Unlike {@link #annotationsWithRepeatable(DotName, IndexView)}, this method doesn't return annotations
* declared on nested annotation targets.
*
* @param name name of the annotation type, must not be {@code null}
* @param index index used to obtain the annotation type, must not be {@code null}
* @return immutable collection of annotation instances, never {@code null}
* @throws IllegalArgumentException if the index is {@code null}, if the index does not contain the annotation type
* or if {@code name} does not identify an annotation type
* @since 3.0
* @see #annotationsWithRepeatable(DotName, IndexView)
*/
default Collection<AnnotationInstance> declaredAnnotationsWithRepeatable(String name, IndexView index) {
return declaredAnnotationsWithRepeatable(DotName.createSimple(name), index);
}

/**
* Returns the annotation instances of given type declared on this annotation target.
* <p>
* If the specified annotation is repeatable, the result also contains all values from the container annotation
* instance. In this case, the {@link AnnotationInstance#target()} returns the target of the container annotation
* instance.
* <p>
* Unlike {@link #annotationsWithRepeatable(DotName, IndexView)}, this method doesn't return annotations
* declared on nested annotation targets.
*
* @param clazz the annotation type, must not be {@code null}
* @param index index used to obtain the annotation type, must not be {@code null}
* @return immutable collection of annotation instances, never {@code null}
* @throws IllegalArgumentException if the index is {@code null}, if the index does not contain the annotation type
* or if {@code name} does not identify an annotation type
* @since 3.0
* @see #annotationsWithRepeatable(DotName, IndexView)
*/
default Collection<AnnotationInstance> declaredAnnotationsWithRepeatable(Class<? extends Annotation> clazz,
IndexView index) {
return declaredAnnotationsWithRepeatable(DotName.createSimple(clazz.getName()), index);
}

/**
* Returns the annotation instances declared on this annotation target.
* <p>
Expand Down
14 changes: 14 additions & 0 deletions core/src/main/java/org/jboss/jandex/DotName.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,20 @@ public static DotName createSimple(String name) {
return new DotName(null, name, false, false);
}

/**
* Constructs a simple {@link DotName} which stores the name of given class in its entirety.
* This variant is ideal for temporary usage, such as looking up an entry in a {@code Map}
* or an {@linkplain Index index}.
* <p>
* This method is a shortcut for {@code DotName.createSimple(clazz.getName())}.
*
* @param clazz a class whose fully qualified name is returned; must not be {@code null}
* @return a simple {@code DotName} that wraps the name of given {@code clazz}; never {@code null}
*/
public static DotName createSimple(Class<?> clazz) {
return createSimple(clazz.getName());
}

/**
* Constructs a componentized {@link DotName}. Such {@code DotName} refers to
* a parent prefix (or {@code null} if there is no further prefix) in addition
Expand Down