001: /*
002: * $RCSfile: TileEncoderRegistry.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:49 $
010: * $State: Exp $
011: */package javax.media.jai.registry;
012:
013: import java.awt.image.Raster;
014: import java.awt.image.SampleModel;
015: import java.io.IOException;
016: import java.io.OutputStream;
017: import java.util.Iterator;
018: import java.util.List;
019: import javax.media.jai.JAI;
020: import javax.media.jai.OperationRegistry;
021: import javax.media.jai.tilecodec.TileCodecParameterList;
022: import javax.media.jai.tilecodec.TileEncoder;
023: import javax.media.jai.tilecodec.TileEncoderFactory;
024:
025: /**
026: * Utility class to provide type-safe interaction with the
027: * <code>OperationRegistry</code> for <code>TileEncoderFactory</code> objects.
028: *
029: * If the <code>OperationRegistry</code> specified as an argument to the
030: * methods in this class is null, then <code>JAI.getOperationRegistry()</code>
031: * will be used.
032: *
033: * @since JAI 1.1
034: */
035: public final class TileEncoderRegistry {
036:
037: private static final String MODE_NAME = TileEncoderRegistryMode.MODE_NAME;
038:
039: /**
040: * Registers the given <code>TileEncoderFactory</code> with the given
041: * <code>OperationRegistry</code> under the given formatName and
042: * productName.
043: *
044: * @param registry The <code>OperationRegistry</code> to register the
045: * <code>TileEncoderFactory</code> with.
046: * @param formatName The formatName to register the
047: * <code>TileEncoderFactory</code> under.
048: * @param productName The productName to register the
049: * <code>TileEncoderFactory</code> under.
050: * @param tef The <code>TileEncoderFactory</code> to register.
051: *
052: * @throws IllegalArgumentException if formatName is null.
053: * @throws IllegalArgumentException if productName is null.
054: * @throws IllegalArgumentException if tef is null.
055: * @throws IllegalArgumentException if there is no
056: * <code>TileCodecDescriptor</code> registered against the
057: * given <code>formatName</code>.
058: */
059: public static void register(OperationRegistry registry,
060: String formatName, String productName,
061: TileEncoderFactory tef) {
062:
063: registry = (registry != null) ? registry : JAI
064: .getDefaultInstance().getOperationRegistry();
065:
066: registry.registerFactory(MODE_NAME, formatName, productName,
067: tef);
068: }
069:
070: /**
071: * Unregisters the given <code>TileEncoderFactory</code> previously
072: * registered under the given formatName and productName in the given
073: * <code>OperationRegistry</code>.
074: *
075: * @param registry The <code>OperationRegistry</code> to unregister the
076: * <code>TileEncoderFactory</code> from.
077: * @param formatName The formatName to unregister the
078: * <code>TileEncoderFactory</code> from.
079: * @param productName The productName to unregister the
080: * <code>TileEncoderFactory</code> from.
081: * @param tef The <code>TileEncoderFactory</code> to unregister.
082: *
083: * @throws IllegalArgumentException if formatName is null.
084: * @throws IllegalArgumentException if productName is null.
085: * @throws IllegalArgumentException if tef is null.
086: * @throws IllegalArgumentException if there is no
087: * <code>TileCodecDescriptor</code> registered against the
088: * given <code>formatName</code>.
089: * @throws IllegalArgumentException if the tef was not previously
090: * registered against the given formatName and productName.
091: */
092: public static void unregister(OperationRegistry registry,
093: String formatName, String productName,
094: TileEncoderFactory tef) {
095:
096: registry = (registry != null) ? registry : JAI
097: .getDefaultInstance().getOperationRegistry();
098:
099: registry.unregisterFactory(MODE_NAME, formatName, productName,
100: tef);
101: }
102:
103: /**
104: * Sets a preference between the given two <code>TileEncoderFactory</code>
105: * objects in the given <code>OperationRegistry</code> under the given
106: * formatName and productName.
107: *
108: * @param registry The <code>OperationRegistry</code> to set
109: * preferences on.
110: * @param formatName The formatName of the two
111: * <code>TileEncoderFactory</code>s.
112: * @param productName The productName of the two
113: * <code>TileEncoderFactory</code>s.
114: * @param preferredTEF The preferred <code>TileEncoderFactory</code>.
115: * @param otherTEF The other <code>TileEncoderFactory</code>.
116: *
117: * @throws IllegalArgumentException if formatName is null.
118: * @throws IllegalArgumentException if productName is null.
119: * @throws IllegalArgumentException if preferredTEF is null.
120: * @throws IllegalArgumentException if otherTEF is null.
121: * @throws IllegalArgumentException if there is no
122: * <code>TileCodecDescriptor</code> registered against the
123: * given <code>formatName</code>.
124: * @throws IllegalArgumentException if either of the two tef's
125: * was not previously registered against formatName and productName.
126: */
127: public static void setPreference(OperationRegistry registry,
128: String formatName, String productName,
129: TileEncoderFactory preferredTEF, TileEncoderFactory otherTEF) {
130:
131: registry = (registry != null) ? registry : JAI
132: .getDefaultInstance().getOperationRegistry();
133:
134: registry.setFactoryPreference(MODE_NAME, formatName,
135: productName, preferredTEF, otherTEF);
136: }
137:
138: /**
139: * Unsets a preference previously set amongst the given two
140: * <code>TileEncoderFactory</code> objects in the given
141: * <code>OperationRegistry</code> under the given formatName and productName.
142: *
143: * @param registry The <code>OperationRegistry</code> to unset
144: * preferences on.
145: * @param formanName The formatName of the two
146: * <code>TileEncoderFactory</code>s.
147: * @param productName The productName of the two
148: * <code>TileEncoderFactory</code>s.
149: * @param preferredTEF The preferred <code>TileEncoderFactory</code>.
150: * @param otherTEF The other <code>TileEncoderFactory</code>.
151: *
152: * @throws IllegalArgumentException if formatName is null.
153: * @throws IllegalArgumentException if productName is null.
154: * @throws IllegalArgumentException if preferredTEF is null.
155: * @throws IllegalArgumentException if otherTEF is null.
156: * @throws IllegalArgumentException if there is no
157: * <code>TileCodecDescriptor</code> registered against the
158: * given <code>formatName</code>.
159: * @throws IllegalArgumentException if either of the two tef's
160: * was not previously registered against formatName and productName.
161: */
162: public static void unsetPreference(OperationRegistry registry,
163: String formatName, String productName,
164: TileEncoderFactory preferredTEF, TileEncoderFactory otherTEF) {
165:
166: registry = (registry != null) ? registry : JAI
167: .getDefaultInstance().getOperationRegistry();
168:
169: registry.unsetFactoryPreference(MODE_NAME, formatName,
170: productName, preferredTEF, otherTEF);
171: }
172:
173: /**
174: * Clears all preferences set for registered <code>TileEncoderFactory</code>s
175: * under the given formatName and productName in the given
176: * <code>OperationRegistry</code>.
177: *
178: * @param registry The <code>OperationRegistry</code> to clear
179: * preferences from.
180: * @param formatName The format name to clear preferences under.
181: * @param productName The productName to clear preferences under.
182: *
183: * @throws IllegalArgumentException if formatName is null.
184: * @throws IllegalArgumentException if productName is null.
185: * @throws IllegalArgumentException if there is no
186: * <code>TileCodecDescriptor</code> registered against the
187: * given <code>formatName</code>.
188: */
189: public static void clearPreferences(OperationRegistry registry,
190: String formatName, String productName) {
191:
192: registry = (registry != null) ? registry : JAI
193: .getDefaultInstance().getOperationRegistry();
194:
195: registry.clearFactoryPreferences(MODE_NAME, formatName,
196: productName);
197: }
198:
199: /**
200: * Returns a List of the <code>TileEncoderFactory</code>s registered
201: * in the given <code>OperationRegistry</code> under the given
202: * formatName and productName, in an ordering that satisfies
203: * all of the pairwise preferences that have been set. Returns
204: * <code>null</code> if cycles exist.
205: *
206: * @param registry The <code>OperationRegistry</code> to clear
207: * preferences from.
208: * @param formatName The format name to clear preferences under.
209: * @param productName The productName to clear preferences under.
210: *
211: * @throws IllegalArgumentException if formatName is null.
212: * @throws IllegalArgumentException if productName is null.
213: * @throws IllegalArgumentException if there is no
214: * <code>TileCodecDescriptor</code> registered against the
215: * given <code>formatName</code>.
216: */
217: public static List getOrderedList(OperationRegistry registry,
218: String formatName, String productName) {
219:
220: registry = (registry != null) ? registry : JAI
221: .getDefaultInstance().getOperationRegistry();
222:
223: return registry.getOrderedFactoryList(MODE_NAME, formatName,
224: productName);
225: }
226:
227: /**
228: * Returns an <code>Iterator</code> over all
229: * <code>TileEncoderFactory</code> objects registered under the
230: * given format name over all products. The order of the
231: * <code>TileEncoderFactory</code> objects in the iteration will
232: * be according to the pairwise preferences among products and
233: * <code>TileEncoderFactory</code> objects within a product. The
234: * <code>remove()</code> method of the <code>Iterator</code>
235: * may not be implemented.
236: *
237: * @param registry The <code>OperationRegistry</code> to use.
238: * @param formatName The format name.
239: *
240: * @return an <code>Iterator</code> over <code>TileEncoderFactory</code>
241: * objects.
242: *
243: * @throws IllegalArgumentException if formatName is <code>null</code>
244: * @throws IllegalArgumentException if there is no
245: * <code>TileCodecDescriptor</code> registered against
246: * the <code>formatName</code>.
247: */
248: public static Iterator getIterator(OperationRegistry registry,
249: String formatName) {
250:
251: registry = (registry != null) ? registry : JAI
252: .getDefaultInstance().getOperationRegistry();
253:
254: return registry.getFactoryIterator(MODE_NAME, formatName);
255: }
256:
257: /**
258: * Returns the the most preferred <code>TileEncoderFactory</code>
259: * object registered against the given format name. This
260: * method will return the first <code>TileEncoderFactory</code> that
261: * would be encountered by the <code>Iterator</code> returned by the
262: * <code>getIterator()</code> method.
263: *
264: * @param registry The <code>OperationRegistry</code> to use.
265: * If this is <code>null</code>, then <code>
266: * JAI.getDefaultInstance().getOperationRegistry()</code>
267: * will be used.
268: * @param formatName The format name as a <code>String</code>
269: *
270: * @return a registered <code>TileEncoderFactory</code> object
271: *
272: * @throws IllegalArgumentException if formatName is <code>null</code>.
273: * @throws IllegalArgumentException if there is no <code>
274: * TileCodecDescriptor</code> registered against the <code>formatName</code>
275: */
276: public static TileEncoderFactory get(OperationRegistry registry,
277: String formatName) {
278:
279: registry = (registry != null) ? registry : JAI
280: .getDefaultInstance().getOperationRegistry();
281:
282: return (TileEncoderFactory) registry.getFactory(MODE_NAME,
283: formatName);
284: }
285:
286: /**
287: * Creates a <code>TileEncoder</code> for the specified format that is
288: * capable of handling the supplied arguments.
289: *
290: * <p> The preferences set amongst the <code>TileEncoderFactory</code>
291: * objects registered with the <code>OperationRegistry</code> are used
292: * to select the most prefered <code>TileEncoderFactory</code> whose
293: * <code>createEncoder()</code> method returns a non-null value.
294: *
295: * <p>Since this class is a simple type-safe wrapper around
296: * <code>OperationRegistry</code>'s type-unsafe methods, no additional
297: * argument validation is performed in this method. Thus errors/exceptions
298: * may occur if incorrect values are provided for the input arguments.
299: *
300: * <p>Exceptions thrown by the <code>TileEncoderFactory</code>s used to
301: * create the <code>TileEncoder</code> will be caught by this method
302: * and will not be propagated.
303: *
304: * @param registry The <code>OperationRegistry</code> to use to create
305: * the <code>TileEncoder</code>.
306: * @param formatName The format for which the <code>TileEncoder</code> is
307: * to be created.
308: * @param output The <code>OutputStream</code> to write encoded data to.
309: * @param paramList The object containing the tile encoding parameters.
310: * @param sampleModel The <code>SampleModel</code> of the
311: * <code>Raster</code> to be encoded.
312: *
313: * @throws IllegalArgumentException if formatName is null.
314: * @throws IllegalArgumentException if there is no
315: * <code>TileCodecDescriptor</code> registered against the
316: * given <code>formatName</code>.
317: */
318: public static TileEncoder create(OperationRegistry registry,
319: String formatName, OutputStream output,
320: TileCodecParameterList paramList, SampleModel sampleModel) {
321:
322: registry = (registry != null) ? registry : JAI
323: .getDefaultInstance().getOperationRegistry();
324:
325: Object args[] = { output, paramList, sampleModel };
326:
327: return (TileEncoder) registry.invokeFactory(MODE_NAME,
328: formatName, args);
329: }
330:
331: /**
332: * Encodes the given <code>Raster</code> using the given formatName and
333: * <code>TileCodecParameterList</code> and writes the encoded data to the
334: * specified <code>OutputStream</code>.
335: * The <code>TileEncoder</code> which performs the encoding is the
336: * one created from the most prefered <code>TileEncoderFactory</code>
337: * whose <code>create</code> method returns a non-null result. If
338: * there are no <code>TileEncoder</code> objects that can encode
339: * the specified <code>Raster</code> according to the encoding
340: * parameters supplied, nothing will be written to the specified
341: * <code>OutputStream</code>.
342: *
343: * <p> If the specified <code>TileCodecParameterList</code> is null, the
344: * default <code>TileCodecParameterList</code> retrieved by the specific
345: * <code>TileEncoder.getDefaultParameters()</code> method for the
346: * "tileEncoder" registry mode will be used.
347: *
348: * <p> If multiple tiles are to be encoded to the same
349: * <code>OutputStream</code> in the same format using the same
350: * <code>TileCodecParameterList</code>, it is advisable to create a
351: * <code>TileEncoder</code> object and use the <code>encode()</code> method
352: * on this encoder to encode each tile, thus creating and using only a
353: * single <code>TileEncoder</code> object. The <code>encode()</code>
354: * method on <code>TileEncoderRegistry</code> creates a new
355: * <code>TileEncoder</code> object each time it is called.
356: *
357: * <p>Since this class is a simple type-safe wrapper around
358: * <code>OperationRegistry</code>'s type-unsafe methods, no additional
359: * argument validation is performed in this method. Thus errors/exceptions
360: * may occur if incorrect values are provided for the input arguments.
361: *
362: * <p>Exceptions thrown by the <code>TileEncoderFactory</code>s used to
363: * create the <code>TileEncoder</code> will be caught by this method
364: * and will not be propagated.
365: *
366: * @param registry The <code>OperationRegistry</code> to use to create
367: * the <code>TileEncoder</code>.
368: * @param formatName The name of the format to encode the data in.
369: * @param raster The <code>Raster</code> to be encoded.
370: * @param output The <code>OutputStream</code> to write the encoded
371: * data to.
372: * @param param The <code>TileCodecParameterList</code> to be used.
373: * @throws IllegalArgumentException if formatName is null.
374: * @throws IOException if an input/output error occurs during the encoding.
375: * @throws IllegalArgumentException if there is no
376: * <code>TileCodecDescriptor</code> registered against the
377: * given <code>formatName</code>.
378: *
379: * @return The associated <code>TileEncoder</code>, or <code>null</code>.
380: */
381: public static void encode(OperationRegistry registry,
382: String formatName, Raster raster, OutputStream output,
383: TileCodecParameterList param) throws IOException {
384:
385: TileEncoder encoder = create(registry, formatName, output,
386: param, raster.getSampleModel());
387:
388: if (encoder != null)
389: encoder.encode(raster);
390: }
391: }
|