ImageOutputStreamSpi


1   /*
2    * @(#)ImageOutputStreamSpi.java    1.19 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.ImageOutputStream  ;
13  
14  /**
15   * The service provider interface (SPI) for
16   * <code>ImageOutputStream</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>ImageOutputStream</code>.  For example, a
22   * particular <code>ImageOutputStreamSpi</code> might allow a generic
23   * <code>OutputStream</code> to be used as a destination; another
24   * might output to a <code>File</code> or to a device such as a serial
25   * port.
26   *
27   * <p> By treating the creation of <code>ImageOutputStream</code>s as
28   * a pluggable service, it becomes possible to handle future output
29   * destinations without changing the API.  Also, high-performance
30   * implementations of <code>ImageOutputStream</code> (for example,
31   * native implementations for a particular platform) can be installed
32   * and used transparently by applications.
33   *
34   * @see IIORegistry
35   * @see javax.imageio.stream.ImageOutputStream
36   *
37   * @version 0.5
38   */
39  public abstract class ImageOutputStreamSpi extends IIOServiceProvider   {
40  
41      /**
42       * A <code>Class</code> object indicating the legal object type
43       * for use by the <code>createInputStreamInstance</code> method.
44       */
45      protected Class  <?> outputClass;
46  
47      /**
48       * Constructs a blank <code>ImageOutputStreamSpi</code>.  It is up
49       * to the subclass to initialize instance variables and/or
50       * override method implementations in order to provide working
51       * versions of all methods.
52       */
53      protected ImageOutputStreamSpi() {
54      }
55  
56      /**
57       * Constructs an <code>ImageOutputStreamSpi</code> with a given
58       * set of values.
59       *
60       * @param vendorName the vendor name.
61       * @param version a version identifier.
62       * @param outputClass a <code>Class</code> object indicating the
63       * legal object type for use by the
64       * <code>createOutputStreamInstance</code> method.
65       *
66       * @exception IllegalArgumentException if <code>vendorName</code>
67       * is <code>null</code>.
68       * @exception IllegalArgumentException if <code>version</code>
69       * is <code>null</code>. 
70      */
71      public ImageOutputStreamSpi(String   vendorName,
72                                  String   version,
73                                  Class  <?> outputClass) {
74          super(vendorName, version);
75          this.outputClass = outputClass;
76      }
77  
78      /**
79       * Returns a <code>Class</code> object representing the class or
80       * interface type that must be implemented by an output
81       * destination in order to be "wrapped" in an
82       * <code>ImageOutputStream</code> via the
83       * <code>createOutputStreamInstance</code> method.
84       *
85       * <p> Typical return values might include
86       * <code>OutputStream.class</code> or <code>File.class</code>, but
87       * any class may be used.
88       *
89       * @return a <code>Class</code> variable.
90       *
91       * @see #createOutputStreamInstance(Object, boolean, File)
92       */
93      public Class  <?> getOutputClass() {
94          return outputClass;
95      }
96  
97      /**
98       * Returns <code>true</code> if the <code>ImageOutputStream</code>
99       * implementation associated with this service provider can
100      * optionally make use of a cache <code>File</code> for improved
101      * performance and/or memory footrprint.  If <code>false</code>,
102      * the value of the <code>cacheFile</code> argument to
103      * <code>createOutputStreamInstance</code> will be ignored.
104      *
105      * <p> The default implementation returns <code>false</code>.
106      *
107      * @return <code>true</code> if a cache file can be used by the
108      * output streams created by this service provider.
109      */
110     public boolean canUseCacheFile() {
111         return false;
112     }
113 
114     /**
115      * Returns <code>true</code> if the <code>ImageOutputStream</code>
116      * implementation associated with this service provider requires
117      * the use of a cache <code>File</code>.
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      * output streams created by this service provider.
123      */
124     public boolean needsCacheFile() {
125         return false;
126     }
127 
128     /**
129      * Returns an instance of the <code>ImageOutputStream</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 output an object of the class type returned by
136      * <code>getOutputClass</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>ImageOutputStream</code> instance.
144      *
145      * @exception IllegalArgumentException if <code>output</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 #getOutputClass
154      */
155     public abstract
156         ImageOutputStream   createOutputStreamInstance(Object   output,
157                                                      boolean useCache,
158                                                      File   cacheDir)
159         throws IOException  ;
160 
161     /**
162      * Returns an instance of the <code>ImageOutputStream</code>
163      * implementation associated with this service provider.  A cache
164      * file will be created in the system-dependent default
165      * temporary-file directory, if needed.
166      *
167      * @param output an object of the class type returned by
168      * <code>getOutputClass</code>.
169      *
170      * @return an <code>ImageOutputStream</code> instance.
171      *
172      * @exception IllegalArgumentException if <code>output</code> is
173      * not an instance of the correct class or is <code>null</code>.
174      * @exception IOException if a cache file is needed but cannot be
175      * created.
176      *
177      * @see #getOutputClass()
178      */
179     public ImageOutputStream   createOutputStreamInstance(Object   output)
180         throws IOException   {
181         return createOutputStreamInstance(output, true, null);
182     }
183 }
184
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags