Interface ObjectLocator

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      <T> T autobuild​(java.lang.Class<T> clazz)
      Autobuilds a class by finding the public constructor with the most parameters.
      <T> T autobuild​(java.lang.String description, java.lang.Class<T> clazz)
      <T> T getObject​(java.lang.Class<T> objectType, AnnotationProvider annotationProvider)
      Obtains an object indirectly, using the MasterObjectProvider service.
      <T> T getService​(java.lang.Class<T> serviceInterface)
      Locates a service given a service interface and (optionally) some marker annotation types.
      <T> T getService​(java.lang.Class<T> serviceInterface, java.lang.Class<? extends java.lang.annotation.Annotation>... markerTypes)
      Locates a service given a service interface and (optionally) some marker annotation types.
      <T> T getService​(java.lang.String serviceId, java.lang.Class<T> serviceInterface)
      Obtains a service via its unique service id.
      <T> T proxy​(java.lang.Class<T> interfaceClass, java.lang.Class<? extends T> implementationClass)
      Creates a proxy.
    • Method Detail

      • getService

        <T> T getService​(java.lang.String serviceId,
                         java.lang.Class<T> serviceInterface)
        Obtains a service via its unique service id. Returns the service's proxy. The service proxy implements the same interface as the actual service, and is used to instantiate the actual service only as needed (this is transparent to the application).
        Type Parameters:
        T -
        Parameters:
        serviceId - unique Service id used to locate the service object (may contain symbols, which will be expanded), case is ignored
        serviceInterface - the interface implemented by the service (or an interface extended by the service interface)
        Returns:
        the service instance
        Throws:
        java.lang.RuntimeException - if the service is not defined, or if an error occurs instantiating it
      • getService

        <T> T getService​(java.lang.Class<T> serviceInterface)
        Locates a service given a service interface and (optionally) some marker annotation types. A single service must implement the service interface (which * can be hard to guarantee) and by marked by all the marker types. The search takes into account inheritance of the service interface (not the service implementation), which may result in a failure due to extra matches.
        Parameters:
        serviceInterface - the interface the service implements
        Returns:
        the service's proxy
        Throws:
        java.lang.RuntimeException - if the service does not exist (this is considered programmer error), or multiple services directly implement, or extend from, the service interface
        See Also:
        Marker
      • getService

        <T> T getService​(java.lang.Class<T> serviceInterface,
                         java.lang.Class<? extends java.lang.annotation.Annotation>... markerTypes)
        Locates a service given a service interface and (optionally) some marker annotation types. A single service must implement the service interface (which * can be hard to guarantee) and by marked by all the marker types. The search takes into account inheritance of the service interface (not the service implementation), which may result in a failure due to extra matches. The ability to specify marker annotation types was added in 5.3
        Parameters:
        serviceInterface - the interface the service implements
        markerTypes - Markers used to select a specific service that implements the interface
        Returns:
        the service's proxy
        Throws:
        java.lang.RuntimeException - if the service does not exist (this is considered programmer error), or multiple services directly implement, or extend from, the service interface
        Since:
        5.3
        See Also:
        Marker
      • getObject

        <T> T getObject​(java.lang.Class<T> objectType,
                        AnnotationProvider annotationProvider)
        Obtains an object indirectly, using the MasterObjectProvider service.
        Type Parameters:
        T -
        Parameters:
        objectType - the type of object to be returned
        annotationProvider - provides access to annotations on the field or parameter for which a value is to be obtained, which may be utilized in selecting an appropriate object, use null when annotations are not available (in which case, selection will be based only on the object type)
        Returns:
        the requested object
        See Also:
        ObjectProvider
      • autobuild

        <T> T autobuild​(java.lang.Class<T> clazz)
        Autobuilds a class by finding the public constructor with the most parameters. Services and other resources or dependencies will be injected into the parameters of the constructor and into private fields marked with the Inject annotation. There are two cases: constructing a service implementation, and constructing an arbitrary object. In the former case, many service resources are also available for injection, not just dependencies or objects provided via the MasterObjectProvider service.
        Type Parameters:
        T -
        Parameters:
        clazz - the type of object to instantiate
        Returns:
        the instantiated instance
        Throws:
        java.lang.RuntimeException - if the autobuild fails
      • proxy

        <T> T proxy​(java.lang.Class<T> interfaceClass,
                    java.lang.Class<? extends T> implementationClass)
        Creates a proxy. The proxy will defer invocation of autobuild(Class) until just-in-time (that is, first method invocation). In a limited number of cases, it is necessary to use such a proxy to prevent service construction cycles, particularly when contributing (directly or indirectly) to the MasterObjectProvider (which is itself at the heart of autobuilding). If the class file for the class is a file on the file system (not a file packaged in a JAR), then the proxy will autoreload: changing the class file will result in the new class being reloaded and re-instantiated (with dependencies).
        Type Parameters:
        T -
        Parameters:
        interfaceClass - the interface implemented by the proxy
        implementationClass - a concrete class that implements the interface
        Returns:
        a proxy
        See Also:
        autobuild(Class)