1/* 2 * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.imageio.spi; 27 28import java.io.File; 29import java.io.IOException; 30import javax.imageio.stream.ImageOutputStream; 31 32/** 33 * The service provider interface (SPI) for 34 * {@code ImageOutputStream}s. For more information on service 35 * provider interfaces, see the class comment for the 36 * {@code IIORegistry} class. 37 * 38 * <p> This interface allows arbitrary objects to be "wrapped" by 39 * instances of {@code ImageOutputStream}. For example, a 40 * particular {@code ImageOutputStreamSpi} might allow a generic 41 * {@code OutputStream} to be used as a destination; another 42 * might output to a {@code File} or to a device such as a serial 43 * port. 44 * 45 * <p> By treating the creation of {@code ImageOutputStream}s as 46 * a pluggable service, it becomes possible to handle future output 47 * destinations without changing the API. Also, high-performance 48 * implementations of {@code ImageOutputStream} (for example, 49 * native implementations for a particular platform) can be installed 50 * and used transparently by applications. 51 * 52 * @see IIORegistry 53 * @see javax.imageio.stream.ImageOutputStream 54 * 55 */ 56public abstract class ImageOutputStreamSpi extends IIOServiceProvider { 57 58 /** 59 * A {@code Class} object indicating the legal object type 60 * for use by the {@code createInputStreamInstance} method. 61 */ 62 protected Class<?> outputClass; 63 64 /** 65 * Constructs a blank {@code ImageOutputStreamSpi}. It is up 66 * to the subclass to initialize instance variables and/or 67 * override method implementations in order to provide working 68 * versions of all methods. 69 */ 70 protected ImageOutputStreamSpi() { 71 } 72 73 /** 74 * Constructs an {@code ImageOutputStreamSpi} with a given 75 * set of values. 76 * 77 * @param vendorName the vendor name. 78 * @param version a version identifier. 79 * @param outputClass a {@code Class} object indicating the 80 * legal object type for use by the 81 * {@code createOutputStreamInstance} method. 82 * 83 * @exception IllegalArgumentException if {@code vendorName} 84 * is {@code null}. 85 * @exception IllegalArgumentException if {@code version} 86 * is {@code null}. 87 */ 88 public ImageOutputStreamSpi(String vendorName, 89 String version, 90 Class<?> outputClass) { 91 super(vendorName, version); 92 this.outputClass = outputClass; 93 } 94 95 /** 96 * Returns a {@code Class} object representing the class or 97 * interface type that must be implemented by an output 98 * destination in order to be "wrapped" in an 99 * {@code ImageOutputStream} via the 100 * {@code createOutputStreamInstance} method. 101 * 102 * <p> Typical return values might include 103 * {@code OutputStream.class} or {@code File.class}, but 104 * any class may be used. 105 * 106 * @return a {@code Class} variable. 107 * 108 * @see #createOutputStreamInstance(Object, boolean, File) 109 */ 110 public Class<?> getOutputClass() { 111 return outputClass; 112 } 113 114 /** 115 * Returns {@code true} if the {@code ImageOutputStream} 116 * implementation associated with this service provider can 117 * optionally make use of a cache {@code File} for improved 118 * performance and/or memory footrprint. If {@code false}, 119 * the value of the {@code cacheFile} argument to 120 * {@code createOutputStreamInstance} will be ignored. 121 * 122 * <p> The default implementation returns {@code false}. 123 * 124 * @return {@code true} if a cache file can be used by the 125 * output streams created by this service provider. 126 */ 127 public boolean canUseCacheFile() { 128 return false; 129 } 130 131 /** 132 * Returns {@code true} if the {@code ImageOutputStream} 133 * implementation associated with this service provider requires 134 * the use of a cache {@code File}. 135 * 136 * <p> The default implementation returns {@code false}. 137 * 138 * @return {@code true} if a cache file is needed by the 139 * output streams created by this service provider. 140 */ 141 public boolean needsCacheFile() { 142 return false; 143 } 144 145 /** 146 * Returns an instance of the {@code ImageOutputStream} 147 * implementation associated with this service provider. If the 148 * use of a cache file is optional, the {@code useCache} 149 * parameter will be consulted. Where a cache is required, or 150 * not applicable, the value of {@code useCache} will be ignored. 151 * 152 * @param output an object of the class type returned by 153 * {@code getOutputClass}. 154 * @param useCache a {@code boolean} indicating whether a 155 * cache file should be used, in cases where it is optional. 156 * @param cacheDir a {@code File} indicating where the 157 * cache file should be created, or {@code null} to use the 158 * system directory. 159 * 160 * @return an {@code ImageOutputStream} instance. 161 * 162 * @exception IllegalArgumentException if {@code output} is 163 * not an instance of the correct class or is {@code null}. 164 * @exception IllegalArgumentException if a cache file is needed, 165 * but {@code cacheDir} is non-{@code null} and is not a 166 * directory. 167 * @exception IOException if a cache file is needed but cannot be 168 * created. 169 * 170 * @see #getOutputClass 171 */ 172 public abstract 173 ImageOutputStream createOutputStreamInstance(Object output, 174 boolean useCache, 175 File cacheDir) 176 throws IOException; 177 178 /** 179 * Returns an instance of the {@code ImageOutputStream} 180 * implementation associated with this service provider. A cache 181 * file will be created in the system-dependent default 182 * temporary-file directory, if needed. 183 * 184 * @param output an object of the class type returned by 185 * {@code getOutputClass}. 186 * 187 * @return an {@code ImageOutputStream} instance. 188 * 189 * @exception IllegalArgumentException if {@code output} is 190 * not an instance of the correct class or is {@code null}. 191 * @exception IOException if a cache file is needed but cannot be 192 * created. 193 * 194 * @see #getOutputClass() 195 */ 196 public ImageOutputStream createOutputStreamInstance(Object output) 197 throws IOException { 198 return createOutputStreamInstance(output, true, null); 199 } 200} 201