ImageInputStreamSpi


1   /*
2    * @(#)ImageInputStreamSpi.java 1.23 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.imageio.spi;
9   
10  import java.io.File  ;
11  import java.io.IOException  ;
12  import javax.imageio.stream.ImageInputStream  ;
13  
14  /**
15   * The service provider interface (SPI) for
16   * <code>ImageInputStream</code>s.  For more information on service
17   * provider interfaces, see the class comment for the
18   * <code>IIORegistry</code> class.
19   *
20   * <p> This interface allows arbitrary objects to be "wrapped" by
21   * instances of <code>ImageInputStream</code>.  For example,
22   * a particular <code>ImageInputStreamSpi</code> might allow
23   * a generic <code>InputStream</code> to be used as an input source;
24   * another might take input from a <code>URL</code>.
25   *
26   * <p> By treating the creation of <code>ImageInputStream</code>s as a
27   * pluggable service, it becomes possible to handle future input
28   * sources without changing the API.  Also, high-performance
29   * implementations of <code>ImageInputStream</code> (for example,
30   * native implementations for a particular platform) can be installed
31   * and used transparently by applications.
32   *
33   * @see IIORegistry
34   * @see javax.imageio.stream.ImageInputStream
35   *
36   * @version 0.5
37   */
38  public abstract class ImageInputStreamSpi extends IIOServiceProvider   {
39      
40      /**
41       * A <code>Class</code> object indicating the legal object type
42       * for use by the <code>createInputStreamInstance</code> method.
43       */
44      protected Class  <?> inputClass;
45  
46      /**
47       * Constructs a blank <code>ImageInputStreamSpi</code>.  It is up
48       * to the subclass to initialize instance variables and/or
49       * override method implementations in order to provide working
50       * versions of all methods.
51       */
52      protected ImageInputStreamSpi() {
53      }
54  
55      /**
56       * Constructs an <code>ImageInputStreamSpi</code> with a given set
57       * of values.
58       *
59       * @param vendorName the vendor name.
60       * @param version a version identifier.
61       * @param inputClass a <code>Class</code> object indicating the
62       * legal object type for use by the
63       * <code>createInputStreamInstance</code> method.
64       *
65       * @exception IllegalArgumentException if <code>vendorName</code>
66       * is <code>null</code>.
67       * @exception IllegalArgumentException if <code>version</code>
68       * is <code>null</code>.
69       */
70      public ImageInputStreamSpi(String   vendorName,
71                                 String   version,
72                                 Class  <?> inputClass) {
73          super(vendorName, version);
74          this.inputClass = inputClass;
75      }
76  
77      /**
78       * Returns a <code>Class</code> object representing the class or
79       * interface type that must be implemented by an input source in
80       * order to be "wrapped" in an <code>ImageInputStream</code> via
81       * the <code>createInputStreamInstance</code> method.
82       *
83       * <p> Typical return values might include
84       * <code>InputStream.class</code> or <code>URL.class</code>, but
85       * any class may be used.
86       *
87       * @return a <code>Class</code> variable.
88       *
89       * @see #createInputStreamInstance(Object, boolean, File)
90       */
91      public Class  <?> getInputClass() {
92          return inputClass;
93      }
94  
95      /**
96       * Returns <code>true</code> if the <code>ImageInputStream</code>
97       * implementation associated with this service provider can
98       * optionally make use of a cache file for improved performance
99       * and/or memory footrprint.  If <code>false</code>, the value of
100      * the <code>useCache</code> argument to
101      * <code>createInputStreamInstance</code> will be ignored.
102      *
103      * <p> The default implementation returns <code>false</code>.
104      *
105      * @return <code>true</code> if a cache file can be used by the
106      * input streams created by this service provider.
107      */
108     public boolean canUseCacheFile() {
109         return false;
110     }
111 
112     /**
113      * Returns <code>true</code> if the <code>ImageInputStream</code>
114      * implementation associated with this service provider requires
115      * the use of a cache <code>File</code>.  If <code>true</code>,
116      * the value of the <code>useCache</code> argument to
117      * <code>createInputStreamInstance</code> will be ignored.
118      *
119      * <p> The default implementation returns <code>false</code>.
120      *
121      * @return <code>true</code> if a cache file is needed by the
122      * input streams created by this service provider.
123      */
124     public boolean needsCacheFile() {
125         return false;
126     }
127 
128     /**
129      * Returns an instance of the <code>ImageInputStream</code>
130      * implementation associated with this service provider.  If the
131      * use of a cache file is optional, the <code>useCache</code>
132      * parameter will be consulted.  Where a cache is required, or 
133      * not applicable, the value of <code>useCache</code> will be ignored.
134      *
135      * @param input an object of the class type returned by
136      * <code>getInputClass</code>.
137      * @param useCache a <code>boolean</code> indicating whether a
138      * cache file should be used, in cases where it is optional.
139      * @param cacheDir a <code>File</code> indicating where the 
140      * cache file should be created, or <code>null</code> to use the
141      * system directory.
142      *
143      * @return an <code>ImageInputStream</code> instance.
144      *
145      * @exception IllegalArgumentException if <code>input</code> is
146      * not an instance of the correct class or is <code>null</code>.
147      * @exception IllegalArgumentException if a cache file is needed
148      * but <code>cacheDir</code> is non-<code>null</code> and is not a
149      * directory.
150      * @exception IOException if a cache file is needed but cannot be
151      * created.
152      *
153      * @see #getInputClass
154      * @see #canUseCacheFile
155      * @see #needsCacheFile
156      */
157     public abstract ImageInputStream  
158         createInputStreamInstance(Object   input,
159                                   boolean useCache,
160                                   File   cacheDir) throws IOException  ;
161 
162     /**
163      * Returns an instance of the <code>ImageInputStream</code>
164      * implementation associated with this service provider.  A cache
165      * file will be created in the system-dependent default
166      * temporary-file directory, if needed.
167      *
168      * @param input an object of the class type returned by
169      * <code>getInputClass</code>.
170      *
171      * @return an <code>ImageInputStream</code> instance.
172      *
173      * @exception IllegalArgumentException if <code>input</code> is
174      * not an instance of the correct class or is <code>null</code>.
175      * @exception IOException if a cache file is needed but cannot be
176      * created.
177      *
178      * @see #getInputClass()
179      */
180     public ImageInputStream   createInputStreamInstance(Object   input)
181         throws IOException   {
182         return createInputStreamInstance(input, true, null);
183     }
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags