Java Doc for OperationRegistry.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » javax » media » jai » Java Source Code / Java DocumentationJava Source Code and Java Documentation

 |-object1-
 |-product1-|-object2-
 |-descriptor1-|          |-object3-
 |             |
 |             |          |-object1-
 |             |-product2-|-object2-
 |-mode1-|                        |-object3-
 |       |
 |-OperationRegistry-|       |                        |-object1-
 |       |             |-product1-|-object2-
 |       |-descriptor2-|          |-object3-
 |                     |
 |                     |          |-object1-
 |                     |-product2-|-object2-
 |                                |-object3-
 |
 |-mode2-|-descriptor1-|-object1--
 |
 |-descriptor2-|-object1--
 

The OperationRegistry class maps a descriptor name (for example, an image operation name) into the particular kind of factory object requested, capable of implementing the functionality described by the descriptor. The mapping is constructed in several stages:

At the highest level all objects are registered against some mode. A mode is specified by a String which must be one of those returned by RegistryMode.getModeNames(). Examples of known registry modes include "rendered", "renderable", "collection", "renderableCollection", "tileEncoder", "tileDecoder", "remoteRendered", "remoteRenderable", etc.

Each registry mode is associated with a RegistryElementDescriptor which describes some functionality to be implemented by factory objects associated with this descriptor. For example, the "rendered" registry mode is associated with OperationDescriptor.class and "tileEncoder" is associated with TileCodecDescriptor.class. Different registry modes can share the same RegistryElementDescriptor. For example "rendered", "renderable" (and other image operation registry modes) are all associated with OperationDescriptor.class.

If a registry mode supports preferences (for example "rendered", "tileEncoder" etc.), then the hierarchy of objects registered under that mode looks like that of "mode1" above. Descriptors are first registered against all modes that the specific instance supports. Each factory object that implements the functionality specified by that descriptor is registered against some product (name) under that descriptor. Preferences can be set among products under a given descriptor or among objects under a specific product/descriptor.

The ordering of such factory objects is determined by the order of the products attached to an OperationDescriptor, and by the order of the factory objects within each product. The orders are established by setting pairwise preferences, resulting in a partial order which is then sorted topologically. The results of creating a cycle are undefined.

The ordering of factory objects within a product is intended to allow vendors to create complex "fallback" chains. An example would be installing a RenderedImageFactory that implements separable convolution ahead of a RenderedImageFactory that implements a more general algorithm.

If a registry mode does not support preferences (for example, "renderable", "remoteRenderable" etc.) then the hierarchy of objects registered under that mode looks like that of "mode2" above. Only a single factory object belonging to this mode can be associated with a given descriptor. If multiple objects are registered under the same descriptor, the last one registered is retained.

The OperationRegistry has several methods to manage this hierarchy, which accept a modeName and work with Objects. The preferred manner of usage is through the type-safe wrapper class which are specific to each mode (for example RIFRegistry, CRIFRegistry etc.)

Vendors are encouraged to use unique product names (by means of the Java programming language convention of reversed Internet addresses) in order to maximize the likelihood of clean installation. See The Java Programming Language, §10.1 for a discussion of this convention in the context of package naming.

Users will, for the most part, only wish to set ordering preferences on the product level, since the factory object level orderings will be complex. However, it is possible for a knowledgable user to insert a specific factory object into an existing product for tuning purposes.

The OperationRegistry also has the responsibility of associating a set of PropertyGenerators with each descriptor. This set will be coalesced into a PropertySource suitable for use by the getPropertySource() method. If several PropertyGenerators associated with a particular descriptor generate the same property, only the last one to be registered will have any effect.

The registry handles all names (except class names) in a case-insensitive but retentive manner.

Initialization and automatic loading of registry objects.

The user has two options for automatic loading of registry objects.

• For most normal situations the user can create a "registryFile.jai" with entries for operators and preferences specific to their packages. This registry file must be put it in the META-INF directory of the jarfile or classpath.
• For situations where more control over the operation registry is needed, (for example remove an operator registered by JAI etc.) the user can implement a concrete sub-class of the OperationRegistrySpi interface and register it as service provider (see OperationRegistrySpi for more details). The updateRegistry method of such registered service providers will be called with the default OperationRegistry of JAI once it has been initialized.

The initialization of the OperationRegistry of the default instance of JAI happens as follows

1. Load the JAI distributed registry file "META-INF/javax.media.jai.registryFile.jai" (from jai_core.jar)
2. Find and load all "META-INF/registryFile.jai" files found in the classpath in some arbitrary order.
3. Look for registered service providers of OperationRegistrySpi listed in all "META-INF/services/javax.media.jai.OperationRegistrySpi" files found in the classpath and call their updateRegistry method passing in the default OperationRegistry. The order of these calls to updateRegistry is arbitrary.

The user could give the registry file a package qualified name for e.g xxx.yyy.registryFile.jai and put this in the META-INF directory of the jar file. Then in the concrete class that implements OperationRegistrySpi

 void updateRegistry(OperationRegistry or) {
 String registryFile = "META-INF/xxx.yyy.registryFile.jai";
 InputStream is = ClassLoader.getResourceAsStream(registryFile);
 or.updateFromStream(is);
 // Make other changes to "or" ...
 }
 

If none of the CIFs registered with this OperationRegistry returns a non-null value, null is returned.

All non-IO exceptions encountered while parsing the registry files are caught and their error messages are redirected to System.err.

If none of the RIFs registered with this OperationRegistry returns a non-null value, null is returned. Exceptions thrown by the RIFs will be caught by this method and will not be propagated.
Parameters:
  operationName - the operation name as a String.
Parameters:
  paramBlock - the operation's ParameterBlock.
Parameters:
  renderHints - a RenderingHints object containing rendering hints.
throws:
  IllegalArgumentException - if operationName is null.
See Also:   RIFRegistry.create

If none of the CIFs registered with this OperationRegistry returns a non-null value, null is returned. Exceptions thrown by the CIFs will be caught by this method and will not be propagated.
Parameters:
  operationName - The operation name as a String.
Parameters:
  args - The operation's input parameters.
Parameters:
  hints - A RenderingHints object containing rendering hints.
throws:
  IllegalArgumentException - if operationName is null.
See Also:   CIFRegistry.create

The InputStream passed in will not be closed by this method, the caller should close the InputStream when it is no longer needed.

The format of the data from the InputStream is expected to be the same as that of the writeExternal method as specified in the serialized form.
Parameters:
  in - The InputStream from which to read the data.
throws:
  IllegalArgumentException - if in is null.
See Also:   OperationRegistry.writeExternal

All non-IO exceptions encountered while parsing the registry files are caught and their error messages are redirected to System.err. If System.err is null the error messages will never be seen.
Parameters:
  in - An ObjectInput from which to read the data.
throws:
  IllegalArgumentException - if in is null.
See Also:   OperationRegistry.writeExternal

This is a convenience method to do automatic detection in runtime loaded jar files

Note that the JAI does not keep track of which JAR files have their registry files loaded and/or services initialized. Hence if registerServices is called twice with the same ClassLoader, the loading of the registry files and/or initialization of the services will happen twice.
since:
   JAI 1.1

The InputStream passed in will not be closed by this method, the caller should close the InputStream when it is no longer needed.

The format of the data from the InputStream is expected to be the same as that of the writeExternal method as specified in the serialized form.
Parameters:
  in - The InputStream from which to read the data.
throws:
  IllegalArgumentException - if in is null.
See Also:   OperationRegistry.writeExternal
since:
   JAI 1.1