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