javax.media.jai.remote
Class RemoteRenderedOp

java.lang.Object
  |
  +--javax.media.jai.PlanarImage
        |
        +--javax.media.jai.RenderedOp
              |
              +--javax.media.jai.remote.RemoteRenderedOp

All Implemented Interfaces:

EventListener, ImageJAI, OperationNode, PropertyChangeEmitter, PropertyChangeListener, PropertySource, RemoteRenderedImage, RenderedImage, Serializable, WritablePropertySource

public class RemoteRenderedOp

extends RenderedOp

implements RemoteRenderedImage

A node in a remote rendered imaging chain. This class is a concrete implementation of the RemoteRenderedImage interface. A RemoteRenderedOp stores a protocol name (as a String), a server name (as a String), an operation name (as a String), a ParameterBlock containing sources and miscellaneous parameters, and a RenderingHints containing rendering hints. A set of nodes may be joined together via the source Vectors within their ParameterBlocks to form a directed acyclic graph (DAG). The topology i.e., connectivity of the graph may be altered by changing the ParameterBlocks; the operation name, parameters, and rendering hints may also be changed.

Such chains represent and handle operations that are being performed remotely. They convey the structure of an imaging chain in a compact representation and can be used to influence the remote imaging process (through the use of retry interval, retries and negotiation preferences).

RemoteRenderedOps are a client side representation of the chain of operations taking place on the server.

The translation between RemoteRenderedOp chains and RemoteRenderedImage (usually PlanarImageServerProxy) chains makes use of two levels of indirection provided by the OperationRegistry and RemoteRIF facilities. First, the local OperationRegistry is used to map the protocol name into a RemoteRIF. This RemoteRIF then constructs one or more RemoteRenderedImages (usually PlanarImageServerProxys) to do the actual work (or returns a RemoteRenderedImage by other means. The OperationRegistry maps a protocol name into a RemoteRIF, since there is one to one correspondence between a protocol name and a RemoteRIF. This differs from the case of RenderedOps, where the OperationRegistry maps each operation name to a RenderedImageFactory (RIF), since there is a one to one correspondence between an operation name and a RIF. The RemoteRIFs are therefore protocol-specific and not operation specific, while a RIF is operation specific.

Once a protocol name has been mapped into a RemoteRIF, the RemoteRIF.create() method is used to create a rendering. This rendering is responsible for communicating with the server to perform the specified operation remotely.

By virtue of being a subclass of RenderedOp, this class participates in Java Bean-style events as specified by RenderedOp. This means that PropertyChangeEmitter methods may be used to register and unregister PropertyChangeListeners. RemoteRenderedOps are also PropertyChangeListeners so that they may be registered as listeners of other PropertyChangeEmitters or the equivalent. Each RemoteRenderedOp also automatically receives any RenderingChangeEvents emitted by any of its sources which are RenderedOps.

RemoteRenderedOps add the server name and the protocol name to the critical attributes, the editing (changing) of which, coupled with a difference in the old and new rendering over some non-empty region, may cause a RenderingChangeEvent to be emitted. As with RenderedOp, editing of a critical attribute of a RemoteRenderedOp will cause a PropertyChangeEventJAI detailing the change to be fired to all registered PropertyChangeListeners. RemoteRenderedOp registers itself as a PropertyChangeListener for all critical attributes, and thus receives all PropertyChangeEventJAI events generated by itself. This is done in order to allow the event handling code to generate a new rendering and reuse any tiles that might be valid after the critical argument change.

When a RemoteRenderedOp node receives a PropertyChangeEventJAI from itself, the region of the current rendering which is invalidated is computed using RemoteDescriptor.getInvalidRegion(). When a RemoteRenderedOp node receives a RenderingChangeEvent from one of its sources, the region of the current rendering which is invalidated is computed using the mapSourceRect() method of the current rendering and the invalid region of the source (retrieved using RenderingChangeEvent.getInvalidRegion()) If the complement of the invalid region contains any tiles of the current rendering, a new rendering of the node will be generated using the new source node and its rendering generated using that version of RemoteRIF.create() that updates the rendering of the node according to the specified PropertyChangeEventJAI. The identified tiles will be retained from the old rendering insofar as possible. This might involve for example adding tiles to a TileCache under the ownership of the new rendering. A RenderingChangeEvent will then be fired to all PropertyChangeListeners of the node, and to any node sinks that are PropertyChangeListeners. The newRendering parameter of the event constructor (which may be retrieved via the getNewValue() method of the event) will be set to either the new rendering of the node or to null if it was not possible to retain any tiles of the previous rendering.

Since:

JAI 1.1

See Also:

RenderedOp, RemoteRenderedImage, 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.RenderedOp

nodeSupport, theImage, thePropertySource

Fields inherited from class javax.media.jai.PlanarImage

colorModel, eventManager, height, minX, minY, properties, sampleModel, tileGridXOffset, tileGridYOffset, tileHeight, tileWidth, width

Constructor Summary

RemoteRenderedOp(OperationRegistry registry, String protocolName, String serverName, String opName, ParameterBlock pb, RenderingHints hints)
Constructs a RemoteRenderedOp that will be used to instantiate a particular rendered operation to be performed remotely using the specified operation registry, the name of the remote imaging protocol, the name of the server to perform the operation on, an operation name, a ParameterBlock, and a set of rendering hints.

RemoteRenderedOp(String protocolName, String serverName, String opName, ParameterBlock pb, RenderingHints hints)
Constructs a RemoteRenderedOp that will be used to instantiate a particular rendered operation to be performed remotely using the default operation registry, the name of the remote imaging protocol, the name of the server to perform the operation on, an operation name, a ParameterBlock, and a set of rendering hints.

Method Summary

protected PlanarImage	createInstance(boolean isNodeRendered) Overrides the RenderedOp method to allow the operation to be performed remotely.
NegotiableCapability	getNegotiatedValue(String category) Returns the results of the negotiation between the client and server capabilities for the given category according to the preferences set via the setNegotiationPreferences() method.
NegotiableCapabilitySet	getNegotiatedValues() Returns the results of the negotiation between the client and server capabilities 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 RemoteRenderedOp.
int	getRetryInterval() Returns the amount of time between retries in milliseconds.
String	getServerName() Returns the String that identifies the server.
void	propertyChange(PropertyChangeEvent evt) Implementation of PropertyChangeListener.
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 RemoteRenderedOp 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.
void	setServerNegotiatedValues(NegotiableCapabilitySet negotiatedValues) Informs the server of the negotiated values that are the result of a successful negotiation.

Methods inherited from class javax.media.jai.RenderedOp

addNodeSource, addPropertyGenerator, addSink, addSink, addSource, addSource, cancelTiles, copyData, copyData, copyPropertyFromSource, createInstance, createRendering, getByteParameter, getCharParameter, getColorModel, getCurrentRendering, getData, getData, getDoubleParameter, getDynamicProperty, getFloatParameter, getHeight, getIntParameter, getLongParameter, getMinX, getMinY, getNewRendering, getNodeSource, getNumParameters, getNumSources, getObjectParameter, getOperationName, getParameterBlock, getParameters, getProperty, getPropertyClass, getPropertyNames, getRegistry, getRendering, getRenderingHint, getRenderingHints, getSampleModel, getShortParameter, getSource, getSourceImage, getSourceObject, getSources, getTile, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTiles, getTileWidth, getWidth, prefetchTiles, queueTiles, removeProperty, removeSink, removeSink, removeSinks, removeSource, removeSource, removeSources, resetProperties, setNodeSource, setOperationName, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameter, setParameterBlock, setParameters, setProperty, setRegistry, setRenderingHint, setRenderingHints, setSource, setSource, setSources, suppressProperty

Methods inherited from class javax.media.jai.PlanarImage

addPropertyChangeListener, addPropertyChangeListener, addTileComputationListener, copyExtendedData, createColorModel, createSnapshot, dispose, finalize, getAsBufferedImage, getAsBufferedImage, getBounds, getDefaultColorModel, getExtendedData, getGraphics, getMaxTileX, getMaxTileY, getMaxX, getMaxY, getMinTileX, getMinTileY, getNumBands, getNumXTiles, getNumYTiles, getProperties, getPropertyNames, getSinks, getSplits, getTileComputationListeners, getTileIndices, getTileRect, getTiles, removePropertyChangeListener, removePropertyChangeListener, removeTileComputationListener, setImageLayout, setProperties, tileXToX, tileXToX, tileYToY, tileYToY, toString, wrapRenderedImage, XToTileX, XToTileX, YToTileY, YToTileY

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, 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

RemoteRenderedOp

public RemoteRenderedOp(String protocolName,
                        String serverName,
                        String opName,
                        ParameterBlock pb,
                        RenderingHints hints)

Constructs a RemoteRenderedOp that will be used to instantiate a particular rendered operation to be performed remotely using the default operation registry, the name of the remote imaging protocol, the name of the server to perform the operation on, an operation name, a ParameterBlock, and a set of rendering hints. All input parameters are saved by reference.

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.

The RenderingHints may contain negotiation preferences specified under the KEY_NEGOTIATION_PREFERENCES key.

Parameters:

protocolName - The protocol name as a String.

serverName - The server name as a String.

opName - The operation name.

pb - The sources and parameters. If null, it is assumed that this node has no sources and parameters.

hints - The rendering hints. If null, it is assumed that no hints are associated with the rendering.

Throws:

IllegalArgumentException - if protocolName is null.

IllegalArgumentException - if opName is null.

RemoteRenderedOp

public RemoteRenderedOp(OperationRegistry registry,
                        String protocolName,
                        String serverName,
                        String opName,
                        ParameterBlock pb,
                        RenderingHints hints)

Constructs a RemoteRenderedOp that will be used to instantiate a particular rendered operation to be performed remotely using the specified operation registry, the name of the remote imaging protocol, the name of the server to perform the operation on, an operation name, a ParameterBlock, and a set of rendering hints. All input parameters are saved by reference.

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.

The RenderingHints may contain negotiation preferences specified under the KEY_NEGOTIATION_PREFERENCES key.

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 parameters. If null, it is assumed that this node has no sources and parameters.

hints - The rendering hints. If null, it is assumed that no hints are associated with the rendering.

Throws:

IllegalArgumentException - if protocolName is null.

IllegalArgumentException - if opName is null.

Method Detail

getServerName

public String getServerName()

Returns the String that identifies the server.

Specified by:

getServerName in interface RemoteRenderedImage

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 and a RenderingChangeEvent may be fired if the node has already been rendered. 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.

Specified by:

getProtocolName in interface RemoteRenderedImage

setProtocolName

public void setProtocolName(String protocolName)

Sets a String identifying the remote imaging protocol. This method causes this RemoteRenderedOp to use the new protocol name with the server name set on this node previously. If the server is not compliant with the new protocol name, the setProtocolAndServerNames() method should be used to set a new protocol name and a compliant new server name at the same time.

If the supplied name does not equal the current protocol name, a PropertyChangeEventJAI named "ProtocolName" will be fired and a RenderingChangeEvent may be fired if the node has already been rendered. 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 server.

Throws:

IllegalArgumentException - if protocolName is null.

setProtocolAndServerNames

public void setProtocolAndServerNames(String protocolName,
                                      String serverName)

Sets the protocol name and the server name of this RemoteRenderedOp 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.

getRegistryModeName

public String getRegistryModeName()

Returns the name of the RegistryMode corresponding to this RemoteRenderedOp. This method overrides the implementation in RenderedOp to always returns the String "remoteRendered".

Overrides:

getRegistryModeName in class RenderedOp

createInstance

protected PlanarImage createInstance(boolean isNodeRendered)

Overrides the RenderedOp method to allow the operation to be performed remotely.

Overrides:

createInstance in class RenderedOp

Tags copied from class: RenderedOp

Throws:

RuntimeException - if the image factory charged with rendering the node is unable to create a rendering.

See Also:

RenderedOp.createInstance()

propertyChange

public void propertyChange(PropertyChangeEvent evt)

Implementation of PropertyChangeListener.

When invoked with an event which is an instance of RenderingChangeEvent the node will respond by re-rendering itself while retaining any tiles possible.

Overrides:

propertyChange in class RenderedOp

Tags copied from class: RenderedOp

See Also:

TiledImage.propertyChange(java.beans.PropertyChangeEvent)

getRetryInterval

public int getRetryInterval()

Returns the amount of time between retries in milliseconds.

If this RemoteRenderedOp has been rendered, then its getRetryInterval() method will be called to return the current retry interval. If no rendering has been created, and a value was set using the setRetryInterval() method), that value will be returned, else the default retry interval as defined by RemoteJAI.DEFAULT_RETRY_INTERVAL is returned.

Specified by:

getRetryInterval in interface RemoteRenderedImage

setRetryInterval

public void setRetryInterval(int retryInterval)

Sets the amount of time between retries in milliseconds. If this RemoteRenderedOp has already been rendered, the setRetryInterval() method is called on the rendering to inform it of the new retry interval. The rendering can choose to ignore this new setting, in which case getRetryInterval() will still return the old value, or the rendering can honor these settings, in which case getRetryInterval() will return the new settings. If this RemoteRenderedOp has not been rendered, the new retry interval specified will be stored. These new stored retry interval will be passed as part of the RenderingHints using the KEY_RETRY_INTERVAL key, to the new rendering when it is created.

Specified by:

setRetryInterval in interface RemoteRenderedImage

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 this RemoteRenderedOp has been rendered, then its getNumRetries() method will be called to return the current number of retries. If no rendering has been created, and a value was set using the setNumRetries() method), that value will be returned, else the default retry interval as defined by RemoteJAI.DEFAULT_NUM_RETRIES is returned.

Specified by:

getNumRetries in interface RemoteRenderedImage

setNumRetries

public void setNumRetries(int numRetries)

Sets the number of retries. If this RemoteRenderedOp has already been rendered, the setNumRetries() method is called on the rendering to inform it of the new number of retries. The rendering can choose to ignore these new settings, in which case getNunRetries() will still return the old values, or the rendering can honor these new settings in which case getNumRetries() will return the new value. If this RemoteRenderedOp has not been rendered, the new setting specified will be stored. These new settings which have been stored will be passed as part of the RenderingHints using the KEY_NUM_RETRIES key, to the new rendering when it is created.

Specified by:

setNumRetries in interface RemoteRenderedImage

Parameters:

numRetries - The number of times an operation should be retried in case of a network error.

Throws:

IllegalArgumentException - if numRetries is negative.

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. If this RemoteRenderedOp has already been rendered, the setNegotiationPreferences() method is called on the rendering to inform it of the new preferences. The rendering can choose to ignore these new preferences, in which case getNegotiatedValues() will still return the results of the old negotiation, or the rendering can re-perform the negotiation, (using the RemoteJAI.negotiate, for example) in which case getNegotiatedValues() will return the new negotiated values. If this RemoteRenderedOp has not been rendered, 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 part of the RenderingHints using the KEY_NEGOTIATION_PREFERENCES key, to the new rendering when it is created.

Specified by:

setNegotiationPreferences in interface RemoteRenderedImage

Parameters:

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

getNegotiationPreferences

public NegotiableCapabilitySet getNegotiationPreferences()

Returns the current negotiation preferences or null, if none were set previously.

Specified by:

getNegotiationPreferences in interface RemoteRenderedImage

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.

If this RemoteRenderedOp has been rendered, then its getNegotiatedValues() method will be called to return the current negotiated values. If no rendering has been created, then the internally stored negotiated value (calculated when the new preferences were set using the setNegotiationPreferences() method) will be returned.

Specified by:

getNegotiatedValues in interface RemoteRenderedImage

getNegotiatedValue

public NegotiableCapability getNegotiatedValue(String category)
                                        throws RemoteImagingException

Returns the results of the negotiation between the client and server capabilities for the given category 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.

If this RemoteRenderedOp has been rendered, then its getNegotiatedValues() method will be called to return the current negotiated values. If no rendering has been created, then the internally stored negotiated value (calculated when the new preferences were set using the setNegotiationPreferences() method) will be returned.

Specified by:

getNegotiatedValue in interface RemoteRenderedImage

Parameters:

category - The category to return the negotiated results for.

setServerNegotiatedValues

public void setServerNegotiatedValues(NegotiableCapabilitySet negotiatedValues)
                               throws RemoteImagingException

Informs the server of the negotiated values that are the result of a successful negotiation. If this RemoteRenderedOp has been rendered, then the rendering's setServerNegotiatedValues method will be called to inform the server of the negotiated results. If no rendering has been created, this method will do nothing.

Specified by:

setServerNegotiatedValues in interface RemoteRenderedImage

Parameters:

negotiatedValues - The result of the negotiation.