File	Doc	Category	Size	Date	Package
ServiceRegistry.java	API Doc	Java SE 5 API	30012	Fri Aug 26 14:57:32 BST 2005	javax.imageio.spi

ServiceRegistry

• java.lang.Object

META-INF/services/javax.someapi.SomeService 

com.mycompany.mypkg.MyService

Fields Summary
private Map	categoryMap

Constructors Summary

public ServiceRegistry(Iterator categories) Constructs a ServiceRegistry instance with a set of categories taken from the categories argument. param categories an Iterator containing Class objects to be used to define categories. exception IllegalArgumentException if categories is null. if (categories == null) { throw new IllegalArgumentException("categories == null!"); } while (categories.hasNext()) { Class category = (Class)categories.next(); SubRegistry reg = new SubRegistry(this, category); categoryMap.put(category, reg); }

Methods Summary
public boolean	contains(java.lang.Object provider) Returns true if provider is currently registered. param provider the service provider object to be queried. return true if the given provider has been registered. exception IllegalArgumentException if provider is null. if (provider == null) { throw new IllegalArgumentException("provider == null!"); } Iterator regs = getSubRegistries(provider); while (regs.hasNext()) { SubRegistry reg = (SubRegistry)regs.next(); if (reg.contains(provider)) { return true; } } return false;
public void	deregisterAll(java.lang.Class category) Deregisters all service provider object currently registered under the given category. param category the category to be emptied. exception IllegalArgumentException if there is no category corresponding to category. SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } reg.clear();
public void	deregisterAll() Deregisters all currently registered service providers from all categories. Iterator iter = categoryMap.values().iterator(); while (iter.hasNext()) { SubRegistry reg = (SubRegistry)iter.next(); reg.clear(); }
public void	deregisterServiceProvider(java.lang.Object provider) Removes a service provider object from all categories that contain it. param provider the service provider object to be deregistered. exception IllegalArgumentException if provider is null. if (provider == null) { throw new IllegalArgumentException("provider == null!"); } Iterator regs = getSubRegistries(provider); while (regs.hasNext()) { SubRegistry reg = (SubRegistry)regs.next(); reg.deregisterServiceProvider(provider); }
public boolean	deregisterServiceProvider(T provider, java.lang.Class category) Removes a service provider object from the given category. If the provider was not previously registered, nothing happens and false is returned. Otherwise, true is returned. If an object of the same class as provider but not equal (using ==) to provider is registered, it will not be deregistered. If provider implements the RegisterableService interface, its onDeregistration method will be called. param provider the service provider object to be deregistered. param category the category from which to deregister the provider. return true if the provider was previously registered in the same category category, false otherwise. exception IllegalArgumentException if provider is null. exception IllegalArgumentException if there is no category corresponding to category. exception ClassCastException if provider does not implement the class defined by category. if (provider == null) { throw new IllegalArgumentException("provider == null!"); } SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } if (!category.isAssignableFrom(provider.getClass())) { throw new ClassCastException(); } return reg.deregisterServiceProvider(provider);
public void	finalize() Finalizes this object prior to garbage collection. The deregisterAll method is called to deregister all currently registered service providers. This method should not be called from application code. exception Throwable if an error occurs during superclass finalization. deregisterAll(); super.finalize();
public java.util.Iterator	getCategories() Returns an Iterator of Class objects indicating the current set of categories. The iterator will be empty if no categories exist. return an Iterator containing Classobjects. Set keySet = categoryMap.keySet(); return keySet.iterator();
public T	getServiceProviderByClass(java.lang.Class providerClass) Returns the currently registered service provider object that is of the given class type. At most one object of a given class is allowed to be registered at any given time. If no registered object has the desired class type, null is returned. param providerClass the Class of the desired service provider object. return a currently registered service provider object with the desired Classtype, or null is none is present. exception IllegalArgumentException if providerClass is null. if (providerClass == null) { throw new IllegalArgumentException("providerClass == null!"); } Iterator iter = categoryMap.keySet().iterator(); while (iter.hasNext()) { Class c = (Class)iter.next(); if (c.isAssignableFrom(providerClass)) { SubRegistry reg = (SubRegistry)categoryMap.get(c); T provider = reg.getServiceProviderByClass(providerClass); if (provider != null) { return provider; } } } return null;
public java.util.Iterator	getServiceProviders(java.lang.Class category, boolean useOrdering) Returns an Iterator containing all registered service providers in the given category. If useOrdering is false, the iterator will return all of the server provider objects in an arbitrary order. Otherwise, the ordering will respect any pairwise orderings that have been set. If the graph of pairwise orderings contains cycles, any providers that belong to a cycle will not be returned. param category the category to be retrieved from. param useOrdering true if pairwise orderings should be taken account in ordering the returned objects. return an Iterator containing service provider objects from the given category, possibly in order. exception IllegalArgumentException if there is no category corresponding to category. SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } return reg.getServiceProviders(useOrdering);
public java.util.Iterator	getServiceProviders(java.lang.Class category, javax.imageio.spi.ServiceRegistry$Filter filter, boolean useOrdering) Returns an Iterator containing service provider objects within a given category that satisfy a criterion imposed by the supplied ServiceRegistry.Filter object's filter method. The useOrdering argument controls the ordering of the results using the same rules as getServiceProviders(Class, boolean). param category the category to be retrieved from. param filter an instance of ServiceRegistry.Filter whose filter method will be invoked. param useOrdering true if pairwise orderings should be taken account in ordering the returned objects. return an Iterator containing service provider objects from the given category, possibly in order. exception IllegalArgumentException if there is no category corresponding to category. SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } Iterator iter = getServiceProviders(category, useOrdering); return new FilterIterator(iter, filter);
private java.util.Iterator	getSubRegistries(java.lang.Object provider) Returns an Iterator containing the subregistries to which the provider belongs. List l = new ArrayList(); Iterator iter = categoryMap.keySet().iterator(); while (iter.hasNext()) { Class c = (Class)iter.next(); if (c.isAssignableFrom(provider.getClass())) { l.add((SubRegistry)categoryMap.get(c)); } } return l.iterator();
public static java.util.Iterator	lookupProviders(java.lang.Class providerClass, java.lang.ClassLoader loader) Searches for implementations of a particular service class using the given class loader. This method transforms the name of the given service class into a provider-configuration filename as described in the class comment and then uses the getResources method of the given class loader to find all available files with that name. These files are then read and parsed to produce a list of provider-class names. The iterator that is returned uses the given class loader to look up and then instantiate each element of the list. Because it is possible for extensions to be installed into a running Java virtual machine, this method may return different results each time it is invoked. param providerClass a Classobject indicating the class or interface of the service providers being detected. param loader the class loader to be used to load provider-configuration files and instantiate provider classes, or null if the system class loader (or, failing that the bootstrap class loader) is to be used. return An Iterator that yields provider objects for the given service, in some arbitrary order. The iterator will throw an Error if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated. exception IllegalArgumentException if providerClass is null. if (providerClass == null) { throw new IllegalArgumentException("providerClass == null!"); } return Service.providers(providerClass, loader);
public static java.util.Iterator	lookupProviders(java.lang.Class providerClass) Locates and incrementally instantiates the available providers of a given service using the context class loader. This convenience method is equivalent to: ClassLoader cl = Thread.currentThread().getContextClassLoader(); return Service.providers(service, cl); param providerClass a Classobject indicating the class or interface of the service providers being detected. return An Iterator that yields provider objects for the given service, in some arbitrary order. The iterator will throw an Error if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated. exception IllegalArgumentException if providerClass is null. if (providerClass == null) { throw new IllegalArgumentException("providerClass == null!"); } return Service.providers(providerClass);
public boolean	registerServiceProvider(T provider, java.lang.Class category) Adds a service provider object to the registry. The provider is associated with the given category. If provider implements the RegisterableService interface, its onRegistration method will be called. Its onDeregistration method will be called each time it is deregistered from a category, for example if a category is removed or the registry is garbage collected. param provider the service provide object to be registered. param category the category under which to register the provider. return true if no provider of the same class was previously registered in the same category category. exception IllegalArgumentException if provider is null. exception IllegalArgumentException if there is no category corresponding to category. exception ClassCastException if provider does not implement the Class defined by category. if (provider == null) { throw new IllegalArgumentException("provider == null!"); } SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } if (!category.isAssignableFrom(provider.getClass())) { throw new ClassCastException(); } return reg.registerServiceProvider(provider);
public void	registerServiceProvider(java.lang.Object provider) Adds a service provider object to the registry. The provider is associated within each category present in the registry whose Class it implements. If provider implements the RegisterableService interface, its onRegistration method will be called once for each category it is registered under. Its onDeregistration method will be called each time it is deregistered from a category or when the registry is finalized. param provider the service provider object to be registered. exception IllegalArgumentException if provider is null. if (provider == null) { throw new IllegalArgumentException("provider == null!"); } Iterator regs = getSubRegistries(provider); while (regs.hasNext()) { SubRegistry reg = (SubRegistry)regs.next(); reg.registerServiceProvider(provider); }
public void	registerServiceProviders(java.util.Iterator providers) Adds a set of service provider objects, taken from an Iterator to the registry. Each provider is associated within each category present in the registry whose Class it implements. For each entry of providers that implements the RegisterableService interface, its onRegistration method will be called once for each category it is registered under. Its onDeregistration method will be called each time it is deregistered from a category or when the registry is finalized. param providers an Iterator containing service provider objects to be registered. exception IllegalArgumentException if providers is null or contains a null entry. if (providers == null) { throw new IllegalArgumentException("provider == null!"); } while (providers.hasNext()) { registerServiceProvider(providers.next()); }
public boolean	setOrdering(java.lang.Class category, T firstProvider, T secondProvider) Sets a pairwise ordering between two service provider objects within a given category. If one or both objects are not currently registered within the given category, or if the desired ordering is already set, nothing happens and false is returned. If the providers previously were ordered in the reverse direction, that ordering is removed. The ordering will be used by the getServiceProviders methods when their useOrdering argument is true. param category a Class object indicating the category under which the preference is to be established. param firstProvider the preferred provider. param secondProvider the provider to which firstProvider is preferred. return true if a previously unset ordering was established. exception IllegalArgumentException if either provider is null or they are the same object. exception IllegalArgumentException if there is no category corresponding to category. if (firstProvider == null || secondProvider == null) { throw new IllegalArgumentException("provider is null!"); } if (firstProvider == secondProvider) { throw new IllegalArgumentException("providers are the same!"); } SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } if (reg.contains(firstProvider) && reg.contains(secondProvider)) { return reg.setOrdering(firstProvider, secondProvider); } return false;
public boolean	unsetOrdering(java.lang.Class category, T firstProvider, T secondProvider) Sets a pairwise ordering between two service provider objects within a given category. If one or both objects are not currently registered within the given category, or if no ordering is currently set between them, nothing happens and false is returned. The ordering will be used by the getServiceProviders methods when their useOrdering argument is true. param category a Class object indicating the category under which the preference is to be disestablished. param firstProvider the formerly preferred provider. param secondProvider the provider to which firstProvider was formerly preferred. return true if a previously set ordering was disestablished. exception IllegalArgumentException if either provider is null or they are the same object. exception IllegalArgumentException if there is no category corresponding to category. if (firstProvider == null || secondProvider == null) { throw new IllegalArgumentException("provider is null!"); } if (firstProvider == secondProvider) { throw new IllegalArgumentException("providers are the same!"); } SubRegistry reg = (SubRegistry)categoryMap.get(category); if (reg == null) { throw new IllegalArgumentException("category unknown!"); } if (reg.contains(firstProvider) && reg.contains(secondProvider)) { return reg.unsetOrdering(firstProvider, secondProvider); } return false;