< prev index next >

src/java.desktop/share/classes/javax/imageio/spi/IIOServiceProvider.java

Print this page




  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 
  26 package javax.imageio.spi;
  27 
  28 import java.util.Locale;
  29 import javax.imageio.spi.RegisterableService;
  30 import javax.imageio.spi.ServiceRegistry;
  31 
  32 /**
  33  * A superinterface for functionality common to all Image I/O service
  34  * provider interfaces (SPIs).  For more information on service
  35  * provider classes, see the class comment for the
  36  * <code>IIORegistry</code> class.
  37  *
  38  * @see IIORegistry
  39  * @see javax.imageio.spi.ImageReaderSpi
  40  * @see javax.imageio.spi.ImageWriterSpi
  41  * @see javax.imageio.spi.ImageTranscoderSpi
  42  * @see javax.imageio.spi.ImageInputStreamSpi
  43  * @see javax.imageio.spi.ImageOutputStreamSpi
  44  */
  45 public abstract class IIOServiceProvider implements RegisterableService {
  46 
  47     /**
  48      * A <code>String</code> to be returned from
  49      * <code>getVendorName</code>, initially <code>null</code>.
  50      * Constructors should set this to a non-<code>null</code> value.
  51      */
  52     protected String vendorName;
  53 
  54     /**
  55      * A <code>String</code> to be returned from
  56      * <code>getVersion</code>, initially null.  Constructors should
  57      * set this to a non-<code>null</code> value.
  58      */
  59     protected String version;
  60 
  61     /**
  62      * Constructs an <code>IIOServiceProvider</code> with a given
  63      * vendor name and version identifier.
  64      *
  65      * @param vendorName the vendor name.
  66      * @param version a version identifier.
  67      *
  68      * @exception IllegalArgumentException if <code>vendorName</code>
  69      * is <code>null</code>.
  70      * @exception IllegalArgumentException if <code>version</code>
  71      * is <code>null</code>.
  72      */
  73     public IIOServiceProvider(String vendorName,
  74                               String version) {
  75         if (vendorName == null) {
  76             throw new IllegalArgumentException("vendorName == null!");
  77         }
  78         if (version == null) {
  79             throw new IllegalArgumentException("version == null!");
  80         }
  81         this.vendorName = vendorName;
  82         this.version = version;
  83     }
  84 
  85     /**
  86      * Constructs a blank <code>IIOServiceProvider</code>.  It is up
  87      * to the subclass to initialize instance variables and/or
  88      * override method implementations in order to ensure that the
  89      * <code>getVendorName</code> and <code>getVersion</code> methods
  90      * will return non-<code>null</code> values.
  91      */
  92     public IIOServiceProvider() {
  93     }
  94 
  95     /**
  96      * A callback that will be called exactly once after the Spi class
  97      * has been instantiated and registered in a
  98      * <code>ServiceRegistry</code>.  This may be used to verify that
  99      * the environment is suitable for this service, for example that
 100      * native libraries can be loaded.  If the service cannot function
 101      * in the environment where it finds itself, it should deregister
 102      * itself from the registry.
 103      *
 104      * <p> Only the registry should call this method.
 105      *
 106      * <p> The default implementation does nothing.
 107      *
 108      * @see ServiceRegistry#registerServiceProvider(Object provider)
 109      */
 110     public void onRegistration(ServiceRegistry registry,
 111                                Class<?> category) {}
 112 
 113     /**
 114      * A callback that will be whenever the Spi class has been
 115      * deregistered from a <code>ServiceRegistry</code>.
 116      *
 117      * <p> Only the registry should call this method.
 118      *
 119      * <p> The default implementation does nothing.
 120      *
 121      * @see ServiceRegistry#deregisterServiceProvider(Object provider)
 122      */
 123     public void onDeregistration(ServiceRegistry registry,
 124                                  Class<?> category) {}
 125 
 126     /**
 127      * Returns the name of the vendor responsible for creating this
 128      * service provider and its associated implementation.  Because
 129      * the vendor name may be used to select a service provider,
 130      * it is not localized.
 131      *
 132      * <p> The default implementation returns the value of the
 133      * <code>vendorName</code> instance variable.
 134      *
 135      * @return a non-<code>null</code> <code>String</code> containing
 136      * the name of the vendor.
 137      */
 138     public String getVendorName() {
 139         return vendorName;
 140     }
 141 
 142     /**
 143      * Returns a string describing the version
 144      * number of this service provider and its associated
 145      * implementation.  Because the version may be used by transcoders
 146      * to identify the service providers they understand, this method
 147      * is not localized.
 148      *
 149      * <p> The default implementation returns the value of the
 150      * <code>version</code> instance variable.
 151      *
 152      * @return a non-<code>null</code> <code>String</code> containing
 153      * the version of this service provider.
 154      */
 155     public String getVersion() {
 156         return version;
 157     }
 158 
 159     /**
 160      * Returns a brief, human-readable description of this service
 161      * provider and its associated implementation.  The resulting
 162      * string should be localized for the supplied
 163      * <code>Locale</code>, if possible.
 164      *
 165      * @param locale a <code>Locale</code> for which the return value
 166      * should be localized.
 167      *
 168      * @return a <code>String</code> containing a description of this
 169      * service provider.
 170      */
 171     public abstract String getDescription(Locale locale);
 172 }


  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 
  26 package javax.imageio.spi;
  27 
  28 import java.util.Locale;
  29 import javax.imageio.spi.RegisterableService;
  30 import javax.imageio.spi.ServiceRegistry;
  31 
  32 /**
  33  * A superinterface for functionality common to all Image I/O service
  34  * provider interfaces (SPIs).  For more information on service
  35  * provider classes, see the class comment for the
  36  * {@code IIORegistry} class.
  37  *
  38  * @see IIORegistry
  39  * @see javax.imageio.spi.ImageReaderSpi
  40  * @see javax.imageio.spi.ImageWriterSpi
  41  * @see javax.imageio.spi.ImageTranscoderSpi
  42  * @see javax.imageio.spi.ImageInputStreamSpi
  43  * @see javax.imageio.spi.ImageOutputStreamSpi
  44  */
  45 public abstract class IIOServiceProvider implements RegisterableService {
  46 
  47     /**
  48      * A {@code String} to be returned from
  49      * {@code getVendorName}, initially {@code null}.
  50      * Constructors should set this to a non-{@code null} value.
  51      */
  52     protected String vendorName;
  53 
  54     /**
  55      * A {@code String} to be returned from
  56      * {@code getVersion}, initially null.  Constructors should
  57      * set this to a non-{@code null} value.
  58      */
  59     protected String version;
  60 
  61     /**
  62      * Constructs an {@code IIOServiceProvider} with a given
  63      * vendor name and version identifier.
  64      *
  65      * @param vendorName the vendor name.
  66      * @param version a version identifier.
  67      *
  68      * @exception IllegalArgumentException if {@code vendorName}
  69      * is {@code null}.
  70      * @exception IllegalArgumentException if {@code version}
  71      * is {@code null}.
  72      */
  73     public IIOServiceProvider(String vendorName,
  74                               String version) {
  75         if (vendorName == null) {
  76             throw new IllegalArgumentException("vendorName == null!");
  77         }
  78         if (version == null) {
  79             throw new IllegalArgumentException("version == null!");
  80         }
  81         this.vendorName = vendorName;
  82         this.version = version;
  83     }
  84 
  85     /**
  86      * Constructs a blank {@code IIOServiceProvider}.  It is up
  87      * to the subclass to initialize instance variables and/or
  88      * override method implementations in order to ensure that the
  89      * {@code getVendorName} and {@code getVersion} methods
  90      * will return non-{@code null} values.
  91      */
  92     public IIOServiceProvider() {
  93     }
  94 
  95     /**
  96      * A callback that will be called exactly once after the Spi class
  97      * has been instantiated and registered in a
  98      * {@code ServiceRegistry}.  This may be used to verify that
  99      * the environment is suitable for this service, for example that
 100      * native libraries can be loaded.  If the service cannot function
 101      * in the environment where it finds itself, it should deregister
 102      * itself from the registry.
 103      *
 104      * <p> Only the registry should call this method.
 105      *
 106      * <p> The default implementation does nothing.
 107      *
 108      * @see ServiceRegistry#registerServiceProvider(Object provider)
 109      */
 110     public void onRegistration(ServiceRegistry registry,
 111                                Class<?> category) {}
 112 
 113     /**
 114      * A callback that will be whenever the Spi class has been
 115      * deregistered from a {@code ServiceRegistry}.
 116      *
 117      * <p> Only the registry should call this method.
 118      *
 119      * <p> The default implementation does nothing.
 120      *
 121      * @see ServiceRegistry#deregisterServiceProvider(Object provider)
 122      */
 123     public void onDeregistration(ServiceRegistry registry,
 124                                  Class<?> category) {}
 125 
 126     /**
 127      * Returns the name of the vendor responsible for creating this
 128      * service provider and its associated implementation.  Because
 129      * the vendor name may be used to select a service provider,
 130      * it is not localized.
 131      *
 132      * <p> The default implementation returns the value of the
 133      * {@code vendorName} instance variable.
 134      *
 135      * @return a non-{@code null String} containing
 136      * the name of the vendor.
 137      */
 138     public String getVendorName() {
 139         return vendorName;
 140     }
 141 
 142     /**
 143      * Returns a string describing the version
 144      * number of this service provider and its associated
 145      * implementation.  Because the version may be used by transcoders
 146      * to identify the service providers they understand, this method
 147      * is not localized.
 148      *
 149      * <p> The default implementation returns the value of the
 150      * {@code version} instance variable.
 151      *
 152      * @return a non-{@code null String} containing
 153      * the version of this service provider.
 154      */
 155     public String getVersion() {
 156         return version;
 157     }
 158 
 159     /**
 160      * Returns a brief, human-readable description of this service
 161      * provider and its associated implementation.  The resulting
 162      * string should be localized for the supplied
 163      * {@code Locale}, if possible.
 164      *
 165      * @param locale a {@code Locale} for which the return value
 166      * should be localized.
 167      *
 168      * @return a {@code String} containing a description of this
 169      * service provider.
 170      */
 171     public abstract String getDescription(Locale locale);
 172 }
< prev index next >