01: /*
02: * $RCSfile: TileDecoderFactory.java,v $
03: *
04: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
05: *
06: * Use is subject to license terms.
07: *
08: * $Revision: 1.1 $
09: * $Date: 2005/02/11 04:57:56 $
10: * $State: Exp $
11: */package javax.media.jai.tilecodec;
12:
13: import java.io.InputStream;
14: import javax.media.jai.remote.NegotiableCapability;
15:
16: /**
17: * A factory for creating <code>TileDecoder</code>s.
18: *
19: * <p> This class stipulates that the capabilities of the
20: * <code>TileDecoder</code> be specified by implementing the
21: * <code>getDecodingCapability()</code> method.
22: *
23: * @see javax.media.jai.remote.NegotiableCapability
24: *
25: * @since JAI 1.1
26: */
27: public interface TileDecoderFactory {
28:
29: /**
30: * Creates a <code>TileDecoder</code> capable of decoding the encoded
31: * data from the given <code>InputStream</code> using the specified
32: * <code>TileCodecParameterList</code> containing the decoding
33: * parameters to be used.
34: *
35: * <p> This method can return null if the <code>TileDecoder</code> is
36: * not capable of producing output for the given set of parameters.
37: * For example, if a <code>TileDecoder</code> is only capable of dealing
38: * with a jpeg quality factor of 0.5, and the associated
39: * <code>TileCodecParameterList</code> specifies a quality factor of 0.75,
40: * null should be returned.
41: *
42: * <p>It is recommended that the data in the supplied
43: * <code>InputStream</code> not be used as a factor in determining
44: * whether this <code>InputStream</code> can be successfully decoded,
45: * unless the supplied <code>InputStream</code> is known to be rewindable
46: * (i.e. its <code>markSupported()</code> method returns true or it has
47: * additional functionality that allows backward seeking). It is required
48: * that the <code>InputStream</code> contain the same data on
49: * returning from this method as before this method was called.
50: * In other words, the <code>InputStream</code> should only be used as a
51: * discriminator if it can be rewound to its starting position
52: * before returning from this method. Note that wrapping the
53: * incoming <code>InputStream</code> in a <code>PushbackInputStream</code>
54: * and then rewinding the <code>PushbackInputStream</code> before returning
55: * does not rewind the wrapped <code>InputStream</code>.
56: *
57: * <p> If the supplied <code>TileCodecParameterList</code> is null,
58: * a default <code>TileCodecParameterList</code> from the
59: * <code>TileCodecDescriptor</code> will be used to create the decoder.
60: *
61: * <p> Exceptions thrown by the <code>TileDecoder</code> will be
62: * caught by this method and will not be propagated.
63: *
64: * @param input The <code>InputStream</code> containing the encoded data
65: * to decode.
66: * @param param The parameters to be be used in the decoding process.
67: * @throws IllegalArgumentException if input is null.
68: */
69: TileDecoder createDecoder(InputStream input,
70: TileCodecParameterList param);
71:
72: /**
73: * Returns the capabilities of this <code>TileDecoder</code> as a
74: * <code>NegotiableCapability</code>.
75: *
76: * @see javax.media.jai.remote.NegotiableCapability
77: */
78: NegotiableCapability getDecodeCapability();
79: }
|