javax.media.jai.remote
Class JAIRMIDescriptor

java.lang.Object
  |
  +--javax.media.jai.remote.RemoteDescriptorImpl
        |
        +--javax.media.jai.remote.JAIRMIDescriptor

All Implemented Interfaces:

RegistryElementDescriptor, RemoteDescriptor

public class JAIRMIDescriptor

extends RemoteDescriptorImpl

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.

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

The "jairmi" protocol expects the 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.

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

http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html

http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html

The JAI instance used by the "jairmi" remote imaging server can be configured by providing an implementation of the com.sun.media.jai.remote.JAIServerConfigurationSpi interface on the CLASSPATH when starting the server. For more details, please refer to JAIServerConfigurationSpi

The "jairmi" remote imaging server supports the following configurable parameters whose values can be specified on the command line when starting the server : -host The server name or server IP address -port The port that rmiregistry is running on -rmiRegistryPort Same as -port option -serverPort The port that the server should listen on, for connections from clients -cacheMemCapacity The memory capacity in bytes. -cacheMemThreshold The memory threshold, which is the fractional amount of cache memory to retain during tile removal -disableDefaultCache Disable use of default tile cache. -schedulerParallelism The degree of parallelism of the default TileScheduler -schedulerPrefetchParallelism The degree of parallelism of the default TileScheduler for tile prefetching -schedulerPriority The priority of tile scheduling for the default TileScheduler -schedulerPrefetchPriority The priority of tile prefetch scheduling for the default TileScheduler -defaultTileSize x The default tile dimensions in the form x -defaultRenderingSize x The default size to render a RenderableImage to, in the form x -serializeDeepCopy Whether a deep copy of the image data should be used when serializing images -tileCodecFormat The default format to be used for tile serialization via TileCodecs -retryInterval The retry interval value to be used for dealing with network errors during remote imaging -numRetries The number of retries to be used for dealing with network errors during remote imaging

It should be noted that if a parameter was set via JAIServerConfigurationSpi, and the command line option for the same parameter specifies a different value, then the command line specified parameter value will be honored. That is to say that the JAIServerConfigurationSpi specified configuration happens first, followed by command line parameter configuration, and the last configuration to be applied overwrites all previous settings.

Since:

JAI 1.1

Field Summary

static String

IMAGE_SERVER_BIND_NAME The bind name for the remote "jairmi" server.

Fields inherited from class javax.media.jai.remote.RemoteDescriptorImpl

protocolName, serverNameDocURL

Constructor Summary

JAIRMIDescriptor()
Creates a JAIRMIDescriptor.

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.
OperationDescriptor[]	getServerSupportedOperationList(String serverName) Returns the list of OperationDescriptors that describe the operations supported by the server.

Methods inherited from class javax.media.jai.remote.RemoteDescriptorImpl

arePropertiesSupported, getName, getParameterListDescriptor, getPropertyGenerators, getServerNameDocs, getSupportedModes, isModeSupported

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IMAGE_SERVER_BIND_NAME

public static final String IMAGE_SERVER_BIND_NAME

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.

Constructor Detail

JAIRMIDescriptor

public JAIRMIDescriptor()
                 throws MalformedURLException

Creates a JAIRMIDescriptor.

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 "jairmi" protocol gets this information from the server.

If the supplied serverName argument is null, then the local host will be used instead.

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 "jairmi" protocol gets this information from the server.

If the supplied serverName argument is null, then the local host will be used instead.

Parameters:

serverName - The String identifying the server.

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.

Overrides:

getInvalidRegion in class RemoteDescriptorImpl

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

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