javax.media.jai.remote
Class PlanarImageServerProxy

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

All Implemented Interfaces:

ImageJAI, PropertyChangeEmitter, PropertySource, RemoteRenderedImage, RenderedImage, WritablePropertySource

public abstract class PlanarImageServerProxy

extends PlanarImage

implements RemoteRenderedImage

A subclass of PlanarImage which represents an image on a remote server machine. This class is also an implementation of the RemoteRenderedImage interface. This class allows processing to occur on the remote server machine.

Conceptually this class is like a No-op, all it provides is a mechanism allowing the processing to occur on a server. Note that this class does not mandate that the client-server communication rely on any particular wire protocol or communication protocol. A subclass can choose any wire or communication protocol to communicate with its server. This is accomplished by having the subclass implement the methods declared to be abstract in this class. All functionality in this class is then implemented in terms of these abstract methods.

Network errors (detected via throws of RemoteImagingException) 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. 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. 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.

The resultant image layout is computed and provided by the concrete subclass by implementing the abstract method getImageLayout. All the accessor methods dealing with the layout variables namely getMinX(), getMinY(), getWidth(), getHeight(), getMaxX(), getMaxY(), getTileWidth(), getTileHeight(), getTileGridXOffset(), getTileGridYOffset(), getColorModel() and getSampleModel() are implemented in terms of the getImageLayout() method. The implementation of these methods uses retries and retry intervals to deal with Network errors, such that the subclass implementing getImageLayout() does not need to worry about Network errors except to signal them by throwing a RemoteImagingException. The same applies to the other abstract methods implemented by sub-classes namely getRemoteProperty(), getRemotePropertyNames() and computeTile().

The getTile method (abstract in this class' superclass), is implemented in terms of the computeTile method. It provides the additional functionality of caching the tiles on the client, as well as that of dealing with Network errors as mentioned above.

Since:

JAI 1.1

See Also:

RemoteImagingException

Field Summary

protected TileCache	cache A reference to a centralized TileCache object.
protected RenderingHints	hints The RenderingHints for the operation.
protected NegotiableCapabilitySet	negotiated The set of properties agreed upon after the negotiation process between the client and the server has been completed.
protected int	numRetries The number of retries.
protected String	operationName The name of the operation to be performed remotely.
protected ParameterBlock	paramBlock The sources and/or arguments to the operation.
protected NegotiableCapabilitySet	preferences The preferences to be utilized in the negotiation.
protected String	protocolName The name of the protocol to be used for remote communication.
protected OperationRegistry	registry A reference to the OperationRegistry object.
protected int	retryInterval Time in milliseconds between retries.
protected String	serverName The String representing the remote server machine.
protected Object	tileCacheMetric Metric used to produce an ordered list of tiles.

Fields inherited from class javax.media.jai.PlanarImage

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

Constructor Summary

PlanarImageServerProxy(String serverName, String protocolName, String operationName, ParameterBlock paramBlock, RenderingHints hints)
Constructs a PlanarImageServerProxy using the specified name of the server to perform the specified operation on, using the sources and parameters specified by the supplied ParameterBlock and supplied RenderingHints.

Method Summary

abstract Raster	computeTile(int tileX, int tileY) Returns tile (tileX, tileY) as computed on the remote server machine.
protected void	finalize() Uncaches all the tiles when this image is garbage collected.
ColorModel	getColorModel() Overrides the method in PlanarImage to return the ColorModel of the remote image.
int	getHeight() Overrides the method in PlanarImage to return the height of the remote image.
abstract ImageLayout	getImageLayout() Get the layout of the image.
int	getMaxX() Overrides the method in PlanarImage to return the X coordinate of the column immediately to the right of the rightmost column of the remote image.
int	getMaxY() Overrides the method in PlanarImage to return the Y coordinate of the row immediately below the bottom row of the remote image.
int	getMinX() Overrides the method in PlanarImage to return the X coordinate of the leftmost column of the remote image.
int	getMinY() Overrides the method in PlanarImage to return the Y coordinate of the uppermost row of the remote image.
NegotiableCapability	getNegotiatedValue(String category) Returns the results of the negotiation process for the given category.
NegotiableCapabilitySet	getNegotiatedValues() Returns the results of the negotiation process.
NegotiableCapabilitySet	getNegotiationPreferences() Returns the current negotiation preferences or null, if none were set previously.
int	getNumRetries() Returns the number of retries.
String	getOperationName() Returns the operation name as a String.
ParameterBlock	getParameterBlock() Returns the ParameterBlock that specifies the sources and parameters for the operation to be performed by this PlanarImageServerProxy.
Object	getProperty(String name) Gets a property from the property set of this image.
String[]	getPropertyNames() Returns a list of property names that are recognized by this image or null if none are recognized.
String	getProtocolName() Returns the String that identifies the remote imaging protocol.
abstract Object	getRemoteProperty(String name) Returns a property from the property set generated on the remote server machine.
abstract String[]	getRemotePropertyNames() Returns a list of names recognized by the getRemoteProperty method.
RenderingHints	getRenderingHints() Returns the RenderingHints associated with the operation to be performed by this PlanarImageServerProxy.
int	getRetryInterval() Returns the amount of time between retries in milliseconds.
SampleModel	getSampleModel() Overrides the method in PlanarImage to return the SampleModel of the remote image.
String	getServerName() Returns the String that identifies the server.
Raster	getTile(int tileX, int tileY) Returns the tile (tileX, tileY).
TileCache	getTileCache() Returns the tile cache object of this image by reference.
Object	getTileCacheMetric() Returns the tileCacheMetric instance variable by reference.
int	getTileGridXOffset() Overrides the method in PlanarImage to return the X coordinate of the upper-left pixel of tile (0, 0) remotely.
int	getTileGridYOffset() Overrides the method in PlanarImage to return the Y coordinate of the upper-left pixel of tile (0, 0) remotely.
int	getTileHeight() Overrides the method in PlanarImage to return the height of a tile remotely.
int	getTileWidth() Overrides the method in PlanarImage to return the width of a tile remotely.
int	getWidth() Overrides the method in PlanarImage to return the width of the remote image.
abstract Rectangle	mapDestRect(Rectangle destRect, int sourceIndex) Returns a conservative estimate of the region of a specified source that is required in order to compute the pixels of a given destination rectangle.
abstract Rectangle	mapSourceRect(Rectangle sourceRect, int sourceIndex) Returns a conservative estimate of the destination region that can potentially be affected by the pixels of a rectangle of a given source.
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	setRetryInterval(int retryInterval) Sets the amount of time between retries in milliseconds.
void	setTileCache(TileCache cache) Sets the tile cache object of this image.

Methods inherited from class javax.media.jai.PlanarImage

addPropertyChangeListener, addPropertyChangeListener, addSink, addSink, addSource, addTileComputationListener, cancelTiles, copyData, copyData, copyExtendedData, createColorModel, createSnapshot, dispose, getAsBufferedImage, getAsBufferedImage, getBounds, getData, getData, getDefaultColorModel, getExtendedData, getGraphics, getMaxTileX, getMaxTileY, getMinTileX, getMinTileY, getNumBands, getNumSources, getNumXTiles, getNumYTiles, getProperties, getPropertyClass, getPropertyNames, getSinks, getSource, getSourceImage, getSourceObject, getSources, getSplits, getTileComputationListeners, getTileIndices, getTileRect, getTiles, getTiles, prefetchTiles, queueTiles, removeProperty, removePropertyChangeListener, removePropertyChangeListener, removeSink, removeSink, removeSinks, removeSource, removeSources, removeTileComputationListener, setImageLayout, setProperties, setProperty, setSource, setSources, 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

retryInterval

protected int retryInterval

Time in milliseconds between retries.

numRetries

protected int numRetries

The number of retries.

cache

protected transient TileCache cache

A reference to a centralized TileCache object.

tileCacheMetric

protected Object tileCacheMetric

Metric used to produce an ordered list of tiles. This determines which tiles are removed from the cache first if a memory control operation is required.

registry

protected transient OperationRegistry registry

A reference to the OperationRegistry object.

serverName

protected String serverName

The String representing the remote server machine.

protocolName

protected String protocolName

The name of the protocol to be used for remote communication.

operationName

protected String operationName

The name of the operation to be performed remotely.

paramBlock

protected ParameterBlock paramBlock

The sources and/or arguments to the operation.

hints

protected RenderingHints hints

The RenderingHints for the operation.

preferences

protected NegotiableCapabilitySet preferences

The preferences to be utilized in the negotiation.

negotiated

protected NegotiableCapabilitySet negotiated

The set of properties agreed upon after the negotiation process between the client and the server has been completed.

Constructor Detail

PlanarImageServerProxy

public PlanarImageServerProxy(String serverName,
                              String protocolName,
                              String operationName,
                              ParameterBlock paramBlock,
                              RenderingHints hints)

Constructs a PlanarImageServerProxy using the specified name of the server to perform the specified operation on, using the sources and parameters specified by the supplied ParameterBlock and supplied RenderingHints. If hints relating to the OperationRegistry, TileCache, retry interval, number of retries, tile caching metric or negotiation preferences are included in the specified RenderingHints object, they will be honored.

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:

serverName - The String identifying the remote server machine.

protocolName - The name of the remote imaging protocol.

operationName - The name of the operation.

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

hints - The hints for the operation.

Throws:

IllegalArgumentException - if operationName is null.

Method Detail

getServerName

public String getServerName()

Returns the String that identifies the server.

Specified by:

getServerName in interface RemoteRenderedImage

getProtocolName

public String getProtocolName()

Returns the String that identifies the remote imaging protocol.

Specified by:

getProtocolName in interface RemoteRenderedImage

getOperationName

public String getOperationName()

Returns the operation name as a String.

getParameterBlock

public ParameterBlock getParameterBlock()

Returns the ParameterBlock that specifies the sources and parameters for the operation to be performed by this PlanarImageServerProxy.

getRenderingHints

public RenderingHints getRenderingHints()

Returns the RenderingHints associated with the operation to be performed by this PlanarImageServerProxy.

getTileCache

public TileCache getTileCache()

Returns the tile cache object of this image by reference. If this image does not have a tile cache, this method returns null.

setTileCache

public void setTileCache(TileCache cache)

Sets the tile cache object of this image. A null input indicates that this image should have no tile cache and subsequently computed tiles will not be cached.

The existing cache object is informed to release all the currently cached tiles of this image.

Parameters:

cache - A cache object to be used for caching this image's tiles, or null if no tile caching is desired.

getTileCacheMetric

public Object getTileCacheMetric()

Returns the tileCacheMetric instance variable by reference.

getImageLayout

public abstract ImageLayout getImageLayout()
                                    throws RemoteImagingException

Get the layout of the image. This could be implemented by either asking the server to specify the layout, or have the client compute the image layout. The ImageLayout object returned must have all its fields initialized, else an Error will be thrown. Network errors encountered should be signalled by throwing a RemoteImagingException.

Throws:

RemoteImagingException - if an error condition during remote image processing occurs

Error - if all the fields in the ImageLayout are not initialized.

getRemoteProperty

public abstract Object getRemoteProperty(String name)
                                  throws RemoteImagingException

Returns a property from the property set generated on the remote server machine. Network errors encountered should be signalled by throwing a RemoteImagingException. If the property name is not recognized, java.awt.Image.UndefinedProperty will be returned.

Throws:

RemoteImagingException - if an error condition during remote image processing occurs

IllegalArgumentException - if name is null.

getRemotePropertyNames

public abstract String[] getRemotePropertyNames()
                                         throws RemoteImagingException

Returns a list of names recognized by the getRemoteProperty method. Network errors encountered should be signalled by throwing a RemoteImagingException.

Throws:

RemoteImagingException - if an error condition during remote image processing occurs

mapSourceRect

public abstract Rectangle mapSourceRect(Rectangle sourceRect,
                                        int sourceIndex)
                                 throws RemoteImagingException

Returns a conservative estimate of the destination region that can potentially be affected by the pixels of a rectangle of a given source. This can be implemented by either asking the server to compute the destination region, or by having the client compute the destination region. Network errors encountered should be signalled by throwing a RemoteImagingException.

Parameters:

sourceRect - The Rectangle in source coordinates.

sourceIndex - The index of the source image.

Returns:

A Rectangle indicating the potentially affected destination region, or null if the region is unknown.

Throws:

IllegalArgumentException - If the source index is negative or greater than that of the last source.

IllegalArgumentException - If sourceRect is null.

mapDestRect

public abstract Rectangle mapDestRect(Rectangle destRect,
                                      int sourceIndex)
                               throws RemoteImagingException

Returns a conservative estimate of the region of a specified source that is required in order to compute the pixels of a given destination rectangle. Either the server or the client can compute the source region to implement this method. Network errors encountered should be signalled by throwing a RemoteImagingException.

Parameters:

destRect - The Rectangle in destination coordinates.

sourceIndex - The index of the source image.

Returns:

A Rectangle indicating the required source region.

Throws:

IllegalArgumentException - If the source index is negative or greater than that of the last source.

IllegalArgumentException - If destRect is null.

computeTile

public abstract Raster computeTile(int tileX,
                                   int tileY)
                            throws RemoteImagingException

Returns tile (tileX, tileY) as computed on the remote server machine. Note that tileX and tileY are indices into the tile array, not pixel locations. The Raster that is returned is a copy. Network errors encountered should be signalled by throwing a RemoteImagingException.

Subclasses must implement this method to return a non-null value for all tile indices between getMinTile{X,Y} and getMaxTile{X,Y}, inclusive. Tile indices outside of this region should result in a return value of null.

Parameters:

tileX - the X index of the requested tile in the tile array.

tileY - the Y index of the requested tile in the tile array.

Throws:

RemoteImagingException - if an error condition during remote image processing occurs

getRetryInterval

public int getRetryInterval()

Returns the amount of time between retries in milliseconds.

Specified by:

getRetryInterval in interface RemoteRenderedImage

setRetryInterval

public void setRetryInterval(int retryInterval)

Sets the amount of time between retries in milliseconds.

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.

Specified by:

getNumRetries in interface RemoteRenderedImage

setNumRetries

public void setNumRetries(int numRetries)

Sets the number of retries.

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.

getMinX

public int getMinX()

Overrides the method in PlanarImage to return the X coordinate of the leftmost column of the remote image.

Specified by:

getMinX in interface RenderedImage

Overrides:

getMinX in class PlanarImage

getMaxX

public int getMaxX()

Overrides the method in PlanarImage to return the X coordinate of the column immediately to the right of the rightmost column of the remote image.

Overrides:

getMaxX in class PlanarImage

getMinY

public int getMinY()

Overrides the method in PlanarImage to return the Y coordinate of the uppermost row of the remote image.

Specified by:

getMinY in interface RenderedImage

Overrides:

getMinY in class PlanarImage

getMaxY

public int getMaxY()

Overrides the method in PlanarImage to return the Y coordinate of the row immediately below the bottom row of the remote image.

Overrides:

getMaxY in class PlanarImage

getWidth

public int getWidth()

Overrides the method in PlanarImage to return the width of the remote image.

Specified by:

getWidth in interface RenderedImage

Overrides:

getWidth in class PlanarImage

getHeight

public int getHeight()

Overrides the method in PlanarImage to return the height of the remote image.

Specified by:

getHeight in interface RenderedImage

Overrides:

getHeight in class PlanarImage

getTileWidth

public int getTileWidth()

Overrides the method in PlanarImage to return the width of a tile remotely.

Specified by:

getTileWidth in interface RenderedImage

Overrides:

getTileWidth in class PlanarImage

getTileHeight

public int getTileHeight()

Overrides the method in PlanarImage to return the height of a tile remotely.

Specified by:

getTileHeight in interface RenderedImage

Overrides:

getTileHeight in class PlanarImage

getTileGridXOffset

public int getTileGridXOffset()

Overrides the method in PlanarImage to return the X coordinate of the upper-left pixel of tile (0, 0) remotely.

Specified by:

getTileGridXOffset in interface RenderedImage

Overrides:

getTileGridXOffset in class PlanarImage

getTileGridYOffset

public int getTileGridYOffset()

Overrides the method in PlanarImage to return the Y coordinate of the upper-left pixel of tile (0, 0) remotely.

Specified by:

getTileGridYOffset in interface RenderedImage

Overrides:

getTileGridYOffset in class PlanarImage

getSampleModel

public SampleModel getSampleModel()

Overrides the method in PlanarImage to return the SampleModel of the remote image.

Specified by:

getSampleModel in interface RenderedImage

Overrides:

getSampleModel in class PlanarImage

getColorModel

public ColorModel getColorModel()

Overrides the method in PlanarImage to return the ColorModel of the remote image.

Specified by:

getColorModel in interface RenderedImage

Overrides:

getColorModel in class PlanarImage

getProperty

public Object getProperty(String name)

Gets a property from the property set of this image. If the property name is not recognized, java.awt.Image.UndefinedProperty will be returned. The property to be returned is first looked for in the set of locally cached properties. If not found, the getRemoteProperty method is called to retrieve the property. Network errors that might be encountered during the getRemoteProperty call are dealt with by retries and retry intervals.

Specified by:

getProperty in interface RenderedImage

Overrides:

getProperty in class PlanarImage

Parameters:

name - the name of the property to get, as a String.

Returns:

a reference to the property Object, or the value java.awt.Image.UndefinedProperty.

Throws:

RemoteImagingException - if the limit of retries is exceeded.

getPropertyNames

public String[] getPropertyNames()

Returns a list of property names that are recognized by this image or null if none are recognized. The list of recognized property names consists of the locally cached property names (retrieved via super.getPropertyNames) as well as those that might be generated by the operations performed on the remote server machine (retrieved via getRemotePropertyNames). Network errors that might be encountered during the getRemotePropertyNames method are dealt with by retries and retry intervals.

Specified by:

getPropertyNames in interface RenderedImage

Overrides:

getPropertyNames in class PlanarImage

Returns:

an array of Strings containing valid property names.

Throws:

RemoteImagingException - if the limit of retries is exceeded.

getTile

public Raster getTile(int tileX,
                      int tileY)

Returns the tile (tileX, tileY). Note the tileX and tileY are indices into the tile array and not pixel positions. This method is implemented in terms of the computeTile method. This method deals with Network errors (recognized as RemoteImagingExceptions) through retries and retry intervals. This method also performs caching of tiles, so that an already computed tile does not need to be re-computed.

Specified by:

getTile in interface RenderedImage

Overrides:

getTile in class PlanarImage

Parameters:

tileX - the X index of the tile.

tileY - the Y index of the tile.

Throws:

RemoteImagingException - if limit of retries is exceeded.

finalize

protected void finalize()
                 throws Throwable

Uncaches all the tiles when this image is garbage collected.

Overrides:

finalize in class PlanarImage

Tags copied from class: PlanarImage

Throws:

Throwable - if an error occurs in the garbage collector.

getNegotiationPreferences

public NegotiableCapabilitySet getNegotiationPreferences()

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

Specified by:

getNegotiationPreferences in interface RemoteRenderedImage

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. Everytime this method is called, new preferences are specified for the negotiation, which takes place anew to produce a new set of negotiated resultant values to be used in the remote communication. If the subclass wants to ignore the negotiation preferences newly set, this method can be overridden to do so.

Specified by:

setNegotiationPreferences in interface RemoteRenderedImage

Parameters:

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

getNegotiatedValues

public NegotiableCapabilitySet getNegotiatedValues()
                                            throws RemoteImagingException

Returns the results of the negotiation process. This will return null if no negotiation preferences were set, and no negotiation was performed, or if the negotiation failed.

Specified by:

getNegotiatedValues in interface RemoteRenderedImage

getNegotiatedValue

public NegotiableCapability getNegotiatedValue(String category)
                                        throws RemoteImagingException

Returns the results of the negotiation process for the given category. This will return null if no negotiation preferences were set, and no negotiation was performed, or if the negotiation failed.

Specified by:

getNegotiatedValue in interface RemoteRenderedImage

Parameters:

category - The category to return the negotiated results for.

Throws:

IllegalArgumentException - if category is null.