javax.media.jai.remote
Class RemoteRenderableOp

java.lang.Object
  extended byjavax.media.jai.RenderableOp
      extended byjavax.media.jai.remote.RemoteRenderableOp
All Implemented Interfaces:
OperationNode, PropertyChangeEmitter, PropertySource, RenderableImage, Serializable, WritablePropertySource

public class RemoteRenderableOp
extends RenderableOp

A subclass of RenderableOp for remote operations. This class represents a node in a remote renderable imaging chain. A RemoteRenderableOp stores a protocol name (as a String), a server name (as a String), an operation name (as a String), and a ParameterBlock containing sources and miscellaneous parameters.

By virtue of being a subclass of RemoteRenderableOp, this class participates in Java Bean-style events as specified by RenderableOp. RemoteRenderableOps add the server name and the protocol name to the critical attributes, the editing (chaging) of which may cause a PropertyChangeEventJAI to be emitted.

Since:
JAI 1.1
See Also:
RenderableOp, Serialized Form

Field Summary
protected  String protocolName
          The name of the protocol this class provides an implementation for.
protected  String serverName
          The name of the server.
 
Fields inherited from class javax.media.jai.RenderableOp
crif, eventManager, nodeSupport, properties, thePropertySource
 
Fields inherited from interface java.awt.image.renderable.RenderableImage
HINTS_OBSERVED
 
Constructor Summary
RemoteRenderableOp(OperationRegistry registry, String protocolName, String serverName, String opName, ParameterBlock pb)
          Constructs a RemoteRenderableOp using the specified operation registry, given the name of the remote imaging protocol, the name of the server to perform the operation on, the name of the operation to be performed remotely and a ParameterBlock containing RenderableImage sources and other parameters.
RemoteRenderableOp(String protocolName, String serverName, String opName, ParameterBlock pb)
          Constructs a RemoteRenderableOp using the default operation registry, given the name of the remote imaging protocol, the name of the server to perform the operation on, the name of the operation to be performed remotely and a ParameterBlock containing RenderableImage sources and other parameters.
 
Method Summary
 RenderedImage createRendering(RenderContext renderContext)
          Overrides the RenderableOp method to return a RemoteRenderedImage that represents the remote rendering of this image using a given RenderContext.
 float getHeight()
          Overrides the method in RenderableOp to return the rendering-independent height of the image, as queried from the remote server.
 float getMinX()
          Overrides the method in RenderableOp to return the minimum X coordinate of the rendering-independent image data, as queried from the remote server.
 float getMinY()
          Overrides the method in RenderableOp to return the maximum X coordinate of the rendering-independent image data, as queried from the remote server.
 NegotiableCapabilitySet getNegotiatedValues()
          Returns the results of the negotiation between the client and server capabilities according to the preferences set via the setNegotiationPreferences() method.
 NegotiableCapability getNegotiatedValues(String category)
          Returns the results of the negotiation between the client and server capabilities for the given catgory according to the preferences set via the setNegotiationPreferences() method.
 NegotiableCapabilitySet getNegotiationPreferences()
          Returns the current negotiation preferences or null, if none were set previously.
 int getNumRetries()
          Returns the number of retries.
 String getProtocolName()
          Returns the String that identifies the remote imaging protocol.
 String getRegistryModeName()
          Returns the name of the RegistryMode corresponding to this RenderableOp.
 int getRetryInterval()
          Returns the amount of time between retries in milliseconds.
 String getServerName()
          Returns the String that identifies the server.
 float getWidth()
          Overrides the method in RenderableOp to return the rendering-independent width of the image, as queried from the remote server.
 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 setProtocolAndServerNames(String protocolName, String serverName)
          Sets the protocol name and the server name of this RemoteRenderableOp to the specified arguments..
 void setProtocolName(String protocolName)
          Sets a String identifying the remote imaging protocol.
 void setRetryInterval(int retryInterval)
          Sets the amount of time between retries in milliseconds.
 void setServerName(String serverName)
          Sets a String identifying the server.
 
Methods inherited from class javax.media.jai.RenderableOp
addPropertyChangeListener, addPropertyChangeListener, addPropertyGenerator, copyPropertyFromSource, createDefaultRendering, createScaledRendering, getByteParameter, getCharParameter, getDoubleParameter, getDynamicProperty, getFloatParameter, getIntParameter, getLongParameter, getObjectParameter, getOperationName, getParameterBlock, getProperty, getPropertyClass, getPropertyNames, getPropertyNames, getRegistry, getRenderingHints, getShortParameter, getSource, getSources, isDynamic, removeProperty, removePropertyChangeListener, removePropertyChangeListener, removeSources, setOperationName, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameterBlock, setProperty, setRegistry, setRenderingHints, setSource, suppressProperty
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

protocolName

protected String protocolName
The name of the protocol this class provides an implementation for.


serverName

protected String serverName
The name of the server.

Constructor Detail

RemoteRenderableOp

public RemoteRenderableOp(String protocolName,
                          String serverName,
                          String opName,
                          ParameterBlock pb)
Constructs a RemoteRenderableOp using the default operation registry, given the name of the remote imaging protocol, the name of the server to perform the operation on, the name of the operation to be performed remotely and a ParameterBlock containing RenderableImage sources and other parameters. Any RenderedImage sources referenced by the ParameterBlock will be ignored.

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 server name by the specified protocol.

Parameters:
protocolName - The protocol name as a String.
serverName - The server name as a String.
opName - The operation name.
pb - The sources and other parameters. If null, it is assumed that this node has no sources and parameters.
Throws:
IllegalArgumentException - if protocolName is null.
IllegalArgumentException - if opName is null.

RemoteRenderableOp

public RemoteRenderableOp(OperationRegistry registry,
                          String protocolName,
                          String serverName,
                          String opName,
                          ParameterBlock pb)
Constructs a RemoteRenderableOp using the specified operation registry, given the name of the remote imaging protocol, the name of the server to perform the operation on, the name of the operation to be performed remotely and a ParameterBlock containing RenderableImage sources and other parameters. Any RenderedImage sources referenced by the ParameterBlock will be ignored.

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 server name by the specified protocol.

Parameters:
registry - The OperationRegistry to be used for instantiation. if null, the default registry is used.
protocolName - The protocol name as a String.
serverName - The server name as a String.
opName - The operation name.
pb - The sources and other parameters. If null, it is assumed that this node has no sources and parameters.
Throws:
IllegalArgumentException - if protocolName is null.
IllegalArgumentException - if opName is null.
Method Detail

getRegistryModeName

public String getRegistryModeName()
Returns the name of the RegistryMode corresponding to this RenderableOp. This method overrides the implementation in RenderableOp to always returns the String "remoteRenderable".

Specified by:
getRegistryModeName in interface OperationNode
Overrides:
getRegistryModeName in class RenderableOp

getServerName

public String getServerName()
Returns the String that identifies the server.


setServerName

public void setServerName(String serverName)
Sets a String identifying the server.

If the supplied name does not equal the current server name, a PropertyChangeEventJAI named "ServerName" will be fired. The oldValue field in the PropertyChangeEventJAI will contain the old server name String and the newValue field will contain the new server name String.

Parameters:
serverName - A String identifying the server.
Throws:
IllegalArgumentException - if serverName is null.

getProtocolName

public String getProtocolName()
Returns the String that identifies the remote imaging protocol.


setProtocolName

public void setProtocolName(String protocolName)
Sets a String identifying the remote imaging protocol.

If the supplied name does not equal the current protocol name, a PropertyChangeEventJAI named "ProtocolName" will be fired. The oldValue field in the PropertyChangeEventJAI will contain the old protocol name String and the newValue field will contain the new protocol name String.

Parameters:
protocolName - A String identifying the protocol.
Throws:
IllegalArgumentException - if protocolName is null.

setProtocolAndServerNames

public void setProtocolAndServerNames(String protocolName,
                                      String serverName)
Sets the protocol name and the server name of this RemoteRenderableOp to the specified arguments..

If both the supplied protocol name and the supplied server name values do not equal the current values, a PropertyChangeEventJAI named "ProtocolAndServerName" will be fired. The oldValue field in the PropertyChangeEventJAI will contain a two element array of Strings, the old protocol name being the first element and the old server name being the second. Similarly the newValue field of the PropertyChangeEventJAI will contain a two element array of Strings, the new protocol name being the first element and the new server name being the second. If only the supplied protocol name does not equal the current protocol name, a PropertyChangeEventJAI named "ProtocolName" will be fired. If only the supplied server name does not equal the current server name, a PropertyChangeEventJAI named "ServerName" will be fired.

Parameters:
protocolName - A String identifying the protocol.
serverName - A String identifying the server.
Throws:
IllegalArgumentException - if protocolName is null.
IllegalArgumentException - if serverName is null.

getWidth

public float getWidth()
Overrides the method in RenderableOp to return the rendering-independent width of the image, as queried from the remote server.

Specified by:
getWidth in interface RenderableImage
Overrides:
getWidth in class RenderableOp
Returns:
the image width as a float.

getHeight

public float getHeight()
Overrides the method in RenderableOp to return the rendering-independent height of the image, as queried from the remote server.

Specified by:
getHeight in interface RenderableImage
Overrides:
getHeight in class RenderableOp
Returns:
the image height as a float.

getMinX

public float getMinX()
Overrides the method in RenderableOp to return the minimum X coordinate of the rendering-independent image data, as queried from the remote server.

Specified by:
getMinX in interface RenderableImage
Overrides:
getMinX in class RenderableOp

getMinY

public float getMinY()
Overrides the method in RenderableOp to return the maximum X coordinate of the rendering-independent image data, as queried from the remote server.

Specified by:
getMinY in interface RenderableImage
Overrides:
getMinY in class RenderableOp

createRendering

public RenderedImage createRendering(RenderContext renderContext)
Overrides the RenderableOp method to return a RemoteRenderedImage that represents the remote rendering of this image using a given RenderContext. This is the most general way to obtain a rendering of a RemoteRenderableOp.

This method does not validate sources and parameters supplied in the ParameterBlock against the specification of the operation this node represents. It is the caller's responsibility to ensure that the data in the ParameterBlock are suitable for this operation. Otherwise, some kind of exception or error will occur.

RemoteJAI.createRenderable() is the method that does the validation. Therefore, it is strongly recommended that all RemoteRenderableOps are created using RemoteJAI.createRenderable().

The RenderContext may contain a Shape that represents the area-of-interest (aoi). If the aoi is specifed, it is still legal to return an image that's larger than this aoi. Therefore, by default, the aoi, if specified, is ignored at the rendering.

The RenderingHints in the RenderContext may contain negotiation preferences specified under the KEY_NEGOTIATION_PREFERENCES key. These preferences can be ignored by the rendering if it so chooses.

Specified by:
createRendering in interface RenderableImage
Overrides:
createRendering in class RenderableOp
Parameters:
renderContext - the RenderContext to use to produce the rendering.
Returns:
a RemoteRenderedImage containing the rendered data.

getRetryInterval

public int getRetryInterval()
Returns the amount of time between retries in milliseconds. If a value for the retry interval has been set previously by setRetryInterval(), the same value is returned, else the default retry interval as defined by RemoteJAI.DEFAULT_RETRY_INTERVAL is returned.


setRetryInterval

public void setRetryInterval(int retryInterval)
Sets the amount of time between retries in milliseconds.

This new value for retry interval will be stored and will be passed as RenderingHints as part of the RenderContext used to create the rendering. The RenderingHints in the RenderContext will contain this information under the KEY_RETRY_INTERVAL key. If the RenderingHints in the RenderContext already contains a retry interval value specified by the user, that will take preference over the one stored in this class.

Parameters:
retryInterval - The amount of time (in milliseconds) to wait between retries.
Throws:
IllegalArgumentException - if retryInterval is negative.

getNumRetries

public int getNumRetries()
Returns the number of retries. If a value for the number of retries has been set previously by setNumRetries(), the same value is returned, else the default number of retries as defined by RemoteJAI.DEFAULT_NUM_RETRIES is returned.


setNumRetries

public void setNumRetries(int numRetries)
Sets the number of retries.

This new value for number of retries will be stored and will be passed as RenderingHints as part of the RenderContext used to create the rendering. The RenderingHints in the RenderContext will contain this information under the KEY_NUM_RETRIES key. If the RenderingHints in the RenderContext already contains a number of retries value specified by the user, that will take preference over the one stored in this class.

Parameters:
numRetries - The number of times an operation should be retried in case of a network error.
Throws:
IllegalArgumentException - if numRetries is negative.

getNegotiationPreferences

public NegotiableCapabilitySet getNegotiationPreferences()
Returns the current negotiation preferences or null, if none were set previously.


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. Also each preference can be a list of values in decreasing order of preference, each value specified as a NegotiableCapability. The NegotiableCapability first (for a particular category) in this list is given highest priority in the negotiation process (for that category).

It may be noted that this method allows for multiple negotiation cycles by allowing negotiation preferences to be set multiple times. Every time this method is called, the new preferences specified will be stored, a negotiation with these new preferences will be initiated and the results stored. These new preferences which have been stored will be passed as RenderingHints as part of the RenderContext used to create the rendering. The RenderingHints in the RenderContext will contain this information under the KEY_NEGOTIATION_PREFERENCES key. If the RenderingHints in the RenderContext already contains negotiation preferences specified by the user, the user specified negotiation preferences will take preference over the ones stored in this class.

If preferences to be set are null, the negotiation will become a two-way negotiation between the client and server capabilities.

Parameters:
preferences - The preferences to be used in the negotiation process.

getNegotiatedValues

public NegotiableCapabilitySet getNegotiatedValues()
                                            throws RemoteImagingException
Returns the results of the negotiation between the client and server capabilities according to the preferences set via the setNegotiationPreferences() method. This will return null if no negotiation preferences were set, and no negotiation was performed, or if the negotiation failed.

Throws:
RemoteImagingException

getNegotiatedValues

public NegotiableCapability getNegotiatedValues(String category)
                                         throws RemoteImagingException
Returns the results of the negotiation between the client and server capabilities for the given catgory according to the preferences set via the setNegotiationPreferences() method. This will return null if no negotiation preferences were set, and no negotiation was performed, or if the negotiation failed.

Parameters:
category - The category to return negotiated results for.
Throws:
RemoteImagingException