Package org.apache.beam.sdk.util

Class ApiSurface

  • @Internal
public class ApiSurface
extends java.lang.Object
    Represents the API surface of a package prefix. Used for accessing public classes, methods, and the types they reference, to control what dependencies are re-exported.

    For the purposes of calculating the public API surface, exposure includes any public or protected occurrence of:

    • superclasses
    • interfaces implemented
    • actual type arguments to generic types
    • array component types
    • method return types
    • method parameter types
    • type variable bounds
    • wildcard bounds

    Exposure is a transitive property. The resulting map excludes primitives and array classes themselves.

    It is prudent (though not required) to prune prefixes like "java" via the builder method pruningPrefix(java.lang.String) to halt the traversal so it does not uselessly catalog references that are not interesting.

    • Method Detail

      • classesInPackage

        public static org.hamcrest.Matcher<java.lang.Class<?>> classesInPackage​(java.lang.String packageName)
        A factory method to create a Class matcher for classes residing in a given package.

      • containsOnlyClassesMatching

        public static org.hamcrest.Matcher<ApiSurface> containsOnlyClassesMatching​(java.util.Set<org.hamcrest.Matcher<java.lang.Class<?>>> classMatchers)
        A factory method to create an ApiSurface matcher, producing a positive match if the queried api surface contains ONLY classes described by the provided matchers.

      • containsOnlyClassesMatching

        @SafeVarargs
public static org.hamcrest.Matcher<ApiSurface> containsOnlyClassesMatching​(org.hamcrest.Matcher<java.lang.Class<?>>... classMatchers)
        See containsOnlyClassesMatching(Set).

      • containsOnlyPackages

        public static org.hamcrest.Matcher<ApiSurface> containsOnlyPackages​(java.util.Set<java.lang.String> packageNames)
        A factory method to create an ApiSurface matcher, producing a positive match if the queried api surface contains classes ONLY from specified package names.

      • ofPackage

        public static ApiSurface ofPackage​(java.lang.String packageName,
                                   java.lang.ClassLoader classLoader)
                            throws java.io.IOException
        Returns an ApiSurface object representing the given package and all subpackages.
        Throws:
        java.io.IOException

      • ofPackage

        public static ApiSurface ofPackage​(java.lang.Package aPackage,
                                   java.lang.ClassLoader classLoader)
                            throws java.io.IOException
        Returns an ApiSurface object representing the given package and all subpackages.
        Throws:
        java.io.IOException

      • ofClass

        public static ApiSurface ofClass​(java.lang.Class<?> clazz)
        Returns an ApiSurface object representing just the surface of the given class.

      • includingPackage

        public ApiSurface includingPackage​(java.lang.String packageName,
                                   java.lang.ClassLoader classLoader)
                            throws java.io.IOException
        Returns an ApiSurface like this one, but also including the named package and all of its subpackages.
        Throws:
        java.io.IOException

      • includingClass

        public ApiSurface includingClass​(java.lang.Class<?> clazz)
        Returns an ApiSurface like this one, but also including the given class.

      • pruningPrefix

        public ApiSurface pruningPrefix​(java.lang.String prefix)
        Returns an ApiSurface like this one, but pruning transitive references from classes whose full name (including package) begins with the provided prefix.

      • pruningClassName

        public ApiSurface pruningClassName​(java.lang.String className)
        Returns an ApiSurface like this one, but pruning references from the named class.

      • pruningClass

        public ApiSurface pruningClass​(java.lang.Class<?> clazz)
        Returns an ApiSurface like this one, but pruning references from the provided class.

      • pruningPattern

        public ApiSurface pruningPattern​(java.util.regex.Pattern pattern)
        Returns an ApiSurface like this one, but pruning transitive references from classes whose full name (including package) begins with the provided prefix.

      • getRootClasses

        public java.util.Set<java.lang.Class<?>> getRootClasses()
        Returns all public classes originally belonging to the package in the ApiSurface.

      • getExposedClasses

        public java.util.Set<java.lang.Class<?>> getExposedClasses()
        Returns exposed types in this set, including arrays and primitives as specified.

      • getAnyExposurePath

        public java.util.List<java.lang.Class<?>> getAnyExposurePath​(java.lang.Class<?> exposedClass)
        Returns a path from an exposed class to a root class. There may be many, but this gives only one.

        If there are only cycles, with no path back to a root class, throws IllegalStateException.