Class ServiceRegistry

public ServiceRegistry(Iterator> categories)

Constructs a ServiceRegistry for the specified service categories.

Parameters:

categories - the categories to support

Throws:

IllegalArgumentException - if categories is null, or if its Iterator.next() method returns null.

ClassCastException - if categories does not iterate over instances of Class.

public  Iterator getServiceProviders(Class category,
                                           boolean useOrdering)

Retrieves all providers that have been registered for the specified service category.

Parameters:

category - the service category whose providers are to be retrieved.

useOrdering - true in order to retrieve the providers in an order imposed by the ordering constraints; false in order to retrieve the providers in any order.

Throws:

IllegalArgumentException - if category is not among the categories passed to the constructor of this ServiceRegistry.

See Also:

getServiceProviders(Class, Filter, boolean)

public  Iterator getServiceProviders(Class category,
                                           ServiceRegistry.Filter filter,
                                           boolean useOrdering)

Retrieves all providers that have been registered for the specified service category and that satisfy the criteria of a custom filter.

Parameters:

category - the service category whose providers are to be retrieved.

filter - a custom filter, or null to retrieve all registered providers for the specified category.

useOrdering - true in order to retrieve the providers in an order imposed by the ordering constraints; false in order to retrieve the providers in any order.

Throws:

IllegalArgumentException - if category is not among the categories passed to the constructor of this ServiceRegistry.

public static  Iterator lookupProviders(Class spi)

Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.

Parameters:

spi - the service provider interface which must be implemented by any loaded service providers.

Returns:

an iterator over instances of spi.

Throws:

IllegalArgumentException - if spi is null.

See Also:

lookupProviders(Class, ClassLoader)

public static  Iterator lookupProviders(Class spi,
                                              ClassLoader loader)

Finds service providers that are implementing the specified Service Provider Interface.

On-demand loading: Loading and initializing service providers is delayed as much as possible. The rationale is that typical clients will iterate through the set of installed service providers until one is found that matches some criteria (like supported formats, or quality of service). In such scenarios, it might make sense to install only the frequently needed service providers on the local machine. More exotic providers can be put onto a server; the server will only be contacted when no suitable service could be found locally.

Security considerations: Any loaded service providers are loaded through the specified ClassLoader, or the system ClassLoader if classLoader is null. When lookupProviders is called, the current AccessControlContext gets recorded. This captured security context will determine the permissions when services get loaded via the next() method of the returned Iterator.

Parameters:

spi - the service provider interface which must be implemented by any loaded service providers.

loader - the class loader that will be used to load the service providers, or null for the system class loader. For using the context class loader, see lookupProviders(Class).

Returns:

an iterator over instances of spi.

Throws:

IllegalArgumentException - if spi is null.

public  T getServiceProviderByClass(Class providerClass)

Returns one of the service providers that is a subclass of the specified class.

Parameters:

providerClass - a class to search for.

public  boolean deregisterServiceProvider(T provider,
                                             Class category)

De-registers a provider for the specified service category.

If provider implements the RegisterableService interface, its onDeregistration method is invoked in order to inform the provider about the removal from this registry.

Parameters:

provider - the service provider to be de-registered.

category - the service category from which provider shall be de-registered.

Returns:

true if provider was previously registered for the specified service category; false if if the provider had not been registered.

Throws:

IllegalArgumentException - if provider is null, or if category is not among the categories passed to the constructor of this ServiceRegistry.

ClassCastException - if provider does not implement category.

public  boolean registerServiceProvider(T provider,
                                           Class category)

Registers a provider for the specified service category.

If provider implements the RegisterableService interface, its onRegistration method is invoked in order to inform the provider about the addition to this registry.

Parameters:

provider - the service provider to be registered.

category - the service category under which provider shall be registered.

Returns:

true if provider is the first provider that gets registered for the specified service category; false if other providers have already been registered for the same servide category.

Throws:

IllegalArgumentException - if provider is null, or if category is not among the categories passed to the constructor of this ServiceRegistry.

ClassCastException - if provider does not implement category.

public  boolean setOrdering(Class category,
                               T firstProvider,
                               T secondProvider)

Adds an ordering constraint on service providers.

Parameters:

category - the service category to which an ordering constraint is to be added.

firstProvider - the provider which is supposed to come before second.

secondProvider - the provider which is supposed to come after first.

Throws:

IllegalArgumentException - if first and second are referring to the same object, or if one of them is null.

See Also:

ServiceRegistry, getServiceProviders(Class, Filter, boolean)

public  boolean unsetOrdering(Class category,
                                 T firstProvider,
                                 T secondProvider)

Removes an ordering constraint on service providers.

Parameters:

category - the service category from which an ordering constraint is to be removed.

firstProvider - the provider which is supposed to come before second.

secondProvider - the provider which is supposed to come after first.

Throws:

IllegalArgumentException - if first and second are referring to the same object, or if one of them is null.

See Also:

ServiceRegistry

public boolean contains(Object provider)

Determines whether a provider has been registered with this registry.

Returns:

true if provider has been registered under any service category; false if it is not registered.

Throws:

IllegalArgumentException - if provider is null.

public void deregisterAll()

De-registers all service providers.

If a provider implements the RegisterableService interface, its onDeregistration method is invoked in order to inform the provider about the removal from this registry. If the provider implements several service categories, onDeregistration gets called multiple times.

public void deregisterAll(Class category)

De-registers all providers which have been registered for the specified service category.

If a provider implements the RegisterableService interface, its onDeregistration method is invoked in order to inform the provider about the removal from this registry. If the provider implements several service categories, onDeregistration gets called multiple times.

Parameters:

category - the category whose registered providers will be de-registered.

Throws:

IllegalArgumentException - if category is not among the categories passed to the constructor of this ServiceRegistry.

public void deregisterServiceProvider(Object provider)

De-registers a provider from all service categories it implements.

If provider implements the RegisterableService interface, its onDeregistration method is invoked in order to inform the provider about the removal from this registry. If provider implements several service categories, onDeregistration gets called multiple times.

Parameters:

provider - the service provider to be de-registered.

Throws:

IllegalArgumentException - if provider is null, or if provider does not implement any of the service categories passed to the constructor of this ServiceRegistry.

public void finalize()
            throws Throwable

Called by the Virtual Machine when it detects that this ServiceRegistry has become garbage. De-registers all service providers, which will cause those that implement RegisterableService to receive a onDeregistration notification.

Overrides:

finalize in interface Object

public Iterator> getCategories()

Returns an iterator over all service categories.

Returns:

an unmodifiable Iterator<Class>.

public void registerServiceProvider(Object provider)

Registers a provider under all service categories it implements.

If provider implements the RegisterableService interface, its onRegistration method is invoked in order to inform the provider about the addition to this registry. If provider implements several service categories, onRegistration gets called multiple times.

Parameters:

provider - the service provider to be registered.

Throws:

IllegalArgumentException - if provider is null, or if provider does not implement any of the service categories passed to the constructor of this ServiceRegistry.

public void registerServiceProviders(Iterator providers)

Registers a number of providers under all service categories they implement.

If a provider implements the RegisterableService interface, its onRegistration method is invoked in order to inform the provider about the addition to this registry. If provider implements several service categories, onRegistration gets called multiple times.

Throws:

IllegalArgumentException - if providers is null, if any iterated provider is null, or if some iterated provider does not implement any of the service categories passed to the constructor of this ServiceRegistry.