javax.media.jai.remote
Class RemoteJAI

java.lang.Object
  |
  +--javax.media.jai.remote.RemoteJAI

public class RemoteJAI

extends Object

A convenience class for instantiating operations on remote machines. This class also provides information related to the server and allows for setting of parameters for the remote communication with the server.

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);
 

to create new images by applying operators that are executed remotely on the specified server. The create() method returns a RemoteRenderedOp encapsulating the protocol name, server name, operation name, parameter block, and rendering hints. Additionally, it performs validity checking on the operation parameters. The operation parameters are determined from the OperationDescriptor retrieved using the getServerSupportedOperationList() method. Programmers may also refer to RemoteJAI.createRenderable("opname", 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.

Since:

JAI 1.1

See Also:

JAI, JAIRMIDescriptor, RemoteImagingException

Field Summary

static int	DEFAULT_NUM_RETRIES The default number of retries.
static int	DEFAULT_RETRY_INTERVAL The amount of time to wait between retries (in Millseconds).
protected String	protocolName The name of the protocol used for client-server communication.
protected String	serverName The String representing the remote server machine.

Constructor Summary

RemoteJAI(String protocolName, String serverName)
Constructs a RemoteJAI instance with the given protocol name and server name.

RemoteJAI(String protocolName, String serverName, OperationRegistry registry, TileCache tileCache)
Constructs a RemoteJAI instance with the given protocol name, server name, OperationRegistry and TileCache.

Method Summary

void	clearRenderingHints() Clears the RenderingHints associated with this RemoteJAI instance.
RemoteRenderedOp	create(String opName, ParameterBlock args, RenderingHints hints) Creates a RemoteRenderedOp which represents the named operation to be performed remotely, using the source(s) and/or parameter(s) specified in the ParameterBlock, and applying the specified hints to the destination.
RemoteRenderableOp	createRenderable(String opName, ParameterBlock args) Creates a RemoteRenderableOp that represents the named operation to be performed remotely, using the source(s) and/or parameter(s) specified in the ParameterBlock.
NegotiableCapabilitySet	getClientCapabilities() Returns the set of capabilities supported by the client.
NegotiableCapabilitySet	getNegotiatedValues() Returns the results of the negotiation between the client and server capabilities according to the user preferences specified at an earlier time.
NegotiableCapability	getNegotiatedValues(String category) Returns the results of the negotiation between the client and server capabilities according to the user preferences specified at an earlier time for the given category.
int	getNumRetries() Returns the number of retries.
OperationRegistry	getOperationRegistry() Returns the OperationRegistry being used by this RemoteJAI instance.
String	getProtocolName() Returns the protocol name.
Object	getRenderingHint(RenderingHints.Key key) Returns the hint value associated with a given key in this RemoteJAI instance, or null if no value is associated with the given key.
RenderingHints	getRenderingHints() Returns the RenderingHints associated with this RemoteJAI instance.
int	getRetryInterval() Returns the amount of time between retries in milliseconds.
NegotiableCapabilitySet	getServerCapabilities() Returns the set of capabilites supported by the server.
String	getServerName() Returns a String identifying the remote server machine.
OperationDescriptor[]	getServerSupportedOperationList() Returns the list of OperationDescriptors that describe the operations supported by the server.
TileCache	getTileCache() Returns the TileCache being used by this RemoteJAI instance.
static NegotiableCapabilitySet	negotiate(NegotiableCapabilitySet preferences, NegotiableCapabilitySet serverCapabilities, NegotiableCapabilitySet clientCapabilities) This method negotiates the capabilities to be used in the remote communication.
static NegotiableCapability	negotiate(NegotiableCapabilitySet preferences, NegotiableCapabilitySet serverCapabilities, NegotiableCapabilitySet clientCapabilities, String category) This method negotiates the capabilities to be used in the remote communication for the given category.
void	removeRenderingHint(RenderingHints.Key key) Removes the hint value associated with a given key in this RemoteJAI instance.
void	setNegotiationPreferences(NegotiableCapabilitySet preferences) Sets the preferences to be used in the client-server communication.
void	setNumRetries(int numRetries) Sets the number of retries.
void	setOperationRegistry(OperationRegistry operationRegistry) Sets theOperationRegistry to be used by this RemoteJAI instance.
void	setRenderingHint(RenderingHints.Key key, Object value) Sets the hint value associated with a given key in this RemoteJAI instance.
void	setRenderingHints(RenderingHints hints) Sets the RenderingHints associated with this RemoteJAI instance.
void	setRetryInterval(int retryInterval) Sets the amount of time between retries in milliseconds.
void	setTileCache(TileCache tileCache) Sets the TileCache to be used by this RemoteJAI.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

serverName

protected String serverName

The String representing the remote server machine.

protocolName

protected String protocolName

The name of the protocol used for client-server communication.

DEFAULT_RETRY_INTERVAL

public static final int DEFAULT_RETRY_INTERVAL

The amount of time to wait between retries (in Millseconds).

DEFAULT_NUM_RETRIES

public static final int DEFAULT_NUM_RETRIES

The default number of retries.

Constructor Detail

RemoteJAI

public RemoteJAI(String protocolName,
                 String serverName)

Constructs a RemoteJAI instance with the given protocol name and server name. The semantics of the serverName are defined by the particular protocol used to create this class. Instructions on how to create a serverName that is compatible with this protocol can be retrieved from the getServerNameDocs() method on the RemoteDescriptor associated with the given protocolName. 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:

protocolName - The String that identifies the remote imaging protocol.

serverName - The String that identifies the server.

Throws:

IllegalArgumentException - if protocolName is null.

RemoteJAI

public RemoteJAI(String protocolName,
                 String serverName,
                 OperationRegistry registry,
                 TileCache tileCache)

Constructs a RemoteJAI instance with the given protocol name, server name, OperationRegistry and TileCache. If the specified OperationRegistry is null, the registry associated with the default JAI instance will be used. If the specified TileCache is null, the TileCache associated with the default JAI instance will be used.

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 identifies the server.

protocolName - The String that identifies the remote imaging protocol.

operationRegistry - The OperationRegistry associated with this class, if null, default will be used.

tileCache - The TileCache associated with this class, if null, default will be used.

Throws:

IllegalArgumentException - if protocolName is null.

Method Detail

getServerName

public String getServerName()

Returns a String identifying the remote server machine.

getProtocolName

public String getProtocolName()

Returns the protocol name.

setRetryInterval

public void setRetryInterval(int retryInterval)

Sets the amount of time between retries in milliseconds. The specified retryInterval parameter will be added to the common RenderingHints of this RemoteJAI instance, under the JAI.KEY_RETRY_INTERVAL key.

Parameters:

retryInterval - The time interval between retries (milliseconds).

Throws:

IllegalArgumentException - if retryInterval is negative.

getRetryInterval

public int getRetryInterval()

Returns the amount of time between retries in milliseconds.

setNumRetries

public void setNumRetries(int numRetries)

Sets the number of retries. The specified numRetries parameter will be added to the common RenderingHints of this RemoteJAI instance, under the JAI.KEY_NUM_RETRIES key.

Parameters:

numRetries - The number of retries.

Throws:

IllegalArgumentException - if numRetries is negative.

getNumRetries

public int getNumRetries()

Returns the number of retries.

getOperationRegistry

public OperationRegistry getOperationRegistry()

Returns the OperationRegistry being used by this RemoteJAI instance.

setOperationRegistry

public void setOperationRegistry(OperationRegistry operationRegistry)

Sets theOperationRegistry to be used by this RemoteJAI instance. The operationRegistry parameter will be added to the RenderingHints of this RemoteJAI instance.

Throws:

IllegalArgumentException - if operationRegistry is null.

setTileCache

public void setTileCache(TileCache tileCache)

Sets the TileCache to be used by this RemoteJAI. The tileCache parameter will be added to the RenderingHints of this RemoteJAI instance.

Throws:

IllegalArgumentException - if tileCache is null.

getTileCache

public TileCache getTileCache()

Returns the TileCache being used by this RemoteJAI instance.

getRenderingHints

public RenderingHints getRenderingHints()

Returns the RenderingHints associated with this RemoteJAI instance. These rendering hints will be merged with any hints supplied as an argument to the create() method.

setRenderingHints

public void setRenderingHints(RenderingHints hints)

Sets the RenderingHints associated with this RemoteJAI instance. These rendering hints will be merged with any hints supplied as an argument to the create() method.

Throws:

IllegalArgumentException - if hints is null.

clearRenderingHints

public void clearRenderingHints()

Clears the RenderingHints associated with this RemoteJAI instance.

getRenderingHint

public Object getRenderingHint(RenderingHints.Key key)

Returns the hint value associated with a given key in this RemoteJAI instance, or null if no value is associated with the given key.

Throws:

IllegalArgumentException - if key is null.

setRenderingHint

public void setRenderingHint(RenderingHints.Key key,
                             Object value)

Sets the hint value associated with a given key in this RemoteJAI instance.

Throws:

IllegalArgumentException - if key is null.

IllegalArgumentException - if value is null.

IllegalArgumentException - if value is not of the correct type for the given hint.

removeRenderingHint

public void removeRenderingHint(RenderingHints.Key key)

Removes the hint value associated with a given key in this RemoteJAI instance.

create

public RemoteRenderedOp create(String opName,
                               ParameterBlock args,
                               RenderingHints hints)

Creates a RemoteRenderedOp which represents the named operation to be performed remotely, using the source(s) and/or parameter(s) specified in the ParameterBlock, and applying the specified hints to the destination. This method should only be used when the final result returned is a single RemoteRenderedImage.

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.

args - The source(s) and/or parameter(s) for the operation.

hints - The hints for the operation.

Returns:

A RemoteRenderedOp that represents the named operation to be performed remotely, or null if the specified operation is in the "immediate" mode and the rendering of the PlanarImage failed.

Throws:

IllegalArgumentException - if opName is null.

IllegalArgumentException - if args is null.

IllegalArgumentException - if no OperationDescriptor is available from the server with the specified operation name.

IllegalArgumentException - if the OperationDescriptor for the specified operation name on the server does not support the "rendered" registry mode.

IllegalArgumentException - if the specified operation does not produce a java.awt.image.RenderedImage.

IllegalArgumentException - if the specified operation is unable to handle the sources and parameters specified in args.

createRenderable

public RemoteRenderableOp createRenderable(String opName,
                                           ParameterBlock args)

Creates a RemoteRenderableOp that represents the named operation to be performed remotely, using the source(s) and/or parameter(s) specified in the ParameterBlock. This method should only be used when the final result returned is a single RenderableImage.

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.

args - The source(s) and/or parameter(s) for the operation.

Returns:

A RemoteRenderableOp that represents the named operation to be performed remotely.

Throws:

IllegalArgumentException - if opName is null.

IllegalArgumentException - if args is null.

IllegalArgumentException - if no OperationDescriptor is available from the server with the specified operation name.

IllegalArgumentException - if the OperationDescriptor for the specified operation name on the server does not support "renderable" registry mode.

IllegalArgumentException - if the specified operation does not produce a java.awt.image.renderable.RenderableImage.

IllegalArgumentException - if the specified operation is unable to handle the sources and parameters specified in args.

setNegotiationPreferences

public void setNegotiationPreferences(NegotiableCapabilitySet preferences)

Sets the preferences to be used in the client-server communication. These preferences are utilized in the negotiation process. Note that preferences for more than one category can be specified using this method since NegotiableCapabilitySet allows different NegotiableCapability objects to be bundled up in one NegotiableCapabilitySet class. Even under the same category (as specified by the getCategory() method on NegotiableCapability), multiple NegotiableCapability objects can be added to the preferences. The preference added first for a particular category is given highest priority in the negotiation process.

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.

getNegotiatedValues

public NegotiableCapabilitySet getNegotiatedValues()
                                            throws RemoteImagingException

Returns the results of the negotiation between the client and server capabilities according to the user preferences specified at an earlier time. This will return null if the negotiation failed.

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.

getNegotiatedValues

public NegotiableCapability getNegotiatedValues(String category)
                                         throws RemoteImagingException

Returns the results of the negotiation between the client and server capabilities according to the user preferences specified at an earlier time for the given category. This method returns a NegotiableCapability object, that represents the result of the negotiation for the given category. If the negotiation failed, null will be returned.

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.

negotiate

public static NegotiableCapabilitySet negotiate(NegotiableCapabilitySet preferences,
                                                NegotiableCapabilitySet serverCapabilities,
                                                NegotiableCapabilitySet clientCapabilities)

This method negotiates the capabilities to be used in the remote communication. Upon completion of the negotiation process, this method returns a NegotiableCapabilitySet which contains an aggregation of the NegotiableCapability objects that represent the results of negotiation. If the negotiation fails, null will be returned.

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.

serverCapabilities - The capabilities of the server.

clientCapabilities - The capabilities of the client.

Throws:

IllegalArgumentException - if serverCapabilities is a preference, i.e., if it's isPreference() method returns true.

IllegalArgumentException - if clientCapabilities is a preference, i.e., if it's isPreference() method returns true.

IllegalArgumentException - if preferences is a non-preference, i.e., if it's isPreference() method returns false.

negotiate

public static NegotiableCapability negotiate(NegotiableCapabilitySet preferences,
                                             NegotiableCapabilitySet serverCapabilities,
                                             NegotiableCapabilitySet clientCapabilities,
                                             String category)

This method negotiates the capabilities to be used in the remote communication for the given category. Upon completion of the negotiation process, this method returns a NegotiableCapability object, that represents the result of the negotiation for the given category. If the negotiation fails, null will be returned.

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.

serverCapabilities - The capabilities of the server.

clientCapabilities - The capabilities of the client.

category - The category to perform the negotiation on.

Throws:

IllegalArgumentException - if preferences is a non-preference, i.e., if it's isPreference() method returns false.

IllegalArgumentException - if serverCapabilities is a preference, i.e., if it's isPreference() method returns true.

IllegalArgumentException - if clientCapabilities is a preference, i.e., if it's isPreference() method returns true.

IllegalArgumentException - if category is null.

getServerCapabilities

public NegotiableCapabilitySet getServerCapabilities()
                                              throws RemoteImagingException

Returns the set of capabilites supported by the server. If any network related errors are encountered by this method (identified as such by receiving a RemoteImagingException), they will be dealt with by the use of retries and retry intervals.

getClientCapabilities

public NegotiableCapabilitySet getClientCapabilities()

Returns the set of capabilities supported by the client.

getServerSupportedOperationList

public OperationDescriptor[] getServerSupportedOperationList()
                                                      throws RemoteImagingException

Returns the list of OperationDescriptors that describe the operations supported by the server. If any network related errors are encountered by this method (identified as such by receiving a RemoteImagingException), they will be dealt with by the use of retries and retry intervals.