javax.media.jai.remote
Interface RemoteDescriptor

All Superinterfaces:

RegistryElementDescriptor

All Known Implementing Classes:

RemoteDescriptorImpl

public interface RemoteDescriptor

extends RegistryElementDescriptor

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.

Any implementation of the 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.

There are two 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.

The 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.

Since:

JAI 1.1

See Also:

RemoteRenderedRegistryMode, RemoteRenderableRegistryMode

Method Summary

Object	getInvalidRegion(String registryModeName, String oldServerName, ParameterBlock oldParamBlock, RenderingHints oldHints, String newServerName, ParameterBlock newParamBlock, RenderingHints newHints, OperationNode node) Calculates the region over which two distinct remote renderings of an operation may be expected to differ.
NegotiableCapabilitySet	getServerCapabilities(String serverName) Returns the set of capabilites supported by the server.
URL	getServerNameDocs() Returns a URL that points to documentation containing instructions on constructing a server name string for the protocol with which this class is associated.
OperationDescriptor[]	getServerSupportedOperationList(String serverName) Returns the list of OperationDescriptors that describe the operations supported by the server.

Methods inherited from interface javax.media.jai.RegistryElementDescriptor

arePropertiesSupported, getName, getParameterListDescriptor, getPropertyGenerators, getSupportedModes, isModeSupported

Method Detail

getServerSupportedOperationList

public OperationDescriptor[] getServerSupportedOperationList(String serverName)
                                                      throws RemoteImagingException

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.

Parameters:

serverName - The String identifying the server.

getServerCapabilities

public NegotiableCapabilitySet getServerCapabilities(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.

Parameters:

serverName - The String identifying the server.

getServerNameDocs

public URL getServerNameDocs()

Returns a URL that points to documentation containing instructions on constructing a server name string for the protocol with which this class is associated.

getInvalidRegion

public Object getInvalidRegion(String registryModeName,
                               String oldServerName,
                               ParameterBlock oldParamBlock,
                               RenderingHints oldHints,
                               String newServerName,
                               ParameterBlock newParamBlock,
                               RenderingHints newHints,
                               OperationNode node)
                        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.

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 java.awt.Shape.

Parameters:

registryModeName - The name of the mode.

oldServerName - The previous server name.

oldParamBlock - The previous sources and parameters.

oldHints - The previous hints.

newServerName - The current server name.

newParamBlock - The current sources and parameters.

newHints - The current hints.

node - The affected node in the processing chain.

Returns:

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.

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.

IllegalArgumentException - if oldParamBlock or newParamBlock do not contain sufficient sources or parameters for the operation in question.