ProviderLocator
Date: 2016-06-24

org.apache.geronimo.osgi.locator

## Class ProviderLocator

- java.lang.Object
- - org.apache.geronimo.osgi.locator.ProviderLocator

-     public class ProviderLocator
      extends java.lang.Object

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `destroy()` Cleanup resources on bundle shutdown.
    `static java.lang.Object` | `getService(java.lang.String iface, java.lang.Class<?> contextClass, java.lang.ClassLoader loader)` Get a single service instance that matches an interface definition.
    `static java.lang.Class<?>` | `getServiceClass(java.lang.String iface, java.lang.Class<?> contextClass, java.lang.ClassLoader loader)` Locate a service class that matches an interface definition.
    `static java.util.List<java.lang.Class<?>>` | `getServiceClasses(java.lang.String iface, java.lang.Class<?> contextClass, java.lang.ClassLoader loader)` Get a list of service class implementations that match an interface name.
    `static java.util.List<java.lang.Object>` | `getServices(java.lang.String iface, java.lang.Class<?> contextClass, java.lang.ClassLoader loader)` Get a list of services that match a given interface name.
    `static void` | `init(org.osgi.framework.BundleContext c)` initialize the tracker statics for this bundle
    `static java.lang.Class<?>` | `loadClass(java.lang.String className)` Utility class for locating a class with OSGi registry support.
    `static java.lang.Class<?>` | `loadClass(java.lang.String className, java.lang.Class<?> contextClass)` Utility class for locating a class with OSGi registry support.
    `static java.lang.Class<?>` | `loadClass(java.lang.String className, java.lang.Class<?> contextClass, java.lang.ClassLoader loader)` Standardized utility method for performing class lookups with support for OSGi registry lookups.
    `static java.lang.Class<?>` | `locate(java.lang.String providerId)` Locate a class by its provider id indicator.
    `static java.util.List<java.lang.Class<?>>` | `locateAll(java.lang.String providerId)` Locate all class files that match a given factory id.
    `static java.lang.String` | `lookupByJREPropertyFile(java.lang.String path, java.lang.String property)` Perform a service class discovery by looking for a property in a target properties file located in the java.home directory.

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

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

- - ### Method Detail

    - #### init

          public static void init(org.osgi.framework.BundleContext c)

      initialize the tracker statics for this bundle
      Parameters:
        `c` - The starup BundleContext.

    - #### destroy

          public static void destroy()

      Cleanup resources on bundle shutdown.

    - #### locate

          public static java.lang.Class<?> locate(java.lang.String providerId)

      Locate a class by its provider id indicator. .
      Parameters:
        `providerId` - The provider id (generally, a fully qualified class name).
      Returns:
        The Class corresponding to this provider id. Returns null if this is not registered or the indicated class can't be loaded.

    - #### locateAll

          public static java.util.List<java.lang.Class<?>> locateAll(java.lang.String providerId)

      Locate all class files that match a given factory id.
      Parameters:
        `providerId` - The target provider identifier.
      Returns:
        A List containing the class objects corresponding to the provider identifier. Returns an empty list if no matching classes can be located.

    - #### loadClass

          public static java.lang.Class<?> loadClass(java.lang.String className)
                                              throws java.lang.ClassNotFoundException

      Utility class for locating a class with OSGi registry support. Uses the thread context classloader as part of the search order.
      Parameters:
        `className` - The name of the target class.
      Returns:
        The loaded class.
      Throws:
        `java.lang.ClassNotFoundException` - Thrown if the class cannot be located.

    - #### loadClass

          public static java.lang.Class<?> loadClass(java.lang.String className,
                                     java.lang.Class<?> contextClass)
                                              throws java.lang.ClassNotFoundException

      Utility class for locating a class with OSGi registry support. Uses the thread context classloader as part of the search order.
      Parameters:
        `className` - The name of the target class.
      Returns:
        The loaded class.
      Throws:
        `java.lang.ClassNotFoundException` - Thrown if the class cannot be located.

    - #### loadClass

          public static java.lang.Class<?> loadClass(java.lang.String className,
                                     java.lang.Class<?> contextClass,
                                     java.lang.ClassLoader loader)
                                              throws java.lang.ClassNotFoundException

      Standardized utility method for performing class lookups with support for OSGi registry lookups.
      Parameters:
        `className` - The name of the target class.
        `loader` - An optional class loader.
      Returns:
        The loaded class
      Throws:
        `java.lang.ClassNotFoundException` - Thrown if the class cannot be loaded.

    - #### getService

          public static java.lang.Object getService(java.lang.String iface,
                                    java.lang.Class<?> contextClass,
                                    java.lang.ClassLoader loader)
                                             throws java.lang.Exception

      Get a single service instance that matches an interface definition.
      Parameters:
        `iface` - The name of the required interface.
        `contextClass` - The class requesting the lookup (used for class resolution).
        `loader` - A class loader to use for searching for service definitions and loading classes.
      Returns:
        The service instance, or null if no matching services can be found.
      Throws:
        `java.lang.Exception` - Thrown for any classloading or exceptions thrown trying to instantiate a service instance.

    - #### getServiceClass

          public static java.lang.Class<?> getServiceClass(java.lang.String iface,
                                           java.lang.Class<?> contextClass,
                                           java.lang.ClassLoader loader)
                                                    throws java.lang.ClassNotFoundException

      Locate a service class that matches an interface definition.
      Parameters:
        `iface` - The name of the required interface.
        `contextClass` - The class requesting the lookup (used for class resolution).
        `loader` - A class loader to use for searching for service definitions and loading classes.
      Returns:
        The located class, or null if no matching services can be found.
      Throws:
        `java.lang.Exception` - Thrown for any classloading exceptions thrown trying to load the class.
        `java.lang.ClassNotFoundException`

    - #### getServices

          public static java.util.List<java.lang.Object> getServices(java.lang.String iface,
                                                     java.lang.Class<?> contextClass,
                                                     java.lang.ClassLoader loader)
                                                              throws java.lang.Exception

      Get a list of services that match a given interface name. This searches both the current class path and the global repository for matches.
      Parameters:
        `iface` - The name of the required interface.
        `contextClass` - The class requesting the lookup (used for class resolution).
        `loader` - A class loader to use for searching for service definitions and loading classes.
      Returns:
        A list of matching services. Returns an empty list if there are no matches.
      Throws:
        `java.lang.Exception` - Thrown for any classloading or exceptions thrown trying to instantiate a service instance.

    - #### getServiceClasses

          public static java.util.List<java.lang.Class<?>> getServiceClasses(java.lang.String iface,
                                                             java.lang.Class<?> contextClass,
                                                             java.lang.ClassLoader loader)
                                                                      throws java.lang.Exception

      Get a list of service class implementations that match an interface name. This searches both the current class path and the global repository for matches.
      Parameters:
        `iface` - The name of the required interface.
        `contextClass` - The class requesting the lookup (used for class resolution).
        `loader` - A class loader to use for searching for service definitions and loading classes.
      Returns:
        A list of matching provider classes. Returns an empty list if there are no matches.
      Throws:
        `java.lang.Exception` - Thrown for any classloading exceptions thrown trying to load a provider class.

    - #### lookupByJREPropertyFile

          public static java.lang.String lookupByJREPropertyFile(java.lang.String path,
                                                 java.lang.String property)
                                                          throws java.io.IOException

      Perform a service class discovery by looking for a property in a target properties file located in the java.home directory.
      Parameters:
        `path` - The relative path to the desired properties file.
        `property` - The name of the required property.
      Returns:
        The value of the named property within the properties file. Returns null if the property doesn't exist or the properties file doesn't exist.
      Throws:
        `java.io.IOException`