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, tileFactory, 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, createWritableRaster, dispose, getAsBufferedImage, getAsBufferedImage, getBounds, getData, getData, getDefaultColorModel, getExtendedData, getGraphics, getImageID, getMaxTileX, getMaxTileY, getMinTileX, getMinTileY, getNumBands, getNumSources, getNumXTiles, getNumYTiles, getProperties, getPropertyClass, getPropertyNames, getSinks, getSource, getSourceImage, getSourceObject, getSources, getSplits, getTileComputationListeners, getTileFactory, getTileIndices, getTileRect, getTiles, getTiles, overlapsMultipleTiles, 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
 
Methods inherited from interface javax.media.jai.remote.RemoteRenderedImage
setServerNegotiatedValues
 
Methods inherited from interface java.awt.image.RenderedImage
copyData, getData, getData, getMinTileX, getMinTileY, getNumXTiles, getNumYTiles, getSources
 

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
Following copied from class: javax.media.jai.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.