001: /*
002: * $RCSfile: FileStoreDescriptor.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:35 $
010: * $State: Exp $
011: */
012: package javax.media.jai.operator;
013:
014: import com.sun.media.jai.codec.ImageCodec;
015: import com.sun.media.jai.codec.ImageEncodeParam;
016: import java.awt.RenderingHints;
017: import java.awt.image.RenderedImage;
018: import java.awt.image.renderable.ParameterBlock;
019: import java.io.File;
020: import java.io.IOException;
021: import javax.media.jai.JAI;
022: import javax.media.jai.OperationDescriptorImpl;
023: import javax.media.jai.ParameterBlockJAI;
024: import javax.media.jai.RenderedOp;
025: import javax.media.jai.registry.RenderedRegistryMode;
026:
027: /**
028: * An <code>OperationDescriptor</code> describing the "FileStore" operation.
029: *
030: * The "FileStore" operation writes an image to a given file in a specified
031: * format using the supplied encoding parameters.
032: *
033: * <p> In the default instance the <code>validateParameters()</code> method
034: * checks for the named file to be writable if it already exists, else that
035: * it can be created. If not, it will return <code>false</code>, causing
036: * <code>JAI.createNS()</code> to throw an
037: * <code>IllegalArgumentException</code>.
038: *
039: * <p> In special cases such as an image being written to a remote system,
040: * the above check for existence of a file on the local system should be
041: * bypassed. This can be accomplished by setting the <code>Boolean</code>
042: * variable <code>checkFileLocally</code> to <code>FALSE</code> in the
043: * <code>ParameterBlock</code>.
044:
045: * <p> The third parameter contains an instance of
046: * <code>ImageEncodeParam</code> to be used during the decoding. It
047: * may be set to <code>null</code> in order to perform default
048: * encoding, or equivalently may be omitted. If
049: * non-<code>null</code>, it must be of the correct class type for the
050: * selected format.
051: *
052: * <p> The requested file path must be writable.
053: *
054: * <p><b> The classes in the <code>com.sun.media.jai.codec</code>
055: * package are not a committed part of the JAI API. Future releases
056: * of JAI will make use of new classes in their place. This
057: * class will change accordingly.</b>
058: *
059: * <p><table border=1>
060: * <caption>Resource List</caption>
061: * <tr><th>Name</th> <th>Value</th></tr>
062: * <tr><td>GlobalName</td> <td>filestore</td></tr>
063: * <tr><td>LocalName</td> <td>filestore</td></tr>
064: * <tr><td>Vendor</td> <td>com.sun.media.jai</td></tr>
065: * <tr><td>Description</td> <td>Stores an image to a file.</td></tr>
066: * <tr><td>DocURL</td> <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/FileStoreDescriptor.html</td></tr>
067: * <tr><td>Version</td> <td>1.0</td></tr>
068: * <tr><td>arg0Desc</td> <td>The path of the file to write to.</td></tr>
069: * <tr><td>arg1Desc</td> <td>The format of the file.</td></tr>
070: * <tr><td>arg2Desc</td> <td>The encoding parameters.</td></tr>
071: * <tr><td>arg3Desc</td> <td>Boolean specifying whether check for file creation / writing locally should be done.</td></tr>
072: * </table></p>
073: *
074: * <p><table border=1>
075: * <caption>Parameter List</caption>
076: * <tr><th>Name</th> <th>Class Type</th>
077: * <th>Default Value</th></tr>
078: * <tr><td>filename</td> <td>java.lang.String</td>
079: * <td>NO_PARAMETER_DEFAULT</td>
080: * <tr><td>format</td> <td>java.lang.String</td>
081: * <td>"tiff"</td>
082: * <tr><td>param</td> <td>com.sun.media.jai.codec.ImageEncodeParam</td>
083: * <td>null</td>
084: * <tr><td>checkFileLocally</td> <td>java.lang.Boolean</td>
085: * <td>TRUE</td>
086: * </table></p>
087: *
088: * @see javax.media.jai.OperationDescriptor
089: */
090: public class FileStoreDescriptor extends OperationDescriptorImpl {
091:
092: /**
093: * The resource strings that provide the general documentation and
094: * specify the parameter list for the "FileStore" operation.
095: */
096: private static final String[][] resources = {
097: { "GlobalName", "FileStore" },
098: { "LocalName", "FileStore" },
099: { "Vendor", "com.sun.media.jai" },
100: { "Description", JaiI18N.getString("FileStoreDescriptor0") },
101: {
102: "DocURL",
103: "http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/FileStoreDescriptor.html" },
104: { "Version", JaiI18N.getString("DescriptorVersion") },
105: { "arg0Desc", JaiI18N.getString("FileStoreDescriptor1") },
106: { "arg1Desc", JaiI18N.getString("FileStoreDescriptor2") },
107: { "arg2Desc", JaiI18N.getString("FileStoreDescriptor3") },
108: { "arg3Desc", JaiI18N.getString("FileStoreDescriptor11") } };
109:
110: /** The parameter names for the "FileStore" operation. */
111: private static final String[] paramNames = { "filename", "format",
112: "param", "checkFileLocally" };
113:
114: /** The parameter class types for the "FileStore" operation. */
115: private static final Class[] paramClasses = {
116: java.lang.String.class, java.lang.String.class,
117: com.sun.media.jai.codec.ImageEncodeParam.class,
118: java.lang.Boolean.class };
119:
120: /** The parameter default values for the "FileStore" operation. */
121: private static final Object[] paramDefaults = {
122: NO_PARAMETER_DEFAULT, "tiff", null, Boolean.TRUE };
123:
124: private static final String[] supportedModes = { "rendered" };
125:
126: /** Constructor. */
127: public FileStoreDescriptor() {
128: super (resources, supportedModes, 1, paramNames, paramClasses,
129: paramDefaults, null);
130: }
131:
132: /**
133: * Validates the input source and parameters.
134: *
135: * <p> In addition to the standard checks performed by the
136: * superclass method, this method checks that the format name is
137: * recognized and is capable of encoding the source image using
138: * the encoding parameter "param", if non-<code>null</code>,
139: * ans that the output file path "filename" is writable.
140: */
141: public boolean validateArguments(String modeName,
142: ParameterBlock args, StringBuffer msg) {
143: if (!super .validateArguments(modeName, args, msg)) {
144: return false;
145: }
146:
147: if (!modeName.equalsIgnoreCase("rendered"))
148: return true;
149:
150: // Retrieve the format.
151: String format = (String) args.getObjectParameter(1);
152:
153: // Retrieve the associated ImageCodec.
154: ImageCodec codec = ImageCodec.getCodec(format);
155:
156: // Check for null codec.
157: if (codec == null) {
158: msg.append(getName() + " "
159: + JaiI18N.getString("FileStoreDescriptor4"));
160: return false;
161: }
162:
163: // Retrieve the ImageEncodeParam object.
164: ImageEncodeParam param = (ImageEncodeParam) args
165: .getObjectParameter(2);
166:
167: RenderedImage src = args.getRenderedSource(0);
168:
169: // Verify that the image can be encoded with null parameters.
170: if (!codec.canEncodeImage(src, param)) {
171: msg.append(getName() + " "
172: + JaiI18N.getString("FileStoreDescriptor5"));
173: return false;
174: }
175:
176: // Retrieve the file path.
177: String pathName = (String) args.getObjectParameter(0);
178: if (pathName == null) {
179: msg.append(getName() + " "
180: + JaiI18N.getString("FileStoreDescriptor6"));
181: return false;
182: }
183:
184: // Perform non-destructive test that the file
185: // may be created and written.
186: Boolean checkFile = (Boolean) args.getObjectParameter(3);
187: if (checkFile.booleanValue()) {
188: try {
189: File f = new File(pathName);
190: if (f.exists()) {
191: if (!f.canWrite()) {
192: // Cannot write to existing file.
193: msg
194: .append(getName()
195: + " "
196: + JaiI18N
197: .getString("FileStoreDescriptor7"));
198: return false;
199: }
200: } else {
201: if (!f.createNewFile()) {
202: // Cannot create file.
203: msg
204: .append(getName()
205: + " "
206: + JaiI18N
207: .getString("FileStoreDescriptor8"));
208: return false;
209: }
210: f.delete();
211: }
212: } catch (IOException ioe) {
213: // I/O exception during createNewFile().
214: msg.append(getName() + " "
215: + JaiI18N.getString("FileStoreDescriptor9")
216: + " " + ioe.getMessage());
217: return false;
218: } catch (SecurityException se) {
219: // Security exception during exists(), canWrite(),
220: // createNewFile(), or delete().
221: msg.append(getName() + " "
222: + JaiI18N.getString("FileStoreDescriptor10")
223: + " " + se.getMessage());
224: return false;
225: }
226: }
227:
228: return true;
229: }
230:
231: /**
232: * Returns true indicating that the operation should be rendered
233: * immediately during a call to <code>JAI.create()</code>.
234: *
235: * @see javax.media.jai.OperationDescriptor
236: */
237: public boolean isImmediate() {
238: return true;
239: }
240:
241: /**
242: * Stores an image to a file.
243: *
244: * <p>Creates a <code>ParameterBlockJAI</code> from all
245: * supplied arguments except <code>hints</code> and invokes
246: * {@link JAI#create(String,ParameterBlock,RenderingHints)}.
247: *
248: * @see JAI
249: * @see ParameterBlockJAI
250: * @see RenderedOp
251: *
252: * @param source0 <code>RenderedImage</code> source 0.
253: * @param filename The path of the file to write to.
254: * @param format The format of the file.
255: * May be <code>null</code>.
256: * @param param The encoding parameters.
257: * May be <code>null</code>.
258: * @param checkFileLocally Boolean specifying whether check for file
259: * creation / writing locally should be done.
260: * May be <code>null</code>.
261: * @param hints The <code>RenderingHints</code> to use.
262: * May be <code>null</code>.
263: * @return The <code>RenderedOp</code> destination.
264: * @throws IllegalArgumentException if <code>source0</code> is <code>null</code>.
265: * @throws IllegalArgumentException if <code>filename</code> is <code>null</code>.
266: */
267: public static RenderedOp create(RenderedImage source0,
268: String filename, String format, ImageEncodeParam param,
269: Boolean checkFileLocally, RenderingHints hints) {
270: ParameterBlockJAI pb = new ParameterBlockJAI("FileStore",
271: RenderedRegistryMode.MODE_NAME);
272:
273: pb.setSource("source0", source0);
274:
275: pb.setParameter("filename", filename);
276: pb.setParameter("format", format);
277: pb.setParameter("param", param);
278: pb.setParameter("checkFileLocally", checkFileLocally);
279:
280: return JAI.create("FileStore", pb, hints);
281: }
282: }
|