1 /* 2 * $RCSfile: RMIImage.java,v $ 3 * 4 * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved. 5 * 6 * Use is subject to license terms. 7 * 8 * $Revision: 1.1 $ 9 * $Date: 2005/02/11 04:56:52 $ 10 * $State: Exp $ 11 */ 12 package com.lightcrafts.media.jai.rmi; 13 14 import java.awt.Rectangle; 15 import java.awt.image.RenderedImage; 16 import java.rmi.Remote; 17 import java.rmi.RemoteException; 18 import java.util.Vector; 19 import com.lightcrafts.mediax.jai.RenderableOp; 20 import com.lightcrafts.mediax.jai.RenderedOp; 21 22 /** 23 * An interface for server-side imaging. This interface attempts to 24 * mimic the RenderedImage interface as much as possible. However, there 25 * are several unavoidable differences: 26 * 27 * <ul> 28 * <li> Additional setSource() methods are provided to inform the server 29 * as to the source of image data for this image. Sources may be set 30 * either from a RenderedImage that is copied over to the server, or 31 * from a graph of RenderedOp objects indicating an abstract 32 * imaging chain to be instantiated using the server's 33 * OperationRegistry. 34 * 35 * <li> All methods throw RemoteException. This is a requirement of 36 * any Remote interface. 37 * 38 * <li> The getTile() method does not return a reference to a `live' 39 * tile; instead it returns a client-side copy of the server image's 40 * tile. The difference is moot since the server image is immutable. 41 * </ul> 42 * 43 * To instantiate a RMIImage, do the following: 44 * 45 * <pre> 46 * RMIImage im; 47 * im = java.rmi.Naming.lookup("//host:1099/com.lightcrafts.mediax.jai.RemoteImageServer"); 48 * </pre> 49 * 50 * <p> The hostname and port will of course depend on the local setup. 51 * The host must be running an <code>rmiregistry</code> process and have a 52 * RemoteImageServer listening at the desired port. 53 * 54 * <p> This call will result in the creation of a server-side 55 * RMIImageImpl object and a client-side stub object. 56 * The client stub serializes its method arguments and transfers 57 * them to the server over a socket; the server serializes it return 58 * values and returns them in the same manner. 59 * 60 * <p> This process implies that all arguments and return values must 61 * be serializable. In the case of a RenderedImage source, 62 * serializability is not guaranteed and must be considered on a 63 * class-by-class basis. For RenderedOps, which are basically 64 * simple nodes connected by ParameterBlocks, serializability will be 65 * determined by the serializabiility of the ultimate 66 * (non-RenderedOp) sources of the DAG and the serializability 67 * of any ad-hoc Object parameters held in the ParameterBlocks. 68 * 69 * <p> The return values of the getData(), copyData(), and getTile() 70 * methods are various kinds of Rasters; at present, Java2D does not 71 * define serialization on Rasters. We will either need to add this 72 * feature to Java2D or else coerce the server-side Rasters into a 73 * serializable subclass form. In any case, we will want to 74 * implement lossless (and possibly lossy) compression as part of 75 * the serialization process wherever possible. 76 * 77 * @see java.rmi.Remote 78 * @see java.rmi.RemoteException 79 * @see java.awt.image.RenderedImage 80 * @see RemoteImage 81 * 82 * @since EA3 83 * 84 */ 85 public interface RMIImage extends Remote { 86 /** 87 * The name to which the remote image server should be bound. 88 */ 89 public static final String RMI_IMAGE_SERVER_NAME = "RemoteImageServer"; 90 91 /** 92 * Returns the identifier of the remote image. This method should be 93 * called to return an identifier before any other methods are invoked. 94 * The same ID must be used in all subsequent references to the remote 95 * image. 96 */ getRemoteID()97 Long getRemoteID() throws RemoteException; 98 99 /** 100 * Sets the source of the image on the server side. This source 101 * should ideally be a lightweight reference to an image available 102 * locally on the server or over a further network link (for 103 * example, an IIPOpImage that contains a URL but not actual image 104 * data). 105 * 106 * <p> Although it is legal to use any RenderedImage, one should be 107 * aware that a deep copy might be made and transmitted to the server. 108 * 109 * @param id An ID for the source which must be unique across all clients. 110 * @param source a RenderedImage source. 111 */ setSource(Long id, RenderedImage source)112 void setSource(Long id, RenderedImage source) throws RemoteException; 113 114 /** 115 * Sets the source to a RenderedOp (i.e., an imaging DAG). 116 * This DAG will be copied over to the server where it will be 117 * transformed into an OpImage chain using the server's local 118 * OperationRegistry and available RenderedImageFactory objects. 119 * 120 * @param id An ID for the source which must be unique across all clients. 121 * @param source a RenderedOp source. 122 */ setSource(Long id, RenderedOp source)123 void setSource(Long id, RenderedOp source) throws RemoteException; 124 125 /** 126 * Sets the source to a RenderableOp defined by a renderable imaging 127 * DAG and a rendering context. The entire RenderableImage 128 * DAG will be copied over to the server. 129 */ setSource(Long id, RenderableOp source, RenderContextProxy renderContextProxy)130 void setSource(Long id, RenderableOp source, RenderContextProxy renderContextProxy) 131 throws RemoteException; 132 133 /** 134 * Disposes of any resouces allocated to the client object with 135 * the specified ID. 136 */ dispose(Long id)137 void dispose(Long id) throws RemoteException; 138 139 /** 140 * Returns a vector of RenderedImages that are the sources of 141 * image data for this RMIImage. Note that this method 142 * will often return an empty vector. 143 */ getSources(Long id)144 Vector getSources(Long id) throws RemoteException; 145 146 /** 147 * Gets a property from the property set of this image. 148 * If the property name is not recognized, java.awt.Image.UndefinedProperty 149 * will be returned. 150 * 151 * @param id An ID for the source which must be unique across all clients. 152 * @param name the name of the property to get, as a String. 153 * @return a reference to the property Object, or the value 154 * java.awt.Image.UndefinedProperty. 155 */ getProperty(Long id, String name)156 Object getProperty(Long id, String name) throws RemoteException; 157 158 /** 159 * Returns a list of names recognized by getProperty(String). 160 * 161 * @return an array of Strings representing proeprty names. 162 */ getPropertyNames(Long id)163 String [] getPropertyNames(Long id) throws RemoteException; 164 165 /** Returns the ColorModel associated with this image. */ getColorModel(Long id)166 ColorModelProxy getColorModel(Long id) throws RemoteException; 167 168 /** Returns the SampleModel associated with this image. */ getSampleModel(Long id)169 SampleModelProxy getSampleModel(Long id) throws RemoteException; 170 171 /** Returns the width of the RMIImage. */ getWidth(Long id)172 int getWidth(Long id) throws RemoteException; 173 174 /** Returns the height of the RMIImage. */ getHeight(Long id)175 int getHeight(Long id) throws RemoteException; 176 177 /** 178 * Returns the minimum X coordinate of the RMIImage. 179 */ getMinX(Long id)180 int getMinX(Long id) throws RemoteException; 181 182 /** 183 * Returns the minimum Y coordinate of the RMIImage. 184 */ getMinY(Long id)185 int getMinY(Long id) throws RemoteException; 186 187 /** Returns the number of tiles across the image. */ getNumXTiles(Long id)188 int getNumXTiles(Long id) throws RemoteException; 189 190 /** Returns the number of tiles down the image. */ getNumYTiles(Long id)191 int getNumYTiles(Long id) throws RemoteException; 192 193 /** 194 * Returns the index of the minimum tile in the X direction of the image. 195 */ getMinTileX(Long id)196 int getMinTileX(Long id) throws RemoteException; 197 198 /** 199 * Returns the index of the minimum tile in the Y direction of the image. 200 */ getMinTileY(Long id)201 int getMinTileY(Long id) throws RemoteException; 202 203 /** Returns the width of a tile in pixels. */ getTileWidth(Long id)204 int getTileWidth(Long id) throws RemoteException; 205 206 /** Returns the height of a tile in pixels. */ getTileHeight(Long id)207 int getTileHeight(Long id) throws RemoteException; 208 209 /** Returns the X offset of the tile grid relative to the origin. */ getTileGridXOffset(Long id)210 int getTileGridXOffset(Long id) throws RemoteException; 211 212 /** Returns the Y offset of the tile grid relative to the origin. */ getTileGridYOffset(Long id)213 int getTileGridYOffset(Long id) throws RemoteException; 214 215 /** 216 * Returns tile (x, y). Note that x and y are indices into the 217 * tile array, not pixel locations. Unlike in the true RenderedImage 218 * interface, the Raster that is returned should be considered a copy. 219 * 220 * @param id An ID for the source which must be unique across all clients. 221 * @param x the x index of the requested tile in the tile array 222 * @param y the y index of the requested tile in the tile array 223 * @return a copy of the tile as a Raster. 224 */ getTile(Long id, int x, int y)225 RasterProxy getTile(Long id, int x, int y) throws RemoteException; 226 227 /** 228 * Returns the entire image as a single Raster. 229 * 230 * @return a RasterProxy containing a copy of this image's data. 231 */ getData(Long id)232 RasterProxy getData(Long id) throws RemoteException; 233 234 /** 235 * Returns an arbitrary rectangular region of the RenderedImage 236 * in a Raster. The rectangle of interest will be clipped against 237 * the image bounds. 238 * 239 * @param id An ID for the source which must be unique across all clients. 240 * @param bounds the region of the RenderedImage to be returned. 241 * @return a RasterProxy containing a copy of the desired data. 242 */ getData(Long id, Rectangle bounds)243 RasterProxy getData(Long id, Rectangle bounds) throws RemoteException; 244 245 /** 246 * Returns the same result as getData(Rectangle) would for the 247 * same rectangular region. 248 */ copyData(Long id, Rectangle bounds)249 RasterProxy copyData(Long id, Rectangle bounds) throws RemoteException; 250 } 251