Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.imageio.spi
Class ImageInputStreamSpi

    java.lang.Object
      javax.imageio.spi.IIOServiceProvider
          javax.imageio.spi.ImageInputStreamSpi

All Implemented Interfaces:
  RegisterableService

    public abstract class ImageInputStreamSpi

extends IIOServiceProvider

The service provider interface (SPI) for `ImageInputStream`s. For more information on service provider interfaces, see the class comment for the `IIORegistry` class.

This interface allows arbitrary objects to be "wrapped" by instances of `ImageInputStream`. For example, a particular `ImageInputStreamSpi` might allow a generic `InputStream` to be used as an input source; another might take input from a `URL`.

By treating the creation of `ImageInputStream`s as a pluggable service, it becomes possible to handle future input sources without changing the API. Also, high-performance implementations of `ImageInputStream` (for example, native implementations for a particular platform) can be installed and used transparently by applications.

See Also:
  `IIORegistry`, `ImageInputStream`

Field Summary
`protected Class<?>` | `inputClass` A `Class` object indicating the legal object type for use by the `createInputStreamInstance` method.

Fields inherited from class javax.imageio.spi.IIOServiceProvider
`vendorName, version`

Constructor Summary
`protected` | `ImageInputStreamSpi()` Constructs a blank `ImageInputStreamSpi`.
`` | `ImageInputStreamSpi(String vendorName, String version, Class<?> inputClass)` Constructs an `ImageInputStreamSpi` with a given set of values.

Method Summary
`boolean` | `canUseCacheFile()` Returns `true` if the `ImageInputStream` implementation associated with this service provider can optionally make use of a cache file for improved performance and/or memory footrprint.
`ImageInputStream` | `createInputStreamInstance(Object input)` Returns an instance of the `ImageInputStream` implementation associated with this service provider.
`abstract ImageInputStream` | `createInputStreamInstance(Object input, boolean useCache, File cacheDir)` Returns an instance of the `ImageInputStream` implementation associated with this service provider.
`Class<?>` | `getInputClass()` Returns a `Class` object representing the class or interface type that must be implemented by an input source in order to be "wrapped" in an `ImageInputStream` via the `createInputStreamInstance` method.
`boolean` | `needsCacheFile()` Returns `true` if the `ImageInputStream` implementation associated with this service provider requires the use of a cache `File`.

Methods inherited from class javax.imageio.spi.IIOServiceProvider
`getDescription, getVendorName, getVersion, onDeregistration, onRegistration`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### inputClass

    protected Class<?> inputClass

  A `Class` object indicating the legal object type for use by the `createInputStreamInstance` method.

Constructor Detail

### ImageInputStreamSpi

    protected ImageInputStreamSpi()

  Constructs a blank `ImageInputStreamSpi`. It is up to the subclass to initialize instance variables and/or override method implementations in order to provide working versions of all methods.

### ImageInputStreamSpi

    public ImageInputStreamSpi(String vendorName,
                               String version,
                               Class<?> inputClass)

  Constructs an `ImageInputStreamSpi` with a given set of values.

  Parameters:
    `vendorName` - the vendor name.
    `version` - a version identifier.
    `inputClass` - a `Class` object indicating the legal object type for use by the `createInputStreamInstance` method.
  Throws:
    `IllegalArgumentException` - if `vendorName` is `null`.
    `IllegalArgumentException` - if `version` is `null`.

Method Detail

### getInputClass

    public Class<?> getInputClass()

  Returns a `Class` object representing the class or interface type that must be implemented by an input source in order to be "wrapped" in an `ImageInputStream` via the `createInputStreamInstance` method.

  Typical return values might include `InputStream.class` or `URL.class`, but any class may be used.

  Returns:
    a `Class` variable.
  See Also:
    `createInputStreamInstance(Object, boolean, File)`

### canUseCacheFile

    public boolean canUseCacheFile()

  Returns `true` if the `ImageInputStream` implementation associated with this service provider can optionally make use of a cache file for improved performance and/or memory footrprint. If `false`, the value of the `useCache` argument to `createInputStreamInstance` will be ignored.

  The default implementation returns `false`.

  Returns:
    `true` if a cache file can be used by the input streams created by this service provider.

### needsCacheFile

    public boolean needsCacheFile()

  Returns `true` if the `ImageInputStream` implementation associated with this service provider requires the use of a cache `File`. If `true`, the value of the `useCache` argument to `createInputStreamInstance` will be ignored.

  The default implementation returns `false`.

  Returns:
    `true` if a cache file is needed by the input streams created by this service provider.

### createInputStreamInstance

    public abstract ImageInputStream createInputStreamInstance(Object input,
                                                               boolean useCache,
                                                               File cacheDir)
                                                        throws IOException

  Returns an instance of the `ImageInputStream` implementation associated with this service provider. If the use of a cache file is optional, the `useCache` parameter will be consulted. Where a cache is required, or not applicable, the value of `useCache` will be ignored.

  Parameters:
    `input` - an object of the class type returned by `getInputClass`.
    `useCache` - a `boolean` indicating whether a cache file should be used, in cases where it is optional.
    `cacheDir` - a `File` indicating where the cache file should be created, or `null` to use the system directory.
  Returns:
    an `ImageInputStream` instance.
  Throws:
    `IllegalArgumentException` - if `input` is not an instance of the correct class or is `null`.
    `IllegalArgumentException` - if a cache file is needed but `cacheDir` is non-`null` and is not a directory.
    `IOException` - if a cache file is needed but cannot be created.
  See Also:
    `getInputClass()`, `canUseCacheFile()`, `needsCacheFile()`

### createInputStreamInstance

    public ImageInputStream createInputStreamInstance(Object input)
                                               throws IOException

  Returns an instance of the `ImageInputStream` implementation associated with this service provider. A cache file will be created in the system-dependent default temporary-file directory, if needed.

  Parameters:
    `input` - an object of the class type returned by `getInputClass`.
  Returns:
    an `ImageInputStream` instance.
  Throws:
    `IllegalArgumentException` - if `input` is not an instance of the correct class or is `null`.
    `IOException` - if a cache file is needed but cannot be created.
  See Also:
    `getInputClass()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.