001: /*
002: * $RCSfile: RemoteDescriptor.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:52 $
010: * $State: Exp $
011: */package javax.media.jai.remote;
012:
013: import java.awt.RenderingHints;
014: import java.awt.image.renderable.ParameterBlock;
015: import java.net.URL;
016: import javax.media.jai.RegistryElementDescriptor;
017: import javax.media.jai.OperationDescriptor;
018: import javax.media.jai.OperationNode;
019:
020: /**
021: * This interface provides a description of a specific remote imaging
022: * protocol. Information regarding the remote imaging protocol such as
023: * its name, the list of operations supported on a particular server,
024: * the capabilities of a server implementing this protocol, human readable
025: * documentation detailing how the <code>String</code> identifying the
026: * server is structured should all be provided through this interface.
027: * Each remote imaging protocol registered with the
028: * <code>OperationRegistry</code> must have a <code>RemoteDescriptor</code>.
029: *
030: * <p> Any implementation of the <code>getName</code> method of
031: * <code>RegistryElementDescriptor</code> is expected to return the name
032: * of the remote imaging protocol. This is the name under which this
033: * <code>RemoteDescriptor</code> will be registered in the
034: * <code>OperationRegistry</code>.
035: *
036: * <p>There are two <code>RegistryMode</code>s associated with remote imaging.
037: * The first is "remoteRendered" which signifies that the remote imaging
038: * operations lie in the rendered mode, the other is "remoteRenderable"
039: * which signifies that the remote imaging operations lie in the renderable
040: * domain and deal with renderable operations.
041: *
042: * <p> The <code>getServerCapabilities()</code> method returns the
043: * capabilities of the specified server. This information may already
044: * be known by virtue of being specified in the imaging protocol, or may
045: * have to be determined from the server, in which case, the implementation
046: * must communicate with the server to get this information. To get the
047: * capabilities of the client, the <code>getClientCapabilities()</code>
048: * method, which exists on <code>RemoteRIF</code> can be used. The reason
049: * for the <code>getClientCapabilities</code> method being defined on the
050: * <code>RemoteRIF</code> instead of on the <code>RemoteDescriptor</code>
051: * is that the descriptor does not have any way to reference the client.
052: * Thus there is no way for the descriptor to report the client
053: * capabilities. On the other hand, the <code>RemoteRIF</code> is the
054: * factory that creates the client, and therefore can be expected to either
055: * know or determine the capabilities of the client.
056: *
057: * @see javax.media.jai.registry.RemoteRenderedRegistryMode
058: * @see javax.media.jai.registry.RemoteRenderableRegistryMode
059: *
060: * @since JAI 1.1
061: */
062: public interface RemoteDescriptor extends RegistryElementDescriptor {
063:
064: /**
065: * Returns the list of <code>OperationDescriptor</code>s that describe
066: * the operations supported by the server. It is the
067: * implementing class's responsibility to extract this information from
068: * either the server or from its own knowledge of the remote imaging
069: * protocol.
070: *
071: * The format of the serverName argument is protocol-dependent. Thus
072: * different protocol specific subclasses may treat the same
073: * serverName argument in different ways, i.e. one protocol may allow
074: * the serverName argument to be null (if this protocol defines a
075: * default server), while another may consider null an invalid
076: * serverName and throw an <code>Exception</code>.
077: *
078: * @param serverName The <code>String</code> identifying the server.
079: */
080: OperationDescriptor[] getServerSupportedOperationList(
081: String serverName) throws RemoteImagingException;
082:
083: /**
084: * Returns the set of capabilites supported by the server. It is the
085: * implementing class's responsibility to extract this information from
086: * either the server or from its own knowledge of the remote imaging
087: * protocol.
088: *
089: * The format of the serverName argument is protocol-dependent. Thus
090: * different protocol specific subclasses may treat the same
091: * serverName argument in different ways, i.e. one protocol may allow
092: * the serverName argument to be null (if this protocol defines a
093: * default server), while another may consider null an invalid
094: * serverName and throw an <code>Exception</code>.
095: *
096: * @param serverName The <code>String</code> identifying the server.
097: */
098: NegotiableCapabilitySet getServerCapabilities(String serverName)
099: throws RemoteImagingException;
100:
101: /**
102: * Returns a <code>URL</code> that points to documentation
103: * containing instructions on constructing a server name string for
104: * the protocol with which this class is associated.
105: */
106: URL getServerNameDocs();
107:
108: /**
109: * Calculates the region over which two distinct remote renderings
110: * of an operation may be expected to differ. The operation is
111: * represented by the <code>OperationNode</code> argument to this
112: * method. The <code>String</code> that identifies the operation
113: * can be retrieved via the <code>OperationNode</code>'s
114: * <code>getOperationName()</code> method.
115: *
116: * <p> The class of the returned object will vary as a function of
117: * the nature of the operation. For rendered and renderable two-
118: * dimensional images this should be an instance of a class which
119: * implements <code>java.awt.Shape</code>.
120: *
121: * @param registryModeName The name of the mode.
122: * @param oldServerName The previous server name.
123: * @param oldParamBlock The previous sources and parameters.
124: * @param oldHints The previous hints.
125: * @param newServerName The current server name.
126: * @param newParamBlock The current sources and parameters.
127: * @param newHints The current hints.
128: * @param node The affected node in the processing chain.
129: *
130: * @return The region over which the data of two renderings of this
131: * operation may be expected to be invalid or <code>null</code>
132: * if there is no common region of validity. If an empty
133: * <code>java.awt.Shape</code> is returned, this indicates
134: * that all pixels within the bounds of the old rendering
135: * remain valid.
136: *
137: * @throws IllegalArgumentException if <code>registryModeName</code>
138: * is <code>null</code> or if the operation requires either
139: * sources or parameters and either <code>oldParamBlock</code>
140: * or <code>newParamBlock</code> is <code>null</code>.
141: * @throws IllegalArgumentException if there is no OperationDescriptor
142: * for the specified operation on any one or both of the
143: * servers identified by <code>oldServerName</code> and
144: * <code>newServerName</code>, or if the number of sources or
145: * the name, number and <code>Class</code> of the operation's
146: * parameters is not the same on both the servers.
147: * @throws IllegalArgumentException if <code>oldParamBlock</code> or
148: * <code>newParamBlock</code> do not contain sufficient sources
149: * or parameters for the operation in question.
150: */
151: Object getInvalidRegion(String registryModeName,
152: String oldServerName, ParameterBlock oldParamBlock,
153: RenderingHints oldHints, String newServerName,
154: ParameterBlock newParamBlock, RenderingHints newHints,
155: OperationNode node) throws RemoteImagingException;
156: }
|