001: /*
002: * $RCSfile: RMIImage.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:56:52 $
010: * $State: Exp $
011: */
012: package com.sun.media.jai.rmi;
013:
014: import java.awt.Rectangle;
015: import java.awt.image.ColorModel;
016: import java.awt.image.Raster;
017: import java.awt.image.RenderedImage;
018: import java.awt.image.SampleModel;
019: import java.awt.image.WritableRaster;
020: import java.awt.image.renderable.RenderContext;
021: import java.rmi.Remote;
022: import java.rmi.RemoteException;
023: import java.util.Vector;
024: import javax.media.jai.RenderableOp;
025: import javax.media.jai.RenderedOp;
026:
027: /**
028: * An interface for server-side imaging. This interface attempts to
029: * mimic the RenderedImage interface as much as possible. However, there
030: * are several unavoidable differences:
031: *
032: * <ul>
033: * <li> Additional setSource() methods are provided to inform the server
034: * as to the source of image data for this image. Sources may be set
035: * either from a RenderedImage that is copied over to the server, or
036: * from a graph of RenderedOp objects indicating an abstract
037: * imaging chain to be instantiated using the server's
038: * OperationRegistry.
039: *
040: * <li> All methods throw RemoteException. This is a requirement of
041: * any Remote interface.
042: *
043: * <li> The getTile() method does not return a reference to a `live'
044: * tile; instead it returns a client-side copy of the server image's
045: * tile. The difference is moot since the server image is immutable.
046: * </ul>
047: *
048: * To instantiate a RMIImage, do the following:
049: *
050: * <pre>
051: * RMIImage im;
052: * im = java.rmi.Naming.lookup("//host:1099/javax.media.jai.RemoteImageServer");
053: * </pre>
054: *
055: * <p> The hostname and port will of course depend on the local setup.
056: * The host must be running an <code>rmiregistry</code> process and have a
057: * RemoteImageServer listening at the desired port.
058: *
059: * <p> This call will result in the creation of a server-side
060: * RMIImageImpl object and a client-side stub object.
061: * The client stub serializes its method arguments and transfers
062: * them to the server over a socket; the server serializes it return
063: * values and returns them in the same manner.
064: *
065: * <p> This process implies that all arguments and return values must
066: * be serializable. In the case of a RenderedImage source,
067: * serializability is not guaranteed and must be considered on a
068: * class-by-class basis. For RenderedOps, which are basically
069: * simple nodes connected by ParameterBlocks, serializability will be
070: * determined by the serializabiility of the ultimate
071: * (non-RenderedOp) sources of the DAG and the serializability
072: * of any ad-hoc Object parameters held in the ParameterBlocks.
073: *
074: * <p> The return values of the getData(), copyData(), and getTile()
075: * methods are various kinds of Rasters; at present, Java2D does not
076: * define serialization on Rasters. We will either need to add this
077: * feature to Java2D or else coerce the server-side Rasters into a
078: * serializable subclass form. In any case, we will want to
079: * implement lossless (and possibly lossy) compression as part of
080: * the serialization process wherever possible.
081: *
082: * @see java.rmi.Remote
083: * @see java.rmi.RemoteException
084: * @see java.awt.image.RenderedImage
085: * @see RemoteImage
086: *
087: * @since EA3
088: *
089: */
090: public interface RMIImage extends Remote {
091: /**
092: * The name to which the remote image server should be bound.
093: */
094: public static final String RMI_IMAGE_SERVER_NAME = "RemoteImageServer";
095:
096: /**
097: * Returns the identifier of the remote image. This method should be
098: * called to return an identifier before any other methods are invoked.
099: * The same ID must be used in all subsequent references to the remote
100: * image.
101: */
102: Long getRemoteID() throws RemoteException;
103:
104: /**
105: * Sets the source of the image on the server side. This source
106: * should ideally be a lightweight reference to an image available
107: * locally on the server or over a further network link (for
108: * example, an IIPOpImage that contains a URL but not actual image
109: * data).
110: *
111: * <p> Although it is legal to use any RenderedImage, one should be
112: * aware that a deep copy might be made and transmitted to the server.
113: *
114: * @param id An ID for the source which must be unique across all clients.
115: * @param source a RenderedImage source.
116: */
117: void setSource(Long id, RenderedImage source)
118: throws RemoteException;
119:
120: /**
121: * Sets the source to a RenderedOp (i.e., an imaging DAG).
122: * This DAG will be copied over to the server where it will be
123: * transformed into an OpImage chain using the server's local
124: * OperationRegistry and available RenderedImageFactory objects.
125: *
126: * @param id An ID for the source which must be unique across all clients.
127: * @param source a RenderedOp source.
128: */
129: void setSource(Long id, RenderedOp source) throws RemoteException;
130:
131: /**
132: * Sets the source to a RenderableOp defined by a renderable imaging
133: * DAG and a rendering context. The entire RenderableImage
134: * DAG will be copied over to the server.
135: */
136: void setSource(Long id, RenderableOp source,
137: RenderContextProxy renderContextProxy)
138: throws RemoteException;
139:
140: /**
141: * Disposes of any resouces allocated to the client object with
142: * the specified ID.
143: */
144: void dispose(Long id) throws RemoteException;
145:
146: /**
147: * Returns a vector of RenderedImages that are the sources of
148: * image data for this RMIImage. Note that this method
149: * will often return an empty vector.
150: */
151: Vector getSources(Long id) throws RemoteException;
152:
153: /**
154: * Gets a property from the property set of this image.
155: * If the property name is not recognized, java.awt.Image.UndefinedProperty
156: * will be returned.
157: *
158: * @param id An ID for the source which must be unique across all clients.
159: * @param name the name of the property to get, as a String.
160: * @return a reference to the property Object, or the value
161: * java.awt.Image.UndefinedProperty.
162: */
163: Object getProperty(Long id, String name) throws RemoteException;
164:
165: /**
166: * Returns a list of names recognized by getProperty(String).
167: *
168: * @return an array of Strings representing proeprty names.
169: */
170: String[] getPropertyNames(Long id) throws RemoteException;
171:
172: /** Returns the ColorModel associated with this image. */
173: ColorModelProxy getColorModel(Long id) throws RemoteException;
174:
175: /** Returns the SampleModel associated with this image. */
176: SampleModelProxy getSampleModel(Long id) throws RemoteException;
177:
178: /** Returns the width of the RMIImage. */
179: int getWidth(Long id) throws RemoteException;
180:
181: /** Returns the height of the RMIImage. */
182: int getHeight(Long id) throws RemoteException;
183:
184: /**
185: * Returns the minimum X coordinate of the RMIImage.
186: */
187: int getMinX(Long id) throws RemoteException;
188:
189: /**
190: * Returns the minimum Y coordinate of the RMIImage.
191: */
192: int getMinY(Long id) throws RemoteException;
193:
194: /** Returns the number of tiles across the image. */
195: int getNumXTiles(Long id) throws RemoteException;
196:
197: /** Returns the number of tiles down the image. */
198: int getNumYTiles(Long id) throws RemoteException;
199:
200: /**
201: * Returns the index of the minimum tile in the X direction of the image.
202: */
203: int getMinTileX(Long id) throws RemoteException;
204:
205: /**
206: * Returns the index of the minimum tile in the Y direction of the image.
207: */
208: int getMinTileY(Long id) throws RemoteException;
209:
210: /** Returns the width of a tile in pixels. */
211: int getTileWidth(Long id) throws RemoteException;
212:
213: /** Returns the height of a tile in pixels. */
214: int getTileHeight(Long id) throws RemoteException;
215:
216: /** Returns the X offset of the tile grid relative to the origin. */
217: int getTileGridXOffset(Long id) throws RemoteException;
218:
219: /** Returns the Y offset of the tile grid relative to the origin. */
220: int getTileGridYOffset(Long id) throws RemoteException;
221:
222: /**
223: * Returns tile (x, y). Note that x and y are indices into the
224: * tile array, not pixel locations. Unlike in the true RenderedImage
225: * interface, the Raster that is returned should be considered a copy.
226: *
227: * @param id An ID for the source which must be unique across all clients.
228: * @param x the x index of the requested tile in the tile array
229: * @param y the y index of the requested tile in the tile array
230: * @return a copy of the tile as a Raster.
231: */
232: RasterProxy getTile(Long id, int x, int y) throws RemoteException;
233:
234: /**
235: * Returns the entire image as a single Raster.
236: *
237: * @return a RasterProxy containing a copy of this image's data.
238: */
239: RasterProxy getData(Long id) throws RemoteException;
240:
241: /**
242: * Returns an arbitrary rectangular region of the RenderedImage
243: * in a Raster. The rectangle of interest will be clipped against
244: * the image bounds.
245: *
246: * @param id An ID for the source which must be unique across all clients.
247: * @param bounds the region of the RenderedImage to be returned.
248: * @return a RasterProxy containing a copy of the desired data.
249: */
250: RasterProxy getData(Long id, Rectangle bounds)
251: throws RemoteException;
252:
253: /**
254: * Returns the same result as getData(Rectangle) would for the
255: * same rectangular region.
256: */
257: RasterProxy copyData(Long id, Rectangle bounds)
258: throws RemoteException;
259: }
|