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 
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      */
IIOServiceProvider(String vendorName, String version)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      */
IIOServiceProvider()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      */
onRegistration(ServiceRegistry registry, Class<?> category)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      */
onDeregistration(ServiceRegistry registry, Class<?> category)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      */
getVendorName()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      */
getVersion()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      */
getDescription(Locale locale)171     public abstract String getDescription(Locale locale);
172 }
173