org.revapi.java.spi

Class Util

java.lang.Object

org.revapi.java.spi.Util

public final class Util
extends Object

A random assortment of methods to help with implementing the Java API checks made public so that extenders don't have to reinvent the wheel.

Since:

0.1

Author:

Lukas Krejci

Method Summary

Modifier and Type	Method and Description
static void	fillAllSuperInterfaces(Types types, TypeMirror type, List<TypeMirror> result)
static void	fillAllSuperTypes(Types types, TypeMirror type, List<TypeMirror> result) Similar to getAllSuperTypes(javax.lang.model.util.Types, javax.lang.model.type.TypeMirror) but avoids instantiation of a new list.
static TypeElement	findTypeByBinaryName(Elements elements, String binaryName) Tries to find a type element using the provided Elements helper given its binary name.
static List<TypeMirror>	getAllSuperClasses(Types types, TypeMirror type) Returns all the super classes of given type.
static List<TypeMirror>	getAllSuperInterfaces(Types types, TypeMirror type)
static List<TypeMirror>	getAllSuperTypes(Types types, TypeMirror type) Similar to getAllSuperClasses(javax.lang.model.util.Types, javax.lang.model.type.TypeMirror) but returns all super types including implemented interfaces.
static boolean	isEqual(AnnotationValue oldVal, AnnotationValue newVal)
static boolean	isSameType(TypeMirror t1, TypeMirror t2) To be used to compare types from different compilations (which are not comparable by standard means in Types).
static boolean	isSubtype(TypeMirror type, List<? extends TypeMirror> superTypes, Types typeEnvironment) Checks whether given type is a sub type or is equal to one of the provided types.
static Map<String,Map.Entry<? extends ExecutableElement,? extends AnnotationValue>>	keyAnnotationAttributesByName(Map<? extends ExecutableElement,? extends AnnotationValue> attributes) Extracts the names of the attributes from the executable elements that represents them in the given map and returns a map keyed by those names.
static String	toHumanReadableString(AnnotatedConstruct construct) Constructs a human readable representation of the supplied element or type mirror.
static String	toHumanReadableString(AnnotationMirror v)
static String	toHumanReadableString(AnnotationValue v)
static String	toUniqueString(AnnotationValue v)
static String	toUniqueString(TypeMirror t) Represents the type mirror as a string in such a way that it can be used for equality comparisons.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isSameType

public static boolean isSameType(@Nonnull
                                 TypeMirror t1,
                                 @Nonnull
                                 TypeMirror t2)

To be used to compare types from different compilations (which are not comparable by standard means in Types). This just compares the type names.

Parameters:

t1 - first type

t2 - second type

Returns:

true if the types have the same fqn, false otherwise

toHumanReadableString

@Nonnull
public static String toHumanReadableString(@Nonnull
                                                    AnnotatedConstruct construct)

Constructs a human readable representation of the supplied element or type mirror. Note that in some cases the representation might be "surprising". Especially for ExecutableType for which there is no way of getting reliably at the method name or the type declaring the method.

Parameters:

construct - the element or type mirror to render

Returns:

a human readable representation of the construct

toUniqueString

@Nonnull
public static String toUniqueString(@Nonnull
                                             TypeMirror t)

Represents the type mirror as a string in such a way that it can be used for equality comparisons.

Parameters:

t - type to convert to string

Returns:

the string representation of the type that is fit for equality comparisons

toUniqueString

@Nonnull
public static String toUniqueString(@Nonnull
                                             AnnotationValue v)

toHumanReadableString

@Nonnull
public static String toHumanReadableString(@Nonnull
                                                    AnnotationValue v)

toHumanReadableString

@Nonnull
public static String toHumanReadableString(@Nonnull
                                                    AnnotationMirror v)

getAllSuperClasses

@Nonnull
public static List<TypeMirror> getAllSuperClasses(@Nonnull
                                                           Types types,
                                                           @Nonnull
                                                           TypeMirror type)

Returns all the super classes of given type. I.e. the returned list does NOT contain any interfaces the class or tis superclasses implement.

Parameters:

types - the Types instance of the compilation environment from which the type comes from

type - the type

Returns:

the list of super classes

getAllSuperTypes

@Nonnull
public static List<TypeMirror> getAllSuperTypes(@Nonnull
                                                         Types types,
                                                         @Nonnull
                                                         TypeMirror type)

Similar to getAllSuperClasses(javax.lang.model.util.Types, javax.lang.model.type.TypeMirror) but returns all super types including implemented interfaces.

Parameters:

types - the Types instance of the compilation environment from which the type comes from

type - the type

Returns:

the list of super tpyes

fillAllSuperTypes

public static void fillAllSuperTypes(@Nonnull
                                     Types types,
                                     @Nonnull
                                     TypeMirror type,
                                     @Nonnull
                                     List<TypeMirror> result)

Similar to getAllSuperTypes(javax.lang.model.util.Types, javax.lang.model.type.TypeMirror) but avoids instantiation of a new list.

Parameters:

types - the Types instance of the compilation environment from which the type comes from

type - the type

result - the list to add the results to.

getAllSuperInterfaces

@Nonnull
public static List<TypeMirror> getAllSuperInterfaces(@Nonnull
                                                              Types types,
                                                              @Nonnull
                                                              TypeMirror type)

fillAllSuperInterfaces

public static void fillAllSuperInterfaces(@Nonnull
                                          Types types,
                                          @Nonnull
                                          TypeMirror type,
                                          @Nonnull
                                          List<TypeMirror> result)

isSubtype

public static boolean isSubtype(@Nonnull
                                TypeMirror type,
                                @Nonnull
                                List<? extends TypeMirror> superTypes,
                                @Nonnull
                                Types typeEnvironment)

Checks whether given type is a sub type or is equal to one of the provided types. Note that this does not require the type to come from the same type "environment" or compilation as the super types.

Parameters:

type - the type to check

superTypes - the list of supposed super types

typeEnvironment - the environment in which the type lives

Returns:

true if type a sub type of one of the provided super types, false otherwise.

keyAnnotationAttributesByName

@Nonnull
public static Map<String,Map.Entry<? extends ExecutableElement,? extends AnnotationValue>> keyAnnotationAttributesByName(@Nonnull
                                                                                                                                  Map<? extends ExecutableElement,? extends AnnotationValue> attributes)

Extracts the names of the attributes from the executable elements that represents them in the given map and returns a map keyed by those names.

I.e. while representing annotation attributes on an annotation type by executable elements is technically correct it is more convenient to address them simply by their names, which, in case of annotation types, are unique (i.e. you cannot overload an annotation attribute, because they cannot have method parameters).

Parameters:

attributes - the attributes as obtained by AnnotationMirror.getElementValues()

Returns:

the equivalent of the supplied map keyed by attribute names instead of the full-blown executable elements

isEqual

public static boolean isEqual(@Nonnull
                              AnnotationValue oldVal,
                              @Nonnull
                              AnnotationValue newVal)

findTypeByBinaryName

public static TypeElement findTypeByBinaryName(Elements elements,
                                               String binaryName)

Tries to find a type element using the provided Elements helper given its binary name. Note that this might NOT be able to find some classes if there are conflicts in the canonical names (but that theoretically cannot happen because the compiler should refuse to compile code with conflicting canonical names).

Parameters:

elements - the elements instance to search the classpath

binaryName - the binary name of the class

Returns:

the type element with given binary name