Package org.apache.tapestry5.ioc.internal.util

## Class InternalUtils

- java.lang.Object
- - org.apache.tapestry5.ioc.internal.util.InternalUtils

-     public class InternalUtils
      extends Object

  Utilities used within various internal implementations of the tapestry-ioc module.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static Mapper<Class,​AnnotationProvider>` | `CLASS_TO_AP_MAPPER` |
    `static Mapper<ObjectCreator,​Object>` | `CREATE_OBJECT` |
    `static Mapper<Method,​AnnotationProvider>` | `METHOD_TO_AP_MAPPER` |
    `static boolean` | `SERVICE_CLASS_RELOADING_ENABLED` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `InternalUtils()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static <K,​V> void` | `addToMapList​(Map<K,​List<V>> map, K key, V value)` | Adds a value to a specially organized map where the values are lists of objects.
    `static String` | `asString​(Method method)` | Converts a method to a user presentable string consisting of the containing class name, the method name, and the short form of the parameter list (the class name of each parameter type, shorn of the package name portion).
    `static String` | `asString​(Method method, PlasticProxyFactory proxyFactory)` | Converts a method to a user presentable string using a `PlasticProxyFactory` to obtain a `Location` (where possible).
    `static ObjectCreator[]` | `calculateParameters​(ObjectLocator locator, InjectionResources resources, Class[] parameterTypes, Type[] genericTypes, Annotation[][] parameterAnnotations, OperationTracker tracker)` |
    `static ObjectCreator[]` | `calculateParametersForMethod​(Method method, ObjectLocator locator, InjectionResources resources, OperationTracker tracker)` |
    `static String` | `capitalize​(String input)` | Capitalizes a string, converting the first character to uppercase.
    `static void` | `close​(Closeable stream)` |
    `static boolean` | `containsSymbols​(String input)` | Return true if the input string contains the marker for symbols that must be expanded.
    `static <T> ObjectCreator<T>` | `createConstructorConstructionPlan​(OperationTracker tracker, ObjectLocator locator, InjectionResources resources, org.slf4j.Logger logger, String description, Constructor<T> constructor)` |
    `static <T> ObjectCreator<T>` | `createMethodInvocationPlan​(OperationTracker tracker, ObjectLocator locator, InjectionResources resources, org.slf4j.Logger logger, String description, Object instance, Method method)` |
    `static String` | `defaultLabel​(String id, Messages messages, String propertyExpression)` | Looks for a label within the messages based on the id.
    `static String` | `extractIdFromPropertyExpression​(String expression)` | Used to convert a property expression into a key that can be used to locate various resources (Blocks, messages, etc.).
    `static <T extends Annotation> T` | `findAnnotation​(Annotation[] annotations, Class<T> annotationClass)` | Finds a specific annotation type within an array of annotations.
    `static Constructor` | `findAutobuildConstructor​(Class clazz)` | Searches a class for the "best" constructor, the public constructor with the most parameters.
    `static Method` | `findMethod​(Class containingClass, String methodName, Class... parameterTypes)` |
    `static <K,​V> V` | `get​(Map<K,​V> map, K key)` | Gets a value from a map (which may be null).
    `static String` | `getServiceId​(AnnotatedElement annotated)` | Extracts the service id from the passed annotated element.
    `static void` | `injectIntoFields​(Object object, ObjectLocator locator, InjectionResources resources, OperationTracker tracker)` | Injects into the fields (of all visibilities) when the `Inject` or `InjectService` annotations are present.
    `static boolean` | `isBlank​(String input)` | Returns true if the input is null, or is a zero length string (excluding leading/trailing whitespace).
    `static boolean` | `isEmptyCollection​(Object input)` | Returns true if the input is an empty collection.
    `static boolean` | `isLocalFile​(Class clazz)` | Determines if the indicated class is stored as a locally accessible file (and not, typically, as a file inside a JAR).
    `static boolean` | `isNonBlank​(String input)` |
    `static boolean` | `isStatic​(Method method)` | Returns true if the method provided is a static method.
    `static String` | `join​(List elements)` | Joins together some number of elements to form a comma separated list.
    `static String` | `join​(List elements, String separator)` | Joins together some number of elements.
    `static String` | `joinSorted​(Collection elements)` | Creates a sorted copy of the provided elements, then turns that into a comma separated list.
    `static <K,​V> Set<K>` | `keys​(Map<K,​V> map)` |
    `static String` | `lastTerm​(String input)` | Searches the string for the final period ('.') character and returns everything after that.
    `static Location` | `locationOf​(Object location)` | Sniffs the object to see if it is a `Location` or `Locatable`.
    `static <T extends Comparable<T>> List<T>` | `matchAndSort​(Collection<? extends T> collection, Predicate<T> predicate)` |
    `static long` | `nextUUID()` | Generates a unique value for the current execution of the application.
    `static Object[]` | `realizeObjects​(ObjectCreator[] creators)` |
    `static String` | `replace​(String input, Pattern pattern, String replacement)` |
    `static <T> Iterator<T>` | `reverseIterator​(List<T> list)` |
    `static int` | `size​(Object[] array)` | Returns the size of an object array, or null if the array is empty.
    `static int` | `size​(Collection collection)` |
    `static List<String>` | `sortedKeys​(Map map)` | Extracts the string keys from a map and returns them in sorted order.
    `static String` | `stripMemberName​(String memberName)` | Strips leading "_" and "$" and trailing "_" from the name.
    `static AdvisorDef2` | `toAdvisorDef2​(AdvisorDef advisor)` |
    `static AnnotationProvider` | `toAnnotationProvider​(Class element)` |
    `static AnnotationProvider` | `toAnnotationProvider​(Method element)` |
    `static ContributionDef2` | `toContributionDef2​(ContributionDef contribution)` |
    `static ContributionDef3` | `toContributionDef3​(ContributionDef contribution)` |
    `static DecoratorDef2` | `toDecoratorDef2​(DecoratorDef decorator)` |
    `static List<String>` | `toList​(Enumeration e)` | Converts an enumeration (of Strings) into a sorted list of Strings.
    `static <S,​T> Mapper<S,​T>` | `toMapper​(Coercion<S,​T> coercion)` | Wraps a `Coercion` as a `Mapper`.
    `static String` | `toMessage​(Throwable exception)` | Deprecated. Deprecated in 5.4; use `ExceptionUtils.toMessage(Throwable)` instead.
    `static ModuleDef2` | `toModuleDef2​(ModuleDef md)` |
    `static ServiceDef2` | `toServiceDef2​(ServiceDef sd)` |
    `static ServiceDef3` | `toServiceDef3​(ServiceDef sd)` |
    `static ServiceLifecycle2` | `toServiceLifecycle2​(ServiceLifecycle lifecycle)` |
    `static String` | `toUserPresentable​(String id)` | Capitalizes the string, and inserts a space before each upper case character (or sequence of upper case characters).
    `static void` | `validateConstructorForAutobuild​(Constructor constructor)` |
    `static void` | `validateMarkerAnnotation​(Class markerClass)` | Validates that the marker annotation class had a retention policy of runtime.
    `static void` | `validateMarkerAnnotations​(Class[] markerClasses)` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### SERVICE_CLASS_RELOADING_ENABLED

          public static final boolean SERVICE_CLASS_RELOADING_ENABLED

      Since:
        5.2.2

    - #### CLASS_TO_AP_MAPPER

          public static final Mapper<Class,​AnnotationProvider> CLASS_TO_AP_MAPPER

      Since:
        5.3

    - #### METHOD_TO_AP_MAPPER

          public static final Mapper<Method,​AnnotationProvider> METHOD_TO_AP_MAPPER

      Since:
        5.3

    - #### CREATE_OBJECT

          public static final Mapper<ObjectCreator,​Object> CREATE_OBJECT

      Since:
        5.3.1, 5.4

  - ### Constructor Detail

    - #### InternalUtils

          public InternalUtils()

  - ### Method Detail

    - #### asString

          public static String asString​(Method method,
                                        PlasticProxyFactory proxyFactory)

      Converts a method to a user presentable string using a `PlasticProxyFactory` to obtain a `Location` (where possible). `asString(Method)` is used under the covers, to present a detailed, but not excessive, description of the class, method and parameters.
      Parameters:
        `method` - method to convert to a string
        `proxyFactory` - used to obtain the `Location`
      Returns:
        the method formatted for presentation to the user

    - #### asString

          public static String asString​(Method method)

      Converts a method to a user presentable string consisting of the containing class name, the method name, and the short form of the parameter list (the class name of each parameter type, shorn of the package name portion).
      Parameters:
        `method` -
      Returns:
        short string representation

    - #### size

          public static int size​(Object[] array)

      Returns the size of an object array, or null if the array is empty.

    - #### size

          public static int size​(Collection collection)

    - #### stripMemberName

          public static String stripMemberName​(String memberName)

      Strips leading "_" and "$" and trailing "_" from the name.

    - #### toList

          public static List<String> toList​(Enumeration e)

      Converts an enumeration (of Strings) into a sorted list of Strings.

    - #### findAnnotation

          public static <T extends Annotation> T findAnnotation​(Annotation[] annotations,
                                                                Class<T> annotationClass)

      Finds a specific annotation type within an array of annotations.
      Type Parameters:
        `T` -
      Parameters:
        `annotations` - to search
        `annotationClass` - to match
      Returns:
        the annotation instance, if found, or null otherwise

    - #### calculateParametersForMethod

          public static ObjectCreator[] calculateParametersForMethod​(Method method,
                                                                     ObjectLocator locator,
                                                                     InjectionResources resources,
                                                                     OperationTracker tracker)

    - #### calculateParameters

          public static ObjectCreator[] calculateParameters​(ObjectLocator locator,
                                                            InjectionResources resources,
                                                            Class[] parameterTypes,
                                                            Type[] genericTypes,
                                                            Annotation[][] parameterAnnotations,
                                                            OperationTracker tracker)

    - #### injectIntoFields

          public static void injectIntoFields​(Object object,
                                              ObjectLocator locator,
                                              InjectionResources resources,
                                              OperationTracker tracker)

      Injects into the fields (of all visibilities) when the `Inject` or `InjectService` annotations are present.
      Parameters:
        `object` - to be initialized
        `locator` - used to resolve external dependencies
        `resources` - provides injection resources for fields
        `tracker` - track operations

    - #### join

          public static String join​(List elements)

      Joins together some number of elements to form a comma separated list.

    - #### join

          public static String join​(List elements,
                                    String separator)

      Joins together some number of elements. If a value in the list is the empty string, it is replaced with the string "(blank)".
      Parameters:
        `elements` - objects to be joined together
        `separator` - used between elements when joining

    - #### joinSorted

          public static String joinSorted​(Collection elements)

      Creates a sorted copy of the provided elements, then turns that into a comma separated list.
      Returns:
        the elements converted to strings, sorted, joined with comma ... or "(none)" if the elements are null or empty

    - #### isBlank

          public static boolean isBlank​(String input)

      Returns true if the input is null, or is a zero length string (excluding leading/trailing whitespace).

    - #### isEmptyCollection

          public static boolean isEmptyCollection​(Object input)

      Returns true if the input is an empty collection.

    - #### isNonBlank

          public static boolean isNonBlank​(String input)

    - #### capitalize

          public static String capitalize​(String input)

      Capitalizes a string, converting the first character to uppercase.

    - #### locationOf

          public static Location locationOf​(Object location)

      Sniffs the object to see if it is a `Location` or `Locatable`. Returns null if null or not convertable to a location.

    - #### keys

          public static <K,​V> Set<K> keys​(Map<K,​V> map)

    - #### get

          public static <K,​V> V get​(Map<K,​V> map,
                                          K key)

      Gets a value from a map (which may be null).
      Type Parameters:
        `K` -
        `V` -
      Parameters:
        `map` - the map to extract from (may be null)
        `key` -
      Returns:
        the value from the map, or null if the map is null

    - #### isStatic

          public static boolean isStatic​(Method method)

      Returns true if the method provided is a static method.

    - #### reverseIterator

          public static <T> Iterator<T> reverseIterator​(List<T> list)

    - #### containsSymbols

          public static boolean containsSymbols​(String input)

      Return true if the input string contains the marker for symbols that must be expanded.

    - #### lastTerm

          public static String lastTerm​(String input)

      Searches the string for the final period ('.') character and returns everything after that. The input string is generally a fully qualified class name, though tapestry-core also uses this method for the occasional property expression (which is also dot separated). Returns the input string unchanged if it does not contain a period character.

    - #### findAutobuildConstructor

          public static Constructor findAutobuildConstructor​(Class clazz)

      Searches a class for the "best" constructor, the public constructor with the most parameters. Returns null if there are no public constructors. If there is more than one constructor with the maximum number of parameters, it is not determined which will be returned (don't build a class like that!). In addition, if a constructor is annotated with `Inject`, it will be used (no check for multiple such constructors is made, only at most a single constructor should have the annotation).
      Parameters:
        `clazz` - to search for a constructor for
      Returns:
        the constructor to be used to instantiate the class, or null if no appropriate constructor was found

    - #### addToMapList

          public static <K,​V> void addToMapList​(Map<K,​List<V>> map,
                                                      K key,
                                                      V value)

      Adds a value to a specially organized map where the values are lists of objects. This somewhat simulates a map that allows multiple values for the same key.
      Type Parameters:
        `K` - the type of key
        `V` - the type of the list
      Parameters:
        `map` - to store value into
        `key` - for which a value is added
        `value` - to add

    - #### validateMarkerAnnotation

          public static void validateMarkerAnnotation​(Class markerClass)

      Validates that the marker annotation class had a retention policy of runtime.
      Parameters:
        `markerClass` - the marker annotation class

    - #### validateMarkerAnnotations

          public static void validateMarkerAnnotations​(Class[] markerClasses)

    - #### close

          public static void close​(Closeable stream)

    - #### toMessage

          public static String toMessage​(Throwable exception)

      Deprecated.
      Deprecated in 5.4; use `ExceptionUtils.toMessage(Throwable)` instead.
      Extracts the message from an exception. If the exception's message is null, returns the exceptions class name.
      Parameters:
        `exception` - to extract message from
      Returns:
        message or class name

    - #### validateConstructorForAutobuild

          public static void validateConstructorForAutobuild​(Constructor constructor)

    - #### toAnnotationProvider

          public static AnnotationProvider toAnnotationProvider​(Class element)

      Since:
        5.3

    - #### findMethod

          public static final Method findMethod​(Class containingClass,
                                                String methodName,
                                                Class... parameterTypes)

    - #### toServiceDef3

          public static ServiceDef3 toServiceDef3​(ServiceDef sd)

      Since:
        5.3

    - #### toServiceDef2

          public static ServiceDef2 toServiceDef2​(ServiceDef sd)

    - #### toModuleDef2

          public static ModuleDef2 toModuleDef2​(ModuleDef md)

    - #### toServiceLifecycle2

          public static ServiceLifecycle2 toServiceLifecycle2​(ServiceLifecycle lifecycle)

      Since:
        5.1.0.2

    - #### matchAndSort

          public static <T extends Comparable<T>> List<T> matchAndSort​(Collection<? extends T> collection,
                                                                       Predicate<T> predicate)

      Since:
        5.2.0

    - #### toContributionDef2

          public static ContributionDef2 toContributionDef2​(ContributionDef contribution)

      Since:
        5.2.0

    - #### toContributionDef3

          public static ContributionDef3 toContributionDef3​(ContributionDef contribution)

    - #### toAdvisorDef2

          public static AdvisorDef2 toAdvisorDef2​(AdvisorDef advisor)

      Since:
        5.2.2

    - #### toDecoratorDef2

          public static DecoratorDef2 toDecoratorDef2​(DecoratorDef decorator)

      Since:
        5.2.2

    - #### isLocalFile

          public static boolean isLocalFile​(Class clazz)

      Determines if the indicated class is stored as a locally accessible file (and not, typically, as a file inside a JAR). This is related to automatic reloading of services.
      Since:
        5.2.0

    - #### toMapper

          public static <S,​T> Mapper<S,​T> toMapper​(Coercion<S,​T> coercion)

      Wraps a `Coercion` as a `Mapper`.
      Since:
        5.2.0

    - #### nextUUID

          public static long nextUUID()

      Generates a unique value for the current execution of the application. This initial UUID value is not easily predictable; subsequent UUIDs are allocated in ascending series.
      Since:
        5.2.0

    - #### getServiceId

          public static String getServiceId​(AnnotatedElement annotated)

      Extracts the service id from the passed annotated element. First the `ServiceId` annotation is checked. If present, its value is returned. Otherwise `Named` annotation is checked. If present, its value is returned. If neither of the annotations is present, `null` value is returned
      Parameters:
        `annotated` - annotated element to get annotations from
      Since:
        5.3

    - #### toAnnotationProvider

          public static AnnotationProvider toAnnotationProvider​(Method element)

    - #### createConstructorConstructionPlan

          public static <T> ObjectCreator<T> createConstructorConstructionPlan​(OperationTracker tracker,
                                                                               ObjectLocator locator,
                                                                               InjectionResources resources,
                                                                               org.slf4j.Logger logger,
                                                                               String description,
                                                                               Constructor<T> constructor)

    - #### createMethodInvocationPlan

          public static <T> ObjectCreator<T> createMethodInvocationPlan​(OperationTracker tracker,
                                                                        ObjectLocator locator,
                                                                        InjectionResources resources,
                                                                        org.slf4j.Logger logger,
                                                                        String description,
                                                                        Object instance,
                                                                        Method method)

    - #### realizeObjects

          public static Object[] realizeObjects​(ObjectCreator[] creators)

      Since:
        5.3.1, 5.4

    - #### sortedKeys

          public static List<String> sortedKeys​(Map map)

      Extracts the string keys from a map and returns them in sorted order. The keys are converted to strings.
      Parameters:
        `map` - the map to extract keys from (may be null)
      Returns:
        the sorted keys, or the empty set if map is null

    - #### toUserPresentable

          public static String toUserPresentable​(String id)

      Capitalizes the string, and inserts a space before each upper case character (or sequence of upper case characters). Thus "userId" becomes "User Id", etc. Also, converts underscore into space (and capitalizes the following word), thus "user_id" also becomes "User Id".

    - #### extractIdFromPropertyExpression

          public static String extractIdFromPropertyExpression​(String expression)

      Used to convert a property expression into a key that can be used to locate various resources (Blocks, messages, etc.). Strips out any punctuation characters, leaving just words characters (letters, number and the underscore).
      Parameters:
        `expression` - a property expression
      Returns:
        the expression with punctuation removed

    - #### defaultLabel

          public static String defaultLabel​(String id,
                                            Messages messages,
                                            String propertyExpression)

      Looks for a label within the messages based on the id. If found, it is used, otherwise the name is converted to a user presentable form.

    - #### replace

          public static String replace​(String input,
                                       Pattern pattern,
                                       String replacement)