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

Conceptually this class is very similar to the JAI class, except that the RemoteJAI class deals with remote operations. This class allows programmers to use the syntax:

 import javax.media.jai.remote.RemoteJAI;
 RemoteJAI rc = new RemoteJAI(protocolName, serverName);
 RemoteRenderedOp im = rc.create("convolve", paramBlock, renderHints);
 

If the OperationDescriptor associated with the named operation returns true from its isImmediate() method, the create() method will ask the RemoteRenderedOp it constructs to render itself immediately. If this rendering is null, create() will itself return null rather than returning an instance of RemoteRenderedOp as it normally does.

The registry being used by this class may be inspected or set using the getOperationRegistry() and setOperationRegistry() methods. Only experienced users should attempt to set the registry. This registry is used to map protocol names into either a RemoteRIF or a RemoteCRIF.

The TileCache associated with an instance may be similarly accessed.

Each instance of RemoteJAI contains a set of default rendering hints which will be used for all image creations. These hints are merged with any hints supplied to the create method; directly supplied hints take precedence over the common hints. When a new RemoteJAI instance is constructed, its hints are initialized to a copy of the default hints. Thus when an instance of RemoteJAI is constructed, hints for the default registry, tile cache, number of retries, and the retry interval are added to the set of common rendering hints. Similarly, invoking setOperationRegistry(), setTileCache(), setNumRetries() or setRetryInterval() on a RemoteJAI instance will cause the respective entity to be added to the common rendering hints. The hints associated with any instance may be manipulated using the getRenderingHints(), setRenderingHints(), clearRenderingHints() methods.

The TileCache to be used by a particular operation may be set during construction, or by calling the setTileCache() method. This will result in the provided tile cache being added to the set of common rendering hints.

Network errors are dealt with through the use of retry intervals and retries. Retries refers to the maximum number of times a remote operation will be retried. The retry interval refers to the amount of time (in milliseconds) between two consecutive retries. If errors are encountered at each retry and the number of specified retries has been exhausted, a RemoteImagingException will be thrown. By default, the number of retries is set to five, and the retry interval is set to a thousand milliseconds. These values can be changed by using the setNumRetries() and the setRetryInterval methods and can also be specified via the RenderingHints object passed as an argument to RemoteJAI.create(). Time outs (When the amount of time taken to get a response or the result of an operation from the remote machine exceeds a limit) are not dealt with, and must be taken care of by the network imaging protocol implementation itself. The implementation must be responsible for monitoring time outs, but on encountering one can deal with it by throwing a RemoteImagingException, which will then be dealt with using retries and retry intervals.

This class provides the capability of negotiating capabilities between the client and the server. The negotiate method uses the preferences specified via the setNegotiationPreferences method alongwith the server and client capabilities retrieved via the getServerCapabilities and getClientCapabilities respectively to negotiate on each of the preferences. This negotiation treats the client and server capabilities as being non-preferences, and the user set NegotiableCapabilitySet as being a preference. The negotiation is performed according to the rules described in the class documentation for NegotiableCapability.

Note that negotiation preferences can be set either prior to specifying a particular rendered or renderable operation (by using RemoteJAI.create() or RemoteJAI.createRenderable()) or afterwards. The currently set negotiation preferences are passed to the RemoteRenderedOp on its construction through the RenderingHints using the KEY_NEGOTIATION_PREFERENCES key. Since RemoteRenderableOp does not accept a RenderingHints object as a construction argument, the newly created RemoteRenderableOp is informed of these preferences using it's setRenderingHints() method. These preferences can be changed after the construction using the setNegotiationPreferences() method on both RemoteRenderedOp and RemoteRenderableOp. The same behavior applies to the number of retries and the retry interval, whether they be the default values contained in the default RenderingHints or whether they are set using the setNumRetries or setRetryInterval methods, the existing values are passed to RemoteRenderedOp's when they are created through the RenderingHints argument, and are set on the newly created RemoteRenderableOp using the setNumRetries or setRetryInterval methods on RemoteRenderableOp.
See Also:   JAI
See Also:   JAIRMIDescriptor
See Also:   RemoteImagingException
since:
   JAI 1.1

The supplied operation name is validated against the names of the OperationDescriptors returned from the getServerSupportedOperationList() method. The source(s) and/or parameter(s) in the ParameterBlock are validated against the named operation's descriptor, both in their numbers and types. Additional restrictions placed on the sources and parameters by an individual operation are also validated by calling its OperationDescriptor.validateRenderableArguments() method.

Parameters are allowed to have a null input value, if that particular parameter has a default value specified in its operation's descriptor.

An IllegalArgumentException may be thrown by the protocol specific classes at a later point, if null is provided as the serverName argument and null is not considered a valid serverName by the specified protocol.
Parameters:
  serverName - The String that identifiesthe server.
Parameters:
  protocolName - The String that identifiesthe remote imaging protocol.
Parameters:
  operationRegistry - The OperationRegistry associatedwith this class, if null, default will be used.
Parameters:
  tileCache - The TileCache associated withthis class, if null, default will be used.
throws:
  IllegalArgumentException - if protocolName is null.

The supplied operation name is validated against the names of the OperationDescriptors returned from the getServerSupportedOperationList() method. The source(s) and/or parameter(s) in the ParameterBlock are validated against the named operation's descriptor, both in their numbers and types. Additional restrictions placed on the sources and parameters by an individual operation are also validated by calling its OperationDescriptor.validateArguments() method.

Parameters are allowed to have a null input value, if that particular parameter has a default value specified in its operation's descriptor. In this case, the default value will replace the null input.

Unspecified tailing parameters are allowed, if these parameters have default values specified in the operation's descriptor. However, if a parameter, which has a default value, is followed by one or more parameters that have no default values, this parameter must be specified in the ParameterBlock, even if it only has a value of code>null.

The rendering hints associated with this instance of RemoteJAI are overlaid with the hints passed to this method. That is, the set of keys will be the union of the keys from the instance's hints and the hints parameter. If the same key exists in both places, the value from the hints parameter will be used.
Parameters:
  opName - The name of the operation.
Parameters:
  args - The source(s) and/or parameter(s) for the operation.
Parameters:
  hints - The hints for the operation.
throws:
  IllegalArgumentException - if opName isnull.
throws:
  IllegalArgumentException - if args isnull.
throws:
  IllegalArgumentException - if noOperationDescriptor is available from the serverwith the specified operation name.
throws:
  IllegalArgumentException - if theOperationDescriptor for the specifiedoperation name on the server does notsupport the "rendered" registry mode.
throws:
  IllegalArgumentException - if the specified operation doesnot produce ajava.awt.image.RenderedImage.
throws:
  IllegalArgumentException - if the specified operation isunable to handle the sources and parameters specified inargs. A RemoteRenderedOp that represents the namedoperation to be performed remotely, or nullif the specified operationis in the "immediate" mode and the rendering of thePlanarImage failed.

The supplied operation name is validated against the names of the OperationDescriptors returned from the getServerSupportedOperationList() method. The source(s) and/or parameter(s) in the ParameterBlock are validated against the named operation's descriptor, both in their numbers and types. Additional restrictions placed on the sources and parameters by an individual operation are also validated by calling its OperationDescriptor.validateRenderableArguments() method.

Parameters are allowed to have a null input value, if that particular parameter has a default value specified in its operation's descriptor. In this case, the default value will replace the null input.

Unspecified tailing parameters are allowed, if these parameters have default values specified in the operation's descriptor. However, if a parameter, which has a default value, is followed by one or more parameters that have no default values, this parameter must be specified in the ParameterBlock, even if it only has a value of code>null.
Parameters:
  opName - The name of the operation.
Parameters:
  args - The source(s) and/or parameter(s) for the operation.
throws:
  IllegalArgumentException - if opName isnull.
throws:
  IllegalArgumentException - if args isnull.
throws:
  IllegalArgumentException - if noOperationDescriptor is available from the serverwith the specified operation name.
throws:
  IllegalArgumentException - if theOperationDescriptor for the specifiedoperation name on the server does notsupport "renderable" registry mode.
throws:
  IllegalArgumentException - if the specified operation doesnot produce ajava.awt.image.renderable.RenderableImage.
throws:
  IllegalArgumentException - if the specified operation isunable to handle the sources and parameters specified inargs. A RemoteRenderableOp that represents the namedoperation to be performed remotely.

If a negotiation cycle has not been initiated prior to calling this method, or the negotiation preferences have been changed, this method will initiate a new negotiation cycle, which will create and return a new set of negotiated values.

If a negotiation cycle has not been initiated prior to calling this method, or the negotiation preferences have been changed, this method will initiate a new negotiation cycle, which will create and return a new negotiated value for the given category.
Parameters:
  category - The category to negotiate on.
throws:
  IllegalArgumentException - if category is null.

The negotiation process treats the serverCapabilities and the clientCapabilities as non-preferences and will throw an IllegalArgumentException if the isPreference method for either of these returns true. The preferences NegotiableCapabilitySet should return true from its isPreference method, otherwise an IllegalArgumentException will be thrown. The negotiation is done in accordance with the rules described in the class comments for NegotiableCapability.

If either the serverCapabilities or the clientCapabilities is null, then the negotiation will fail, and null will be returned. If preferences is null, the negotiation will become a two-way negotiation between the two non-null NegotiableCapabilitySets.
Parameters:
  preferences - The user preferences for the negotiation.
Parameters:
  serverCapabilities - The capabilities of the server.
Parameters:
  clientCapabilities - The capabilities of the client.
throws:
  IllegalArgumentException - if serverCapabilities is apreference, i.e., if it's isPreference() methodreturns true.
throws:
  IllegalArgumentException - if clientCapabilities is apreference, i.e., if it's isPreference() methodreturns true.
throws:
  IllegalArgumentException - if preferences is anon-preference, i.e., if it's isPreference() methodreturns false.

The negotiation process treats the serverCapabilities and the clientCapabilities as non-preferences and will throw an IllegalArgumentException if the isPreference method for either of these returns true. The preferences NegotiableCapabilitySet should return true from its isPreference method or an IllegalArgumentException will be thrown. The negotiation is done in accordance with the rules described in the class comments for NegotiableCapability.

If either the serverCapabilities or the clientCapabilities is null, then the negotiation will fail, and null will be returned. If preferences is null, the negotiation will become a two-way negotiation between the two non-null NegotiableCapabilitySets.
Parameters:
  preferences - The user preferences for the negotiation.
Parameters:
  serverCapabilities - The capabilities of the server.
Parameters:
  clientCapabilities - The capabilities of the client.
Parameters:
  category - The category to perform the negotiation on.
throws:
  IllegalArgumentException - if preferences is anon-preference, i.e., if it's isPreference() methodreturns false.
throws:
  IllegalArgumentException - if serverCapabilities is apreference, i.e., if it's isPreference() methodreturns true.
throws:
  IllegalArgumentException - if clientCapabilities is apreference, i.e., if it's isPreference() methodreturns true.
throws:
  IllegalArgumentException - if category is null.

Since a new set of preferences is set everytime this method is called, this method allows for changing negotiation preferences multiple times. However it should be noted that preferences set on this method are relevant only prior to the creation of an operation (using the RemoteJAI.create method). To change negotiation preferences on an operation after it has been created, the setNegotiationPreferences() method on the created RemoteRenderedOp should be used. The preferences parameter will be added to the RenderingHints of this RemoteJAI instance.