Conceptually this class is very similar to the JAI
* class, except that the RemoteJAI class deals with
* remote operations. This class allows programmers to use the syntax:
*
*
* import javax.media.jai.remote.RemoteJAI;
* RemoteJAI rc = new RemoteJAI(protocolName, serverName);
* RemoteRenderedOp im = rc.create("convolve", paramBlock, renderHints);
*
*
* to create new images by applying operators that are executed remotely on
* the specified server. The create() method returns a
* RemoteRenderedOp encapsulating the protocol name, server
* name, operation name, parameter block, and rendering hints. Additionally,
* it performs validity checking on the operation parameters. The operation
* parameters are determined from the OperationDescriptor
* retrieved using the getServerSupportedOperationList() method.
* Programmers may also refer to
* RemoteJAI.createRenderable("opname", paramBlock, renderHints);
*
* If the OperationDescriptor associated with the
* named operation returns true from its
* isImmediate() method, the create()
* method will ask the RemoteRenderedOp it constructs to render
* itself immediately. If this rendering is null,
* create() will itself return null
* rather than returning an instance of RemoteRenderedOp
* as it normally does.
*
*
The registry being used by this class may be
* inspected or set using the getOperationRegistry() and
* setOperationRegistry() methods. Only experienced
* users should attempt to set the registry. This registry is used to
* map protocol names into either a RemoteRIF or a
* RemoteCRIF.
*
*
The TileCache associated with an instance may be
* similarly accessed.
*
*
Each instance of The Network errors are dealt with through the use of retry intervals and
* retries. Retries refers to the maximum number of times a remote operation
* will be retried. The retry interval refers to the amount of time (in
* milliseconds) between two consecutive retries. If errors are encountered
* at each retry and the number of specified retries has been exhausted, a
* This class provides the capability of negotiating capabilities
* between the client and the server. The Note that negotiation preferences can be set either prior to
* specifying a particular rendered or renderable operation (by using
* An The supplied operation name is validated against the
* names of the Parameters are allowed to have a Unspecified tailing parameters are allowed, if these
* parameters have default values specified in the operation's
* descriptor. However, if a parameter, which has a default value,
* is followed by one or more parameters that
* have no default values, this parameter must be specified in the
* The rendering hints associated with this instance of
* The supplied operation name is validated against the names
* of the Parameters are allowed to have a Unspecified tailing parameters are allowed, if these
* parameters have default values specified in the operation's
* descriptor. However, if a parameter, which
* has a default value, is followed by one or more parameters that
* have no default values, this parameter must be specified in the
* Since a new set of preferences is set everytime this method is
* called, this method allows for changing negotiation preferences
* multiple times. However it should be noted that preferences set on
* this method are relevant only prior to the creation of an
* operation (using the If a negotiation cycle has not been initiated prior to calling
* this method, or the negotiation preferences have been
* changed, this method will initiate a new negotiation cycle, which will
* create and return a new set of negotiated values.
*
* @returns A If a negotiation cycle has not been initiated prior to calling
* this method, or the negotiation preferences have been
* changed, this method will initiate a new negotiation cycle, which will
* create and return a new negotiated value for the given category.
*
* @param category The category to negotiate on.
* @throws IllegalArgumentException if category is null.
* @returns A The negotiation process treats the serverCapabilities and the
* clientCapabilities as non-preferences and will throw an
* If either the serverCapabilities or the clientCapabilities
* is null, then the negotiation will fail, and null will be returned.
* If preferences is null, the negotiation will become a two-way
* negotiation between the two non-null
* The negotiation process treats the serverCapabilities and the
* clientCapabilities as non-preferences and will throw an
* If either the serverCapabilities or the clientCapabilities
* is null, then the negotiation will fail, and null will be returned.
* If preferences is null, the negotiation will become a two-way
* negotiation between the two non-null
* Any implementation of the There are two The The class of the returned object will vary as a function of
* the nature of the operation. For rendered and renderable two-
* dimensional images this should be an instance of a class which
* implements While the The class of the returned object will vary as a function of
* the nature of the operation. For rendered and renderable two-
* dimensional images this should be an instance of a class which
* implements The implementation in this class always returns null as the
* invalid region signifying that there is no common region of validity.
* Since null is always returned, in the interests of efficiency, none
* of the checks for ensuring that the All factories that produce renderings for operations remotely
* must implement Classes that implement this interface must provide a
* constructor with no arguments.
*
* @since 1.1
*/
public interface RemoteRIF {
/**
* Creates a The Hints should be taken into account, but can be ignored.
* The created The Hints should be taken into account, but can be ignored.
* The created All remote operations that are to be used in a rendering-independent
* chain must provide a factory that implements Classes that implement this interface must provide a
* constructor with no arguments.
*
* @since 1.1
*/
public interface RemoteCRIF extends RemoteRIF {
/**
* Maps the operation's output If the This class is the remote equivalent of the 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 can be utilized to perform
* a new round of negotiation to produce new negotiated values to be
* used in the remote communication.
*
* @param preferences The preferences to be used in the negotiation
* process.
* @throws IllegalArgumentException if preferences is null.
*/
void setNegotiationPreferences(NegotiableCapabilitySet preferences);
/**
* 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.
*/
NegotiableCapabilitySet getNegotiatedValues()
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.
*
* @param String category The category to get the negotiated results for.
* @throws IllegalArgumentException if category is null.
*/
NegotiableCapability getNegotiatedValue(String category)
throws RemoteImagingException;
/**
* Informs the server of the negotiated values that are the result of
* a successful negotiation.
*
* @param negotiatedValues The result of the negotiation.
*/
void setServerNegotiatedValues(NegotiableCapabilitySet negotiatedValues)
throws RemoteImagingException;
}
4.12 RemoteRenderedOp
--------------------
package javax.media.jai.remote;
/**
* A node in a remote rendered imaging chain. This class is a concrete
* implementation of the 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).
*
* The translation between Once a protocol name has been mapped into a By virtue of being a subclass of When a An The An The If the supplied name does not equal the current server name, a
* If the supplied name does not equal the current protocol name, a
* If both the supplied protocol name and the supplied server
* name values do not equal the current values, a
* When invoked with an event which is an instance of
* If this If this It may be noted that this method allows for multiple negotiation
* cycles by allowing negotiation preferences to be set
* multiple times. If this If this If this 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
* The resultant image layout is computed and provided by the concrete
* subclass by implementing the abstract method The An The existing cache object is informed to release all the
* currently cached tiles of this image.
*
* @param cache A cache object to be used for caching this image's
* tiles, or Subclasses must implement this method to return a
* non- 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.
*
* @param preferences The preferences to be used in the negotiation
* process.
*/
public void setNegotiationPreferences(NegotiableCapabilitySet preferences)
{}
/**
* 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.
*/
public synchronized NegotiableCapabilitySet getNegotiatedValues()
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.
*
* @param category The category to return the negotiated results for.
* @throws IllegalArgumentException if category is null.
*/
public NegotiableCapability getNegotiatedValue(String category)
throws RemoteImagingException {}
}
4.14 RemoteRenderableOp
-----------------------
package javax.media.jai.remote;
/**
* A subclass of By virtue of being a subclass of An An If the supplied name does not equal the current server name, a
* If the supplied name does not equal the current protocol name, a
* If both the supplied protocol name and the supplied server
* name values do not equal the current values, a
* This method does not validate sources and parameters supplied
* in the The The This new value for retry interval will be stored and will
* be passed as This new value for number of retries will be stored and will
* be passed as 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 In order to locate the "jairmi" server, a RMI registry must be
* running on this server, and the "jairmi" server must have registered
* itself with this RMI registry by binding itself under the
* The "jairmi" protocol expects the If the serverName supplied to any "jairmi" protocol implementing
* class's method is null, then the local host will be used instead.
*
* The default "jairmi" server provided with JAI is
* http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html
* http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html
*
* @since 1.1
*/
public class JAIRMIDescriptor extends RemoteDescriptorImpl {
/**
* The bind name for the remote "jairmi" server. This is also the
* name that the "jairmi" client looks for when trying to locate
* a "jairmi" server.
*/
public static final String IMAGE_SERVER_BIND_NAME =
"JAIRMIRemoteServer1.1";
/**
* Creates a If the supplied serverName argument is null, then the local
* host will be used instead.
*
* @param serverName The If the supplied serverName argument is null, then the local
* host will be used instead.
*
* @param serverName The The class of the returned object will vary as a function of
* the nature of the operation. For rendered and renderable two-
* dimensional images this should be an instance of a class which
* implements RemoteJAI contains a set of
* default rendering hints which will be used for all image creations.
* These hints are merged with any hints supplied to the
* create method; directly supplied hints take precedence
* over the common hints. When a new RemoteJAI instance is
* constructed, its hints are initialized to a copy of the default
* hints. Thus when an instance of RemoteJAI is
* constructed, hints for the default registry, tile cache, number of
* retries, and the retry interval are added to the set of common
* rendering hints. Similarly, invoking setOperationRegistry(),
* setTileCache(), setNumRetries() or
* setRetryInterval() on a RemoteJAI instance
* will cause the respective entity to be added to the common rendering
* hints. The hints associated with any instance may be manipulated
* using the getRenderingHints(),
* setRenderingHints(), TileCache to be used by a particular operation
* may be set during construction, or by calling
* the setTileCache() method. This will result in the
* provided tile cache being added to the set of common rendering
* hints.
*
* RemoteImagingException will be thrown. By default, the
* number of retries is set to five, and the retry interval
* is set to a thousand milliseconds. These values can be changed by using
* the setNumRetries() and the setRetryInterval
* methods and can also be specified via the RenderingHints
* object passed as an argument to RemoteJAI.create(). Time
* outs (When the amount of time taken to get a response or
* the result of an operation from the remote machine exceeds a limit) are
* not dealt with, and must be taken care of by the network imaging
* protocol implementation itself. The implementation must be responsible
* for monitoring time outs, but on encountering one can deal with it by
* throwing a RemoteImagingException, which will then be dealt
* with using retries and retry intervals.
*
* negotiate
* method uses the preferences specified via the
* setNegotiationPreferences method alongwith the server
* and client capabilities retrieved via the getServerCapabilities
* and getClientCapabilities respectively to negotiate on each
* of the preferences. This negotiation treats the client and server
* capabilities as being non-preferences, and the user set
* NegotiableCapabilitySet as being a preference. The
* negotiation is performed according to the rules described in the class
* documentation for NegotiableCapability.
*
* RemoteJAI.create() or
* RemoteJAI.createRenderable()) or afterwards. The currently
* set negotiation preferences are passed to the RemoteRenderedOp
* on its construction through the RenderingHints using the
* KEY_NEGOTIATION_PREFERENCES key. Since
* RemoteRenderableOp does not accept a
* RenderingHints object as a construction argument, the newly
* created RemoteRenderableOp is informed of these preferences
* using it's setRenderingHints() method. These preferences
* can be changed after the construction using the
* setNegotiationPreferences() method on both
* RemoteRenderedOp and RemoteRenderableOp.
*
* The same behavior applies to the number of retries and the retry interval,
* whether they be the default values contained in the default
* RenderingHints or whether they are set using the
* setNumRetries or setRetryInterval methods, the
* existing values are passed to RemoteRenderedOp's when they
* are created through the RenderingHints argument, and are set
* on the newly created RemoteRenderableOp using the
* setNumRetries or setRetryInterval methods on
* RemoteRenderableOp.
*
* @see JAI
* @see RemoteImagingException
*
* @since 1.1
*/
public class RemoteJAI {
/** The String representing the remote server machine. */
protected String serverName;
/** The name of the protocol used for client-server communication. */
protected String protocolName;
/** The amount of time to wait between retries (in Millseconds). */
public static final int DEFAULT_RETRY_INTERVAL = 1000;
/** The default number of retries. */
public static final int DEFAULT_NUM_RETRIES = 5;
/**
* Constructs a RemoteJAI instance with the given
* protocol name and server name. The semantics of the serverName
* are defined by the particular protocol used to create this
* class. Instructions on how to create a serverName that is
* compatible with this protocol can be retrieved from the
* getServerNameDocs() method on the
* RemoteDescriptor associated with the given
* protocolName. An IllegalArgumentException may
* be thrown by the protocol specific classes at a later point, if
* null is provided as the serverName argument and null is not
* considered a valid serverName by the specified protocol.
*
* @param protocolName The String that identifies the
* remote imaging protocol.
* @param serverName The String that identifies the server.
*
* @throws IllegalArgumentException if protocolName is null.
*/
public RemoteJAI(String protocolName, String serverName) {}
/**
* Constructs a RemoteJAI instance with the given
* protocol name, server name, OperationRegistry
* and TileCache. If the specified
* OperationRegistry is null, the registry associated
* with the default JAI instance will be used. If the
* specified TileCache is null, the TileCache
* associated with the default JAI instance will be used.
*
* IllegalArgumentException may
* be thrown by the protocol specific classes at a later point, if
* null is provided as the serverName argument and null is not
* considered a valid serverName by the specified protocol.
*
* @param serverName The String that identifies
* the server.
* @param protocolName The String that identifies
* the remote imaging protocol.
* @param operationRegistry The OperationRegistry associated
* with this class, if null, default will be used.
* @param tileCache The TileCache associated with
* this class, if null, default will be used.
* @throws IllegalArgumentException if protocolName is null.
*/
public RemoteJAI(String protocolName,
String serverName,
OperationRegistry registry,
TileCache tileCache) {}
/**
* Returns a String identifying the remote server machine.
*/
public String getServerName() {}
/**
* Returns the protocol name.
*/
public String getProtocolName() {}
/**
* Sets the amount of time between retries in milliseconds. The
* specified retryInterval parameter will be added
* to the common RenderingHints of this
* RemoteJAI instance, under the
* JAI.KEY_RETRY_INTERVAL key.
*
* @param retryInterval The time interval between retries (milliseconds).
* @throws IllegalArgumentException if retryInterval is negative.
*/
public void setRetryInterval(int retryInterval) {}
/**
* Returns the amount of time between retries in milliseconds.
*/
public int getRetryInterval() {}
/**
* Sets the number of retries. The specified numRetries
* parameter will be added to the common RenderingHints
* of this RemoteJAI instance, under the
* JAI.KEY_NUM_RETRIES key.
*
* @param numRetries The number of retries.
* @throws IllegalArgumentException if numRetries is negative.
*/
public void setNumRetries(int numRetries) {}
/**
* Returns the number of retries.
*/
public int getNumRetries() {}
/**
* Returns the OperationRegistry being used by this
* RemoteJAI instance.
*/
public OperationRegistry getOperationRegistry() {}
/**
* Sets theOperationRegistry to be used by this
* RemoteJAI instance. The operationRegistry
* parameter will be added to the RenderingHints of this
* RemoteJAI instance.
*
* @throws IllegalArgumentException if operationRegistry is null.
*/
public void setOperationRegistry(OperationRegistry operationRegistry) {}
/**
* Sets the TileCache to be used by this
* RemoteJAI. The tileCache parameter
* will be added to the RenderingHints of this
* RemoteJAI instance.
*
* @throws IllegalArgumentException if tileCache is null.
*/
public void setTileCache(TileCache tileCache) {}
/**
* Returns the TileCache being used by this
* RemoteJAI instance.
*/
public TileCache getTileCache() {}
/**
* Returns the RenderingHints associated with this
* RemoteJAI instance. These rendering hints will be
* merged with any hints supplied as an argument to the
* create() method.
*/
public RenderingHints getRenderingHints() {}
/**
* Sets the RenderingHints associated with this
* RemoteJAI instance. These rendering hints will be
* merged with any hints supplied as an argument to the
* create() method.
*
* @throws IllegalArgumentException if hints is null.
*/
public void setRenderingHints(RenderingHints hints) {}
/**
* Clears the RenderingHints associated with this
* RemoteJAI instance.
*/
public void clearRenderingHints() {d}
/**
* Returns the hint value associated with a given key
* in this RemoteJAI instance, or null
* if no value is associated with the given key.
*
* @throws IllegalArgumentException if key is null.
*/
public Object getRenderingHint(RenderingHints.Key key) {}
/**
* Sets the hint value associated with a given key
* in this RemoteJAI instance.
*
* @throws IllegalArgumentException if key is
* null.
* @throws IllegalArgumentException if value is
* null.
* @throws IllegalArgumentException if value is
* not of the correct type for the given hint.
*/
public void setRenderingHint(RenderingHints.Key key, Object value) {}
/**
* Removes the hint value associated with a given key
* in this RemoteJAI instance.
*/
public void removeRenderingHint(RenderingHints.Key key) {}
/**
* Creates a RemoteRenderedOp which represents the named
* operation to be performed remotely, using the source(s) and/or
* parameter(s) specified in the ParameterBlock, and
* applying the specified hints to the destination. This method
* should only be used when the final result returned is a single
* RemoteRenderedImage.
*
* OperationDescriptors returned from
* the getServerSupportedOperationList() method. The
* source(s) and/or parameter(s) in the ParameterBlock
* are validated against the named operation's descriptor, both in
* their numbers and types. Additional restrictions placed on the
* sources and parameters by an individual operation are also
* validated by calling its
* OperationDescriptor.validateArguments() method.
*
* null input
* value, if that particular parameter has a default value specified
* in its operation's descriptor. In this case, the default value
* will replace the null input.
*
* ParameterBlock, even if it only has a value of
* code>null.
*
* RemoteJAI are overlaid with the hints passed to this
* method. That is, the set of keys will be the union of the
* keys from the instance's hints and the hints parameter.
* If the same key exists in both places, the value from the
* hints parameter will be used.
*
* @param opName The name of the operation.
* @param args The source(s) and/or parameter(s) for the operation.
* @param hints The hints for the operation.
*
* @throws IllegalArgumentException if opName is
* null.
* @throws IllegalArgumentException if args is
* null.
* @throws IllegalArgumentException if no
* OperationDescriptor is available from the server
* with the specified operation name.
* @throws IllegalArgumentException if the
* OperationDescriptor for the specified
* operation name on the server does not
* support the "rendered" registry mode.
* @throws IllegalArgumentException if the specified operation does
* not produce a
* java.awt.image.RenderedImage.
* @throws IllegalArgumentException if the specified operation is
* unable to handle the sources and parameters specified in
* args.
*
* @return A RemoteRenderedOp that represents the named
* operation to be performed remotely, or null
* if the specified operation
* is in the "immediate" mode and the rendering of the
* PlanarImage failed.
*/
public RemoteRenderedOp create(String opName,
ParameterBlock args,
RenderingHints hints) {}
/**
* Creates a RemoteRenderableOp that represents the named
* operation to be performed remotely, using the source(s) and/or
* parameter(s) specified in the ParameterBlock.
* This method should only be used when the final result returned
* is a single RenderableImage.
*
* OperationDescriptors returned from
* the getServerSupportedOperationList() method.
* The source(s) and/or parameter(s) in the
* ParameterBlock are validated against the named
* operation's descriptor, both in their numbers and types.
* Additional restrictions placed on the sources and parameters
* by an individual operation are also validated by calling its
* OperationDescriptor.validateRenderableArguments()
* method.
*
* null input
* value, if that particular parameter has a default value specified
* in its operation's descriptor. In this case, the default value
* will replace the null input.
*
* ParameterBlock, even if it only has a value of
* code>null.
*
* @param opName The name of the operation.
* @param args The source(s) and/or parameter(s) for the operation.
*
* @throws IllegalArgumentException if opName is
* null.
* @throws IllegalArgumentException if args is
* null.
* @throws IllegalArgumentException if no
* OperationDescriptor is available from the server
* with the specified operation name.
* @throws IllegalArgumentException if the
* OperationDescriptor for the specified
* operation name on the server does not
* support "renderable" registry mode.
* @throws IllegalArgumentException if the specified operation does
* not produce a
* java.awt.image.renderable.RenderableImage.
* @throws IllegalArgumentException if the specified operation is
* unable to handle the sources and parameters specified in
* args.
*
* @return A RemoteRenderableOp that represents the named
* operation to be performed remotely.
*/
public RemoteRenderableOp createRenderable(String opName,
ParameterBlock args) {}
//
// NEGOTIATION RELATED METHODS
//
/**
* Sets the preferences to be used in the client-server
* communication. These preferences are utilized in the negotiation
* process. Note that preferences for more than one category can be
* specified using this method since NegotiableCapabilitySet
* allows different NegotiableCapability objects to be
* bundled up in one NegotiableCapabilitySet class. Even
* under the same category (as specified by the getCategory() method
* on NegotiableCapability), multiple
* NegotiableCapability objects can be added to the
* preferences. The preference added first for a particular category is
* given highest priority in the negotiation process.
*
* RemoteJAI.create method). To
* change negotiation preferences on an operation after it has been
* created, the setNegotiationPreferences() method on the
* created RemoteRenderedOp should be used. The
* preferences parameter will be added to the
* RenderingHints of this RemoteJAI instance.
*/
public void setNegotiationPreferences(NegotiableCapabilitySet preferences) {}
/**
* Returns the results of the negotiation between the client and server
* capabilities according to the user preferences specified at an
* earlier time. This will return null if the negotiation failed.
*
* NegotiableCapabilitySet that is the
* result of the negotiation process, if negotiation is successful,
* otherwise returns null.
*/
public NegotiableCapabilitySet getNegotiatedValues()
throws RemoteImagingException {}
/**
* Returns the results of the negotiation between the client and server
* capabilities according to the user preferences specified at an
* earlier time for the given category. This method returns a
* NegotiableCapability object, that represents the result
* of the negotiation for the given category. If the negotiation failed,
* null will be returned.
*
* NegotiableCapabilitySet that is the
* result of the negotiation process, if negotiation is successful,
* otherwise returns null.
*/
public NegotiableCapability getNegotiatedValues(String category)
throws RemoteImagingException {}
/**
* This method negotiates the capabilities to be used in the remote
* communication. Upon completion of the negotiation process,
* this method returns a NegotiableCapabilitySet which
* contains an aggregation of the NegotiableCapability
* objects that represent the results of negotiation. If the negotiation
* fails, null will be returned.
*
* IllegalArgumentException if the
* isPreference method for either of these returns
* true. The preferences NegotiableCapabilitySet should
* return true from its isPreference method, otherwise an
* IllegalArgumentException will be thrown. The negotiation
* is done in accordance with the rules described in the class comments
* for NegotiableCapability.
*
* NegotiableCapabilitySets.
*
* @param preferences The user preferences for the negotiation.
* @param serverCapabilities The capabilities of the server.
* @param clientCapabilities The capabilities of the client.
*
* @throws IllegalArgumentException if serverCapabilities is a
* preference, i.e., if it's isPreference() method
* returns true.
* @throws IllegalArgumentException if clientCapabilities is a
* preference, i.e., if it's isPreference() method
* returns true.
* @throws IllegalArgumentException if preferences is a
* non-preference, i.e., if it's isPreference() method
* returns false.
*/
public static NegotiableCapabilitySet negotiate(
NegotiableCapabilitySet preferences,
NegotiableCapabilitySet serverCapabilities,
NegotiableCapabilitySet clientCapabilities) {}
/**
* This method negotiates the capabilities to be used in the remote
* communication for the given category. Upon completion of the
* negotiation process, this method returns a
* NegotiableCapability object, that represents the result
* of the negotiation for the given category. If the negotiation fails,
* null will be returned.
*
* IllegalArgumentException if the
* isPreference method for either of these returns
* true. The preferences NegotiableCapabilitySet should
* return true from its isPreference method or an
* IllegalArgumentException will be thrown. The negotiation
* is done in accordance with the rules described in the class comments
* for NegotiableCapability.
*
* NegotiableCapabilitySets.
*
* @param preferences The user preferences for the negotiation.
* @param serverCapabilities The capabilities of the server.
* @param clientCapabilities The capabilities of the client.
* @param category The category to perform the negotiation on.
*
* @throws IllegalArgumentException if preferences is a
* non-preference, i.e., if it's isPreference() method
* returns false.
* @throws IllegalArgumentException if serverCapabilities is a
* preference, i.e., if it's isPreference() method
* returns true.
* @throws IllegalArgumentException if clientCapabilities is a
* preference, i.e., if it's isPreference() method
* returns true.
* @throws IllegalArgumentException if category is null.
*/
public static NegotiableCapability negotiate(
NegotiableCapabilitySet preferences,
NegotiableCapabilitySet serverCapabilities,
NegotiableCapabilitySet clientCapabilities,
String category) {}
/**
* Returns the set of capabilites supported by the server. If any
* network related errors are encountered by this method (identified
* as such by receiving a RemoteImagingException), they
* will be dealt with by the use of retries and retry intervals.
*/
public NegotiableCapabilitySet getServerCapabilities()
throws RemoteImagingException {}
/**
* Returns the set of capabilities supported by the client.
*/
public NegotiableCapabilitySet getClientCapabilities() {}
/**
* Returns the list of OperationDescriptors that describe
* the operations supported by the server. If any
* network related errors are encountered by this method (identified
* as such by receiving a RemoteImagingException), they
* will be dealt with by the use of retries and retry intervals.
*/
public OperationDescriptor[] getServerSupportedOperationList()
throws RemoteImagingException {}
}
4.2 RemoteImagingException
---------------------------
Any communication over the network is prone to Network errors. These
errors could be machines that happen to be unreachable, refusal of
connection etc. RemoteImagingException allows for notification of
Network errors encountered while doing imaging over the network. Thus
all methods in the Enhanced Network Imaging architecture that involve
any communication over the network throw RemoteImagingException to
indicate a possibility of running into Network errors. It may be noted
that PlanarImageServerProxy allows for a clean way of dealing with these
Network errors (as detected via throws of RemoteImagingException) using
the specified number of retries and retry intervals.
package javax.media.jai.remote;
/**
* RemoteImagingException is an Exception thrown
* to indicate that an error condition was
* encountered during remote image processing. All methods which might
* encounter error conditions during remote image processing should
* be tagged as throwing this exception, as this is something an
* application might want to catch.
*/
public class RemoteImagingException extends RuntimeException {
/**
* Constructs a RemoteImagingException with no detail message.
* A detail message is a String that describes this particular exception.
*/
public RemoteImagingException() {}
/**
* Constructs a RemoteImagingException with the specified detail
* message. A detail message is a String that describes this particular
* exception.
*
* @param s the String that contains a detailed message
*/
public RemoteImagingException(String s) {}
}
The reason that this exception extends RuntimeException instead of
extending Exception is the following:
PlanarImageServerProxy overrides the PlanarImage getMinX(), .... methods
to implement these remotely. Since there is network communication
involved in this implementation, network errors are possible and
therefore the implementation can throw RemoteImagingExceptions. If
RemoteImagingException was a subclass of Exception, it would have to be
declared as being thrown in the method signature. Since getMinX() on
PlanarImage doesn't throw any Exceptions, in order for
PlanarImageServerProxy to be a subclass of PlanarImage it can't throw
any Exceptions either. So the only option left is to allow
RemoteImagingException to be a RuntimeException so it doesn't have to be
reported as being thrown in the method signature.
4.3 RemoteRenderedRegistryMode
-------------------------------
package javax.media.jai.registry;
/**
* A class which provides information about the "remoteRendered" registry
* mode.
*/
public class RemoteRenderedRegistryMode extends RegistryMode {
public static final String MODE_NAME = "remoteRendered";
/**
* Creates a RemoteRenderedRegistryMode for describing
* the "remoteRendered" registry mode.
*/
public RemoteRenderedRegistryMode() {}
}
4.4 RemoteRenderableRegistryMode
-------------------------------
package javax.media.jai.registry;
/**
* A class which provides information about the "remoteRenderable" registry
* mode.
*/
public class RemoteRenderableRegistryMode extends RegistryMode {
public static final String MODE_NAME = "remoteRenderable";
/**
* Creates a RemoteRenderableRegistryMode for describing
* the "remoteRenderable" registry mode.
*/
public RemoteRenderableRegistryMode() {}
}
4.5 RemoteDescriptor
--------------------
package javax.media.jai.remote;
/**
* This interface provides a description of a specific remote imaging
* protocol. Information regarding the remote imaging protocol such as
* its name, the list of operations supported on a particular server,
* the capabilities of a server implementing this protocol, human readable
* documentation detailing how the String identifying the
* server is structured should all be provided through this interface.
* Each remote imaging protocol registered with the
* OperationRegistry must have a RemoteDescriptor.
*
* getName method of
* RegistryElementDescriptor is expected to return the name
* of the remote imaging protocol. This is the name under which this
* RemoteDescriptor will be registered in the
* OperationRegistry.
*
* RegistryModes associated with remote imaging.
* The first is "remoteRendered" which signifies that the remote imaging
* operations lie in the rendered mode, the other is "remoteRenderable"
* which signifies that the remote imaging operations lie in the renderable
* domain and deal with renderable operations.
*
* getServerCapabilities() method returns the
* capabilities of the specified server. This information may already
* be known by virtue of being specified in the imaging protocol, or may
* have to be determined from the server, in which case, the implementation
* must communicate with the server to get this information. To get the
* capabilities of the client, the getClientCapabilities()
* method, which exists on RemoteRIF can be used. The reason
* for the getClientCapabilities method being defined on the
* RemoteRIF instead of on the RemoteDescriptor
* is that the descriptor does not have any way to reference the client.
* Thus there is no way for the descriptor to report the client
* capabilities. On the other hand, the RemoteRIF is the
* factory that creates the client, and therefore can be expected to either
* know or determine the capabilities of the client.
*
* @see javax.media.jai.registry.RemoteRenderedRegistryMode
* @see javax.media.jai.registry.RemoteRenderableRegistryMode
*
* @since 1.1
*/
public interface RemoteDescriptor extends RegistryElementDescriptor {
/**
* Returns the list of OperationDescriptors that describe
* the operations supported by the server. It is the
* implementing class's responsibility to extract this information from
* either the server or from its own knowledge of the remote imaging
* protocol.
*
* The format of the serverName argument is protocol-dependent. Thus
* different protocol specific subclasses may treat the same
* serverName argument in different ways, i.e. one protocol may allow
* the serverName argument to be null (if this protocol defines a
* default server), while another may consider null an invalid
* serverName and throw an Exception.
*
* @param serverName The String identifying the server.
*/
OperationDescriptor[] getServerSupportedOperationList(String serverName)
throws RemoteImagingException;
/**
* Returns the set of capabilites supported by the server. It is the
* implementing class's responsibility to extract this information from
* either the server or from its own knowledge of the remote imaging
* protocol.
*
* The format of the serverName argument is protocol-dependent. Thus
* different protocol specific subclasses may treat the same
* serverName argument in different ways, i.e. one protocol may allow
* the serverName argument to be null (if this protocol defines a
* default server), while another may consider null an invalid
* serverName and throw an Exception.
*
* @param serverName The String identifying the server.
*/
NegotiableCapabilitySet getServerCapabilities(String serverName)
throws RemoteImagingException;
/**
* Returns a URL that points to documentation
* containing instructions on constructing a server name string for
* the protocol with which this class is associated.
*/
URL getServerNameDocs();
/**
* Calculates the region over which two distinct remote renderings
* of an operation may be expected to differ. The operation is
* represented by the OperationNode argument to this
* method. The String that identifies the operation
* can be retrieved via the OperationNode's
* getOperationName() method.
*
* java.awt.Shape.
*
* @param registryModeName The name of the mode.
* @param oldServerName The previous server name.
* @param oldParamBlock The previous sources and parameters.
* @param oldHints The previous hints.
* @param newServerName The current server name.
* @param newParamBlock The current sources and parameters.
* @param newHints The current hints.
* @param node The affected node in the processing chain.
*
* @return The region over which the data of two renderings of this
* operation may be expected to be invalid or null
* if there is no common region of validity. If an empty
* java.awt.Shape is returned, this indicates
* that all pixels within the bounds of the old rendering
* remain valid.
*
* @throws IllegalArgumentException if registryModeName
* is null or if the operation requires either
* sources or parameters and either oldParamBlock
* or newParamBlock is null.
* @throws IllegalArgumentException if there is no OperationDescriptor
* for the specified operation on any one or both of the
* servers identified by oldServerName and
* newServerName, or if the number of sources or
* the name, number and Class of the operation's
* parameters is not the same on both the servers.
* @throws IllegalArgumentException if oldParamBlock or
* newParamBlock do not contain sufficient sources
* or parameters for the operation in question.
*/
Object getInvalidRegion(String registryModeName,
String oldServerName,
ParameterBlock oldParamBlock,
RenderingHints oldHints,
String newServerName,
ParameterBlock newParamBlock,
RenderingHints newHints,
OperationNode node) throws RemoteImagingException;
}
4.6 RemoteDescriptorImpl
------------------------
package javax.media.jai.remote;
/**
* This abstract class provides a partial implementation of the
* RemoteDescriptor interface, and is suitable for
* subclassing.
*
* @see RemoteDescriptor
*
* @since 1.1
*/
public abstract class RemoteDescriptorImpl implements RemoteDescriptor {
/**
* The name of the protocol that this descriptor describes.
*/
protected String protocolName;
/**
* The URL pointing to the documentation regarding
* the format of the server name String.
*/
protected URL serverNameDocURL;
/**
* Creates a RemoteDescriptorImpl given the protocol name
* and the URL that points to documentation regarding the
* format of the server name String.
*
* serverNameDocURL argument is allowed to
* be null, this is strongly discouraged, since this URL
* is the only description available to the user to help with creating
* a serverName String correctly.
*
* @param protocolName The name of the protocol.
* @param serverNameDocURL The URL pointing to server name
* format documentation.
* @throws IllegalArgumentException if protocolName is null.
*/
public RemoteDescriptorImpl(String protocolName, URL serverNameDocURL) {}
/**
* Returns the name of the remote imaging protocol under which this
* RemoteDescriptor will be registered in the
* OperationRegistry.
*/
public String getName() {}
/**
* The registry modes supported by this descriptor. The default
* implementation in this class returns two modes - "remoteRendered"
* and "remoteRenderable". If the subclass does not support both
* these modes it should override this method to reflect that.
*
* @see javax.media.jai.RegistryMode
*/
public String[] getSupportedModes() {}
/**
* Returns true if the supplied modeName is supported by this
* descriptor. The default implementation in this class returns true
* only if the supplied modeName is one of either "remoteRendered"
* or "remoteRenderable".
*
* @param modeName The mode name to check support for.
*
* @return true, if the implementation of this descriptor supports
* the specified mode. false otherwise.
*
* @throws IllegalArgumentException if modeName is null.
*/
public boolean isModeSupported(String modeName) {}
/**
* Returns true, if the implementation of this descriptor supports
* properties, false otherwise. The default implementation in this class
* returns false, signifying that no properties are supported independent
* of the operations themselves.
*
* @see PropertyGenerator
*/
public boolean arePropertiesSupported() {}
/**
* Returns an array of PropertyGenerators implementing
* the property inheritance for this descriptor. Since neither the
* "remoteRendered" or "remoteRendered" modes support properties
* independent of the operations themselves, the default
* implementation throws an UnsupportedOperationException.
* Subclasses should override this method if they wish to produce
* inherited properties.
*
* @param modeName The mode name to get PropertyGenerators
* for.
* @throws IllegalArgumentException if modeName is null.
* @throws UnsupportedOperationException if
* arePropertiesSupported() returns false
*
* @return An array of PropertyGenerators, or
* null if this operation does not have any of
* its own PropertyGenerators.
*/
public PropertyGenerator[] getPropertyGenerators(String modeName) {}
/**
* Returns a URL that points to an HTML page containing
* instructions on constructing a server name string for the protocol
* with which this class is associated.
*/
public URL getServerNameDocs() {}
/**
* Calculates the region over which two distinct remote renderings
* of an operation may be expected to differ. The operation is
* represented by the OperationNode argument to this
* method. The String that identifies the operation
* can be retrieved via the OperationNode's
* getOperationName() method.
*
* java.awt.Shape.
*
* ParameterBlock
* arguments passed to this method contain the correct number and
* Class of sources and parameters are performed in this
* implementation.
*
* @param registryModeName The name of the mode.
* @param oldServerName The previous server name.
* @param oldParamBlock The previous sources and parameters.
* @param oldHints The previous hints.
* @param newServerName The current server name.
* @param newParamBlock The current sources and parameters.
* @param newHints The current hints.
* @param node The affected node in the processing chain.
*
* @return The region over which the data of two renderings of this
* operation may be expected to be invalid or null
* if there is no common region of validity. If an empty
* java.awt.Shape is returned, this indicates
* that all pixels within the bounds of the old rendering
* remain valid.
*
* @throws IllegalArgumentException if registryModeName
* is null or if the operation requires either
* sources or parameters and either oldParamBlock
* or newParamBlock is null.
* @throws IllegalArgumentException if there is no OperationDescriptor
* for the specified operationName on any one or both of the
* servers identified by oldServerName and
* newServerName, or if the number of sources or
* the name, number and Class of the operation's
* parameters is not the same on both the servers.
* @throws IllegalArgumentException if oldParamBlock or
* newParamBlock do not contain sufficient sources
* or parameters for the operation in question.
*/
public Object getInvalidRegion(String registryModeName,
String oldServerName,
ParameterBlock oldParamBlock,
RenderingHints oldHints,
String newServerName,
ParameterBlock newParamBlock,
RenderingHints newHints,
OperationNode node)
throws RemoteImagingException {}
/**
* The two modes supported by this descriptor are "remoteRendered" and
* "remoteRenderable". Since neither of these modes supports any
* parameters, this default implementation always returns null.
*
* @param modeName The mode name to get the
* ParameterListDescriptor for.
*
* @throws IllegalArgumentException if modeName is null.
*/
public ParameterListDescriptor getParameterListDescriptor(String
modeName) {}
}
4.7 RemoteRIF
-------------
package javax.media.jai.remote;
/**
* The RemoteRIF interface is intended to be implemented by
* classes that wish to act as factories to produce different renderings
* remotely, for example by executing a series of remote operations on
* a set of sources, depending on a specific set of parameters, properties,
* and rendering hints.
*
* RemoteRIF.
*
* RemoteRenderedImage representing the results
* of an imaging operation (or chain of operations) for a given
* ParameterBlock and RenderingHints. The
* RemoteRIF may also query any source images
* referenced by the ParameterBlock for their dimensions,
* SampleModels, properties, etc., as necessary.
*
* create() method can return null if the
* RemoteRIF (representing the server) is not capable of
* producing output for the given set of source images and parameters.
* For example, if a server (represented by a RemoteRIF) is
* only capable of performing a 3x3 convolution on single-banded image
* data, and the source image has multiple bands or the convolution
* Kernel is 5x5, null should be returned.
*
* RemoteRenderedImage may have a property
* identified by the String HINTS_OBSERVED to indicate which
* RenderingHints were used to create the image. In addition
* any RenderedImages that are obtained via the getSources()
* method on the created RemoteRenderedImage may have such
* a property.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
* @param paramBlock A ParameterBlock containing sources
* and parameters for the
* RemoteRenderedImage to be created.
* @param hints A RenderingHints object containing
* hints.
* @return A RemoteRenderedImage containing the desired
* output.
*/
RemoteRenderedImage create(String serverName,
String operationName,
ParameterBlock paramBlock,
RenderingHints hints)
throws RemoteImagingException;
/**
* Creates a RemoteRenderedImage representing the results
* of an imaging operation represented by the given
* OperationNode, whose given old rendering is updated
* according to the given PropertyChangeEventJAI. This
* factory method should be used to create a new rendering updated
* according to the changes reported by the given
* PropertyChangeEventJAI. The RemoteRIF
* can query the supplied OperationNode for
* references to the server name, operation name, parameter block,
* and rendering hints. If only a new rendering of the node is desired
* in order to handle the supplied PropertyChangeEventJAI,
* the rendering can be obtained by calling the default
* create() method, the arguments to which can be
* retrieved from the supplied OperationNode.
* The RemoteRIF may also query
* any source images referenced by the ParameterBlock
* for their dimensions, SampleModels, properties, etc.,
* as necessary. The supplied OperationNode should
* not be edited during the creation of the new rendering, otherwise
* the OperationNode might have an inconsistent state.
*
* create() method can return null if the
* RemoteRIF (representing the server) is not capable of
* producing output for the given set of source images and parameters.
* For example, if a server (represented by a RemoteRIF) is
* only capable of performing a 3x3 convolution on single-banded image
* data, and the source image has multiple bands or the convolution
* Kernel is 5x5, null should be returned.
*
* RemoteRenderedImage may have a property
* identified by the String HINTS_OBSERVED to indicate which
* RenderingHints were used to create the image. In addition
* any RenderedImages that are obtained via the getSources()
* method on the created RemoteRenderedImage may have such
* a property.
*
* @param oldRendering The old rendering of the imaging operation.
* @param node The OperationNode that represents the
* imaging operation.
* @param event An event that specifies the changes made to the
* imaging operation.
* @return A RemoteRenderedImage containing the desired
* output.
*/
RemoteRenderedImage create(PlanarImageServerProxy oldRendering,
OperationNode node,
PropertyChangeEventJAI event)
throws RemoteImagingException;
/**
* Returns the set of capabilities supported by the client object.
*/
NegotiableCapabilitySet getClientCapabilities();
}
4.8 RemoteCRIF
--------------
package javax.media.jai.remote;
/**
* The RemoteCRIF interface is equivalent to the
* ContextualRenderedImageFactory for operations that are
* intended to be performed remotely.
*
* RemoteCRIF provides an interface for the functionality
* that may differ between instances of RemoteRenderableOp.
* Thus different remote operations on RenderableImages may be
* performed by a single class such as RemoteRenderedOp through
* the use of multiple instances of RemoteCRIF.
*
* RemoteCRIF.
*
* RenderContext into a
* RenderContext for each of the operation's sources.
* This is useful for operations that can be expressed in whole or in
* part simply as alterations in the RenderContext, such as
* an affine mapping, or operations that wish to obtain lower quality
* renderings of their sources in order to save processing effort or
* transmission bandwith. Some operations, such as blur, can also
* use this mechanism to avoid obtaining sources of higher quality
* than necessary.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
* @param i The index of the source image.
* @param renderContext The RenderContext being applied to the
* operation.
* @param paramBlock A ParameterBlock containing the
* operation's sources and parameters.
* @param image the RenderableImage being rendered.
*/
RenderContext mapRenderContext(String serverName,
String operationName,
int i,
RenderContext renderContext,
ParameterBlock paramBlock,
RenderableImage image)
throws RemoteImagingException;
/**
* Creates a rendering, given a RenderContext and a
* ParameterBlock containing the operation's sources
* and parameters. The output is a RemoteRenderedImage
* that takes the RenderContext into account to
* determine its dimensions and placement on the image plane.
* This method houses the "intelligence" that allows a
* rendering-independent operation to adapt to a specific
* RenderContext.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
* @param renderContext The RenderContext specifying the
* rendering context.
* @param paramBlock A ParameterBlock containing the
* operation's sources and parameters.
*/
RemoteRenderedImage create(String serverName,
String operationName,
RenderContext renderContext,
ParameterBlock paramBlock)
throws RemoteImagingException;
/**
* Returns the bounding box for the output of the operation,
* performed on a given set of sources, in rendering-independent
* space. The bounds are returned as a Rectangle2D,
* that is, an axis-aligned rectangle with floating-point corner
* coordinates.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
* @param paramBlock A ParameterBlock containing the
* operation's sources and parameters.
* @return a Rectangle2D specifying the rendering-independent
* bounding box of the output.
*
*/
Rectangle2D getBounds2D(String serverName,
String operationName,
ParameterBlock paramBlock)
throws RemoteImagingException;
/**
* Gets the appropriate instance of the property specified by the name
* parameter. This method must determine which instance of a property to
* return when there are multiple sources that each specify the property.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
* @param paramBlock A ParameterBlock containing the
* operation's sources and parameters.
* @param name A String naming the desired property.
* @return an object reference to the value of the property requested.
*/
Object getProperty(String serverName,
String operationName,
ParameterBlock paramBlock,
String name) throws RemoteImagingException;
/**
* Returns a list of names recognized by getProperty.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
*/
String[] getPropertyNames(String serverName, String operationName)
throws RemoteImagingException;
/**
* Returns true if successive renderings (that is, calls to
* create(RenderContext, ParameterBlock))
* with the same arguments may produce different results. This method
* may be used to determine whether an existing rendering may be cached
* and reused. It is always safe to return true.
*
* @param serverName A String specifying the name of the
* server to perform the remote operation on.
* @param operationName The String specifying the name of the
* operation to be performed remotely.
*/
boolean isDynamic(String serverName, String operationName)
throws RemoteImagingException;
4.9 RemoteRIFRegistry
---------------------
package javax.media.jai.registry;
/**
* Utility class to provide type-safe interaction with the
* OperationRegistry for RemoteRIF objects.
*
* OperationRegistry specified as an argument to
* the methods in this class is null, then
* JAI.getOperationRegistry() will be used.
*/
public final class RemoteRIFRegistry {
/**
* Registers the given RemoteRIF with the given
* OperationRegistry under the given protocolName.
*
* @param registry The OperationRegistry to register
* the RemoteRIF with. If this is
* null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The protocolName to register the
* RemoteRIF under.
* @param rrif The RemoteRIF to register.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if rrif is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the
* given protocolName.
*/
public static void register(OperationRegistry registry,
String protocolName,
RemoteRIF rrif) {}
/**
* Unregisters the given RemoteRIF previously registered
* under the given protocolName in the given
* OperationRegistry.
*
* @param registry The OperationRegistry to unregister
* the RemoteRIF from. If this is
* null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The protocolName to unregister the
* RemoteRIF from under.
* @param rrif The RemoteRIF to unregister.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if rrif is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the
* given protocolName.
* @throws IllegalArgumentException if the rrif was not previously
* registered against protocolName.
*/
public static void unregister(OperationRegistry registry,
String protocolName,
RemoteRIF rrif) {}
/**
* Returns the RemoteRIF registered under the given
* protocol name in the specified OperationRegistry.
*
* @param registry The OperationRegistry to use.
* If this is null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The name of the remote imaging protocol.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the given
* protocolName.
*/
public static RemoteRIF get(OperationRegistry registry,
String protocolName) {}
/**
* Constructs a RemoteRenderedImage representing the
* results of remotely applying the given operation to the source(s),
* and parameters specified in the specified ParameterBlock,
* using the specified rendering hints. The registry
* is used to determine the RemoteRIF to be used to
* instantiate the operation.
*
* @param registry The OperationRegistry to use to
* create the rendering. If this is
* null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The protocol to be used for remote imaging.
* @param serverName The name of the server.
* @param operationName The name of the operation to be performed remotely.
* @param paramBlock The ParameterBlock specifying the
* sources and parameters required for the operation.
* @param renderHints A RenderingHints object containing
* rendering hints.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if serverName is null.
* @throws IllegalArgumentException if operationName is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the given
* protocolName.
*/
public static RemoteRenderedImage create(OperationRegistry registry,
String protocolName,
String serverName,
String operationName,
ParameterBlock paramBlock,
RenderingHints renderHints) {}
}
4.10 RemoteCRIFRegistry
----------------------
package javax.media.jai.registry;
/**
* Utility class to provide type-safe interaction with the
* OperationRegistry for RemoteCRIF objects.
*
* If the OperationRegistry specified as an argument to the
* methods in this class is null, then JAI.getOperationRegistry()
* will be used.
*/
public final class RemoteCRIFRegistry {
/**
* Registers the given RemoteCRIF with the given
* OperationRegistry under the given protocolName
*
* @param registry The OperationRegistry to register the
* RemoteCRIF with. If this is
* null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The protocolName to register the
* RemoteCRIF under.
* @param rcrif The RemoteCRIF to register.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if rcrif is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the
* given protocolName.
*/
public static void register(OperationRegistry registry,
String protocolName,
RemoteCRIF rcrif) {}
/**
* Unregisters the given RemoteCRIF previously registered
* under the given protocolName in the given
* OperationRegistry.
*
* @param registry The OperationRegistry to unregister the
* RemoteCRIF from. If this is
* null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The protocolName to unregister the
* RemoteCRIF from under.
* @param rcrif The RemoteCRIF to unregister.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if rcrif is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the
* given protocolName.
* @throws IllegalArgumentException if the rcrif was not previously
* registered against protocolName.
*/
public static void unregister(OperationRegistry registry,
String protocolName,
RemoteCRIF rcrif) {}
/**
* Returns the RemoteCRIF registered under the given
* protocol name in the specified OperationRegistry.
*
* @param registry The OperationRegistry to use.
* If this is null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The name of the remote imaging protocol.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the given
* protocolName.
*/
public static RemoteCRIF get(OperationRegistry registry,
String protocolName) {}
/**
* Creates a rendering remotely, given the serverName, protocolName,
* name of the operation to be performed, a RenderContext and
* a ParameterBlock containing the operation's sources
* and parameters. The registry is used to determine the
* RemoteCRIF to be used to instantiate the operation.
*
* @param registry The OperationRegistry to use to
* create the rendering. If this is
* null, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param protocolName The protocol to be used for remote imaging.
* @param serverName The name of the server.
* @param operationName The name of the operation to be performed remotely.
* @param renderContext A RenderContext specifying the
* context in which the rendering should be requested.
* @param paramBlock The ParameterBlock specifying the
* sources and parameters required for the operation.
*
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if serverName is null.
* @throws IllegalArgumentException if operationName is null.
* @throws IllegalArgumentException if there is no
* RemoteDescriptor registered against the given
* protocolName.
*/
public static RemoteRenderedImage create(OperationRegistry registry,
String protocolName,
String serverName,
String operationName,
RenderContext renderContext,
ParameterBlock paramBlock) {}
}
4.11 RemoteRenderedImage
-----------------------
package javax.media.jai.remote;
/**
* RemoteRenderedImage is an interface commonly used to
* represent objects which contain or can produce image data in the form of
* Rasters from locations that are remote. The image data may be
* stored/produced as a single tile or a regular array of tiles.
*
* RenderedImage
* interface and adds methods that deal with the remote location aspect of
* the image.
*
* @see RenderedImage
*
* @since 1.1
*/
public interface RemoteRenderedImage extends RenderedImage {
/**
* Returns the String that identifies the server.
*/
String getServerName();
/**
* Returns the String that identifies the remote imaging
* protocol.
*/
String getProtocolName();
/**
* Returns the amount of time between retries in milliseconds.
*/
int getRetryInterval();
/**
* Sets the amount of time between retries in milliseconds.
*
* @param retryInterval The amount of time (in milliseconds) to wait
* between retries.
* @throws IllegalArgumentException if retryInterval is negative.
*/
void setRetryInterval(int retryInterval);
/**
* Returns the number of retries.
*/
int getNumRetries();
/**
* Sets the number of retries.
*
* @param numRetries The number of times an operation should be retried
* in case of a network error.
* @throws IllegalArgumentException if numRetries is negative.
*/
void setNumRetries(int numRetries);
/**
* Returns the current negotiation preferences or null, if none were
* set previously.
*/
NegotiableCapabilitySet getNegotiationPreferences();
/**
* 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).
*
* 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.
*
* RemoteRenderedOps are a client side representation of
* the chain of operations taking place on the server.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* @see RenderedOp
* @see RemoteRenderedImage
*
* @since 1.1
*/
public class RemoteRenderedOp extends RenderedOp
implements RemoteRenderedImage {
/** The name of the protocol this class provides an implementation for. */
protected String protocolName;
/** The name of the server. */
protected String serverName;
/**
* 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.
*
* 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.
*
* RenderingHints may contain negotiation
* preferences specified under the KEY_NEGOTIATION_PREFERENCES
* key.
*
* @param protocolName The protocol name as a String.
* @param serverName The server name as a String.
* @param opName The operation name.
* @param pb The sources and parameters. If null,
* it is assumed that this node has no sources and
* parameters.
* @param hints The rendering hints. If null, it is
* assumed that no hints are associated with the
* rendering.
*
* @throws IllegalArgumentException if protocolName is
* null.
* @throws IllegalArgumentException if opName is
* null.
*/
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 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.
*
* 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.
*
* RenderingHints may contain negotiation
* preferences specified under the KEY_NEGOTIATION_PREFERENCES
* key.
*
* @param registry The OperationRegistry to be used for
* instantiation. if null, the default
* registry is used.
* @param protocolName The protocol name as a String.
* @param serverName The server name as a String.
* @param opName The operation name.
* @param pb The sources and parameters. If null,
* it is assumed that this node has no sources and
* parameters.
* @param hints The rendering hints. If null, it is
* assumed that no hints are associated with the
* rendering.
*
* @throws IllegalArgumentException if protocolName is
* null.
* @throws IllegalArgumentException if opName is
* null.
*/
public RemoteRenderedOp(OperationRegistry registry,
String protocolName,
String serverName,
String opName,
ParameterBlock pb,
RenderingHints hints) {}
/**
* Returns the String that identifies the server.
*/
public String getServerName() {}
/**
* Sets a String identifying the server.
*
* 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.
*
* @param serverName A String identifying the server.
* @throws IllegalArgumentException if serverName is null.
*/
public void setServerName(String serverName) {}
/**
* Returns the String that identifies the remote imaging
* protocol.
*/
public String getProtocolName() {}
/**
* 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.
*
* 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.
*
* @param protocolName A String identifying the server.
* @throws IllegalArgumentException if protocolName is null.
*/
public void setProtocolName(String protocolName) {}
/**
* Sets the protocol name and the server name of this
* RemoteRenderedOp to the specified arguments..
*
* 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.
*
* @param protocolName A String identifying the protocol.
* @param serverName A String identifying the server.
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if serverName is null.
*/
public void setProtocolAndServerNames(String protocolName,
String serverName) {}
/**
* Returns the name of the RegistryMode corresponding to
* this RemoteRenderedOp. This method overrides the
* implementation in RenderedOp to always returns the
* String "remoteRendered".
*/
public String getRegistryModeName() {}
/**
* Overrides the RenderedOp method to allow the operation
* to be performed remotely.
*/
protected synchronized PlanarImage createInstance(boolean isNodeRendered) {}
/**
* Implementation of PropertyChangeListener.
*
* RenderingChangeEvent the node will respond by
* re-rendering itself while retaining any tiles possible.
*/
public synchronized void propertyChange(PropertyChangeEvent evt) {}
/**
* Returns the amount of time between retries in milliseconds.
*
* RemoteRenderedOp has been rendered, then its
* getRetryInterval() method will be called to return
* the current retry interval. If no rendering has been created, then
* the internally stored value (stored when the new value was
* set using the setRetryInterval() method) will be returned.
*/
public int getRetryInterval() {}
/**
* 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.
*
* @param retryInterval The amount of time (in milliseconds) to wait
* between retries.
* @throws IllegalArgumentException if retryInterval is negative.
*/
public void setRetryInterval(int retryInterval) {}
/**
* Returns the number of retries.
*
* RemoteRenderedOp has been rendered, then its
* getNumRetries() method will be called to return
* the current number of retries. If no rendering has been created, then
* the internally stored value (stored when the new value was
* set using the setNumRetries() method) will be returned.
*/
public int getNumRetries() {}
/**
* 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.
*
* @param numRetries The number of times an operation should be retried
* in case of a network error.
* @throws IllegalArgumentException if numRetries is negative.
*/
public void setNumRetries(int numRetries) {}
/**
* 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).
*
* 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.
*
* @param preferences The preferences to be used in the negotiation
* process.
* @throws IllegalArgumentException if preferences is null.
*/
public void setNegotiationPreferences(NegotiableCapabilitySet preferences)
{}
/**
* Returns the current negotiation preferences or null, if none were
* set previously.
*/
public NegotiableCapabilitySet getNegotiationPreferences() {}
/**
* 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.
*
* 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.
*/
public NegotiableCapabilitySet getNegotiatedValues()
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.
*
* 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.
*
* @param category The category to return the negotiated results for.
*/
public NegotiableCapability getNegotiatedValue(String category)
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.
*
* @param negotiatedValues The result of the negotiation.
*/
public void setServerNegotiatedValues(NegotiableCapabilitySet
negotiatedValues)
throws RemoteImagingException {}
}
4.13 PlanarImageServerProxy
--------------------------
package javax.media.jai.remote;
/**
* 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.
*
* 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.
*
* 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().
*
* 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.
*
* @see RemoteImagingException
*
* @since 1.1
*/
public abstract class PlanarImageServerProxy extends PlanarImage implements RemoteRenderedImage {
/** Time in milliseconds between retries. */
protected int retryInterval;
/** The number of retries. */
protected int numRetries;
/** A reference to a centralized TileCache object. */
protected transient TileCache cache;
/**
* 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.
*/
protected Object tileCacheMetric;
/** A reference to the OperationRegistry object. */
protected transient OperationRegistry registry;
/** The String representing the remote server machine. */
protected String serverName;
/** The name of the protocol to be used for remote communication. */
protected String protocolName;
/** The name of the operation to be performed remotely. */
protected String operationName;
/** The sources and/or arguments to the operation. */
protected ParameterBlock paramBlock;
/** The RenderingHints for the operation. */
protected RenderingHints hints;
/** The preferences to be utilized in the negotiation. */
protected NegotiableCapabilitySet preferences;
/**
* The set of properties agreed upon after the negotiation process
* between the client and the server has been completed.
*/
protected NegotiableCapabilitySet negotiated;
/**
* 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.
*
* 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.
*
* @param serverName The String identifying the remote
* server machine.
* @param protocolName The name of the remote imaging protocol.
* @param operationName The name of the operation.
* @param paramBlock The source(s) and/or parameter(s) for the operation.
* @param hints The hints for the operation.
*
* @throws IllegalArgumentException if operationName is null.
*/
public PlanarImageServerProxy(String serverName,
String protocolName,
String operationName,
ParameterBlock paramBlock,
RenderingHints hints) {}
/**
* Returns the String that identifies the server.
*/
public String getServerName() {}
/**
* Returns the String that identifies the remote imaging
* protocol.
*/
public String getProtocolName() {}
/**
* Returns the operation name as a String.
*/
public String getOperationName() {}
/**
* Returns the ParameterBlock that specifies the
* sources and parameters for the operation to be performed by
* this PlanarImageServerProxy.
*/
public ParameterBlock getParameterBlock() {}
/**
* Returns the RenderingHints associated with the
* operation to be performed by this PlanarImageServerProxy.
*/
public RenderingHints getRenderingHints() {}
/**
* Returns the tile cache object of this image by reference.
* If this image does not have a tile cache, this method returns
* null.
*/
public TileCache getTileCache() {}
/**
* 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.
*
* null if no tile caching is desired.
*/
public void setTileCache(TileCache cache) {}
/**
* Returns the tileCacheMetric instance variable by reference.
*/
public Object getTileCacheMetric() {}
/**
* 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
* @throws Error if all the fields in the ImageLayout are not initialized.
*/
public abstract ImageLayout getImageLayout() 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
* @throws IllegalArgumentException if name is null.
*/
public abstract Object getRemoteProperty(String name)
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
*/
public abstract String[] getRemotePropertyNames()
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.
*
* @param sourceRect The Rectangle in source coordinates.
* @param sourceIndex The index of the source image.
*
* @return 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.
* @throws IllegalArgumentException If sourceRect is
* null.
*/
public abstract Rectangle mapSourceRect(Rectangle sourceRect,
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.
*
* @param destRect The Rectangle in destination coordinates.
* @param sourceIndex The index of the source image.
*
* @return A Rectangle indicating the required source region.
*
* @throws IllegalArgumentException If the source index is
* negative or greater than that of the last source.
* @throws IllegalArgumentException If destRect is
* null.
*/
public abstract Rectangle mapDestRect(Rectangle destRect,
int sourceIndex)
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.
*
* 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.
*
* @param tileX the X index of the requested tile in the tile array.
* @param tileY the Y index of the requested tile in the tile array.
* @throws RemoteImagingException if an error condition during remote
* image processing occurs
*/
public abstract Raster computeTile(int tileX, int tileY)
throws RemoteImagingException;
/**
* Returns the amount of time between retries in milliseconds.
*/
public int getRetryInterval() {}
/**
* Sets the amount of time between retries in milliseconds.
*
* @param retryInterval The amount of time (in milliseconds) to wait
* between retries.
* @throws IllegalArgumentException if retryInterval is negative.
*/
public void setRetryInterval(int retryInterval) {}
/**
* Returns the number of retries.
*/
public int getNumRetries() {}
/**
* Sets the number of retries.
*
* @param numRetries The number of times an operation should be retried
* in case of a network error.
* @throws IllegalArgumentException if numRetries is negative.
*/
public void setNumRetries(int numRetries) {}
/**
* Overrides the method in PlanarImage to return the X
* coordinate of the leftmost column of the remote image.
*/
public int getMinX() {}
/**
* 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.
*/
public int getMaxX() {}
/**
* Overrides the method in PlanarImage to return the Y
* coordinate of the uppermost row of the remote image.
*/
public int getMinY() {}
/**
* Overrides the method in PlanarImage to return the Y
* coordinate of the row immediately below the bottom row of the
* remote image.
*/
public int getMaxY() {}
/**
* Overrides the method in PlanarImage to return the width
* of the remote image.
*/
public int getWidth() {}
/**
* Overrides the method in PlanarImage to return the height
* of the remote image.
*/
public int getHeight() {}
/**
* Overrides the method in PlanarImage to return the width
* of a tile remotely.
*/
public int getTileWidth() {}
/**
* Overrides the method in PlanarImage to return the height
* of a tile remotely.
*/
public int getTileHeight() {}
/**
* Overrides the method in PlanarImage to return the X
* coordinate of the upper-left pixel of tile (0, 0) remotely.
*/
public int getTileGridXOffset() {}
/**
* Overrides the method in PlanarImage to return the Y
* coordinate of the upper-left pixel of tile (0, 0) remotely.
*/
public int getTileGridYOffset() {}
/**
* Overrides the method in PlanarImage to return the
* SampleModel of the remote image.
*/
public SampleModel getSampleModel() {}
/**
* Overrides the method in PlanarImage to return the
* ColorModel of the remote image.
*/
public ColorModel getColorModel() {}
/**
* 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.
*
* @param name the name of the property to get, as a String.
* @return a reference to the property Object, or the value
* java.awt.Image.UndefinedProperty.
*
* @throws RemoteImagingException if the limit of retries is exceeded.
*/
public Object getProperty(String name) {}
/**
* 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.
*
* @return an array of Strings containing valid
* property names.
*
* @throws RemoteImagingException if the limit of retries is exceeded.
*/
public String[] getPropertyNames() {}
/**
* 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.
*
* @param tileX the X index of the tile.
* @param tileY the Y index of the tile.
* @throws RemoteImagingException if limit of retries is exceeded.
*/
public Raster getTile(int tileX, int tileY) {}
/**
* Uncaches all the tiles when this image is garbage collected.
*/
protected void finalize() throws Throwable {}
//
// NEGOTIATION RELATED METHODS
//
/**
* Returns the current negotiation preferences or null, if none were
* set previously.
*/
public NegotiableCapabilitySet getNegotiationPreferences() {}
/**
* 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).
*
* 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.
*
* 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.
*
* @see javax.media.jai.RenderableOp
*
* @since 1.1
*/
public class RemoteRenderableOp extends RenderableOp {
/** The name of the protocol this class provides an implementation for. */
protected String protocolName;
/** The name of the server. */
protected String serverName;
/**
* 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.
*
* 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.
*
* @param protocolName The protocol name as a String.
* @param serverName The server name as a String.
* @param opName The operation name.
* @param 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.
* @throws IllegalArgumentException if opName is
* null.
*/
public RemoteRenderableOp(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.
*
* 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.
*
* @param registry The OperationRegistry to be used for
* instantiation. if null, the default
* registry is used.
* @param protocolName The protocol name as a String.
* @param serverName The server name as a String.
* @param opName The operation name.
* @param 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.
* @throws IllegalArgumentException if opName is
* null.
*/
public RemoteRenderableOp(OperationRegistry registry,
String protocolName,
String serverName,
String opName,
ParameterBlock pb) {}
/**
* Returns the name of the RegistryMode corresponding to
* this RenderableOp. This method overrides the
* implementation in RenderableOp to always returns the
* String "remoteRenderable".
*/
public String getRegistryModeName() {}
/**
* Returns the String that identifies the server.
*/
public String getServerName() {}
/**
* Sets a String identifying the server.
*
* 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.
*
* @param serverName A String identifying the server.
* @throws IllegalArgumentException if serverName is null.
*/
public void setServerName(String serverName) {}
/**
* Returns the String that identifies the remote imaging
* protocol.
*/
public String getProtocolName() {}
/**
* Sets a String identifying the remote imaging protocol.
*
* 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.
*
* @param protocolName A String identifying the protocol.
* @throws IllegalArgumentException if protocolName is null.
*/
public void setProtocolName(String protocolName) {}
/**
* Sets the protocol name and the server name of this
* RemoteRenderableOp to the specified arguments..
*
* 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.
*
* @param protocolName A String identifying the protocol.
* @param serverName A String identifying the server.
* @throws IllegalArgumentException if protocolName is null.
* @throws IllegalArgumentException if serverName is null.
*/
public void setProtocolAndServerNames(String protocolName,
String serverName) {}
/**
* Overrides the method in RenderableOp to return the
* rendering-independent width of the image, as queried from the remote
* server.
*
* @return the image width as a float.
*/
public float getWidth() {}
/**
* Overrides the method in RenderableOp to return the
* rendering-independent height of the image, as queried from the remote
* server.
*
* @return the image height as a float.
*/
public float getHeight() {}
/**
* Overrides the method in RenderableOp to return the
* minimum X coordinate of the rendering-independent image data, as
* queried from the remote server.
*/
public float getMinX() {}
/**
* Overrides the method in RenderableOp to return the
* maximum X coordinate of the rendering-independent image data, as
* queried from the remote server.
*/
public float getMinY() {}
/**
* 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.
*
* 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().
*
* 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.
*
* 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.
*
* @param renderContext the RenderContext to use to produce the rendering.
* @return a RemoteRenderedImage containing the rendered data.
*/
public RenderedImage createRendering(RenderContext renderContext) {}
/**
* Returns the amount of time between retries in milliseconds.
*/
public int getRetryInterval() {}
/**
* Sets the amount of time between retries in milliseconds.
*
* 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 interal value specified by the user, that will
* take preference over the one stored in this class.
*
* @param retryInterval The amount of time (in milliseconds) to wait
* between retries.
* @throws IllegalArgumentException if retryInterval is negative.
*/
public void setRetryInterval(int retryInterval) {}
/**
* Returns the number of retries.
*/
public int getNumRetries() {}
/**
* Sets the number of retries.
*
* 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.
*
* @param numRetries The number of times an operation should be retried
* in case of a network error.
* @throws IllegalArgumentException if numRetries is negative.
*/
public void setNumRetries(int numRetries) {}
/**
* Returns the current negotiation preferences or null, if none were
* set previously.
*/
public NegotiableCapabilitySet getNegotiationPreferences() {}
/**
* 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).
*
* 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.
*
* @param preferences The preferences to be used in the negotiation
* process.
*/
public void setNegotiationPreferences(NegotiableCapabilitySet preferences)
{}
/**
* 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.
*/
public NegotiableCapabilitySet getNegotiatedValues()
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.
*
* @param category The category to return negotiated results for.
*/
public NegotiableCapability getNegotiatedValues(String category)
throws RemoteImagingException {}
}
4.15 JAIRMIDescriptor
----------------------
This class describes the "jairmi" protocol, a default client and server
for which is provided as the implementation of the Enhanced Network
Imaging architecture in JAI 1.1
package javax.media.jai.remote;
/**
* This class describes the "jairmi" remote imaging protocol. This protocol
* assumes that both the client and the server are running JAI. The
* communication between the client and the server takes place using
* the Remote Method Invocation (RMI) mechanism.
*
* IMAGE_SERVER_BIND_NAME String. The RMI
* registry is a simple remote object name service that allows remote
* clients to get a reference to a remote object by name.
*
* String that
* represents the server to be a URL formatted
* String of the form:
*
*
* //host:port
*
*
* where host is the name, or IP address of the "jairmi"
* remote imaging server, and port is the port number
* where a rmiregistry is running on the same host. A protocol like
* "rmi:" does not need to be included in this URL formatted
* String. If the serverName
* String is null, the local host is used as a default.
* If the port is not included in the serverName String, it
* defaults to the well-known port for rmiregistry, 1099.
*
* com.sun.media.jai.rmi.JAIRMIRemoteServer. This server
* can be run in the following manner, after starting a rmiregistry on
* the host where the server will be run:
*
*
* java -Djava.rmi.server.codebase="file:$JAI/lib/jai_core.jar file:$JAI/lib/jai_codec.jar" -Djava.rmi.server.useCodebaseOnly=false -Djava.security.policy=file:$JAI/policy com.sun.media.jai.rmi.JAIRMIImageServer
*
*
* where $JAI refers to the directory where JAI is installed. This server
* binds itself with the running rmiregistry under the
* IMAGE_SERVER_BIND_NAME String bind name, and
* can be used to serve "jairmi" requests. The policy file specified
* above needs to be created by the user. Information on policy
* files and permissions can be found at
* JAIRMIDescriptor.
*/
public JAIRMIDescriptor() throws java.net.MalformedURLException {}
/**
* Returns the list of OperationDescriptors that describe
* the operations supported by the server. It is the
* implementing class's responsibility to extract this information from
* either the server or from its own knowledge of the remote imaging
* protocol. The "jairmi" protocol gets this information from the server.
*
* String identifying the server.
*/
public OperationDescriptor[] getServerSupportedOperationList(String
serverName)
throws RemoteImagingException {}
/**
* Returns the set of capabilites supported by the server. It is the
* implementing class's responsibility to extract this information from
* either the server or from its own knowledge of the remote imaging
* protocol. The "jairmi" protocol gets this information from the server.
*
* String identifying the server.
*/
public NegotiableCapabilitySet getServerCapabilities(String serverName)
throws RemoteImagingException {}
/**
* Calculates the region over which two distinct remote renderings
* of an operation may be expected to differ. The operation is
* represented by the OperationNode argument to this
* method. The String that identifies the operation
* can be retrieved via the OperationNode's
* getOperationName() method.
*
* java.awt.Shape.
*
* @param registryModeName The name of the mode.
* @param oldServerName The previous server name.
* @param oldParamBlock The previous sources and parameters.
* @param oldHints The previous hints.
* @param newServerName The current server name.
* @param newParamBlock The current sources and parameters.
* @param newHints The current hints.
* @param node The affected node in the processing chain.
*
* @return The region over which the data of two renderings of this
* operation may be expected to be invalid or null
* if there is no common region of validity. If an empty
* java.awt.Shape is returned, this indicates
* that all pixels within the bounds of the old rendering
* remain valid.
*
* @throws IllegalArgumentException if registryModeName
* is null or if the operation requires either
* sources or parameters and either oldParamBlock
* or newParamBlock is null.
* @throws IllegalArgumentException if there is no OperationDescriptor
* for the specified operationName on any one or both of the
* servers identified by oldServerName and
* newServerName, or if the number of sources or
* the name, number and Class of the operation's
* parameters is not the same on both the servers.
* @throws IllegalArgumentException if oldParamBlock or
* newParamBlock do not contain sufficient sources
* or parameters for the operation in question.
*/
public Object getInvalidRegion(String registryModeName,
String oldServerName,
ParameterBlock oldParamBlock,
RenderingHints oldHints,
String newServerName,
ParameterBlock newParamBlock,
RenderingHints newHints,
OperationNode node)
throws RemoteImagingException {}
}