001 /*
002 * Copyright 2000-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.imageio.spi;
027
028 import java.util.Locale;
029 import javax.imageio.spi.RegisterableService;
030 import javax.imageio.spi.ServiceRegistry;
031
032 /**
033 * A superinterface for functionality common to all Image I/O service
034 * provider interfaces (SPIs). For more information on service
035 * provider classes, see the class comment for the
036 * <code>IIORegistry</code> class.
037 *
038 * @see IIORegistry
039 * @see javax.imageio.spi.ImageReaderSpi
040 * @see javax.imageio.spi.ImageWriterSpi
041 * @see javax.imageio.spi.ImageTranscoderSpi
042 * @see javax.imageio.spi.ImageInputStreamSpi
043 *
044 * @version 0.5
045 */
046 public abstract class IIOServiceProvider implements RegisterableService {
047
048 /**
049 * A <code>String</code> to be returned from
050 * <code>getVendorName</code>, initially <code>null</code>.
051 * Constructors should set this to a non-<code>null</code> value.
052 */
053 protected String vendorName;
054
055 /**
056 * A <code>String</code> to be returned from
057 * <code>getVersion</code>, initially null. Constructors should
058 * set this to a non-<code>null</code> value.
059 */
060 protected String version;
061
062 /**
063 * Constructs an <code>IIOServiceProvider</code> with a given
064 * vendor name and version identifier.
065 *
066 * @param vendorName the vendor name.
067 * @param version a version identifier.
068 *
069 * @exception IllegalArgumentException if <code>vendorName</code>
070 * is <code>null</code>.
071 * @exception IllegalArgumentException if <code>version</code>
072 * is <code>null</code>.
073 */
074 public IIOServiceProvider(String vendorName, String version) {
075 if (vendorName == null) {
076 throw new IllegalArgumentException("vendorName == null!");
077 }
078 if (version == null) {
079 throw new IllegalArgumentException("version == null!");
080 }
081 this .vendorName = vendorName;
082 this .version = version;
083 }
084
085 /**
086 * Constructs a blank <code>IIOServiceProvider</code>. It is up
087 * to the subclass to initialize instance variables and/or
088 * override method implementations in order to ensure that the
089 * <code>getVendorName</code> and <code>getVersion</code> methods
090 * will return non-<code>null</code> values.
091 */
092 public IIOServiceProvider() {
093 }
094
095 /**
096 * A callback that will be called exactly once after the Spi class
097 * has been instantiated and registered in a
098 * <code>ServiceRegistry</code>. This may be used to verify that
099 * 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 /**
115 * A callback that will be whenever the Spi class has been
116 * deregistered from a <code>ServiceRegistry</code>.
117 *
118 * <p> Only the registry should call this method.
119 *
120 * <p> The default implementation does nothing.
121 *
122 * @see ServiceRegistry#deregisterServiceProvider(Object provider)
123 */
124 public void onDeregistration(ServiceRegistry registry,
125 Class<?> category) {
126 }
127
128 /**
129 * Returns the name of the vendor responsible for creating this
130 * service provider and its associated implementation. Because
131 * the vendor name may be used to select a service provider,
132 * it is not localized.
133 *
134 * <p> The default implementation returns the value of the
135 * <code>vendorName</code> instance variable.
136 *
137 * @return a non-<code>null</code> <code>String</code> containing
138 * the name of the vendor.
139 */
140 public String getVendorName() {
141 return vendorName;
142 }
143
144 /**
145 * Returns a string describing the version
146 * number of this service provider and its associated
147 * implementation. Because the version may be used by transcoders
148 * to identify the service providers they understand, this method
149 * is not localized.
150 *
151 * <p> The default implementation returns the value of the
152 * <code>version</code> instance variable.
153 *
154 * @return a non-<code>null</code> <code>String</code> containing
155 * the version of this service provider.
156 */
157 public String getVersion() {
158 return version;
159 }
160
161 /**
162 * Returns a brief, human-readable description of this service
163 * provider and its associated implementation. The resulting
164 * string should be localized for the supplied
165 * <code>Locale</code>, if possible.
166 *
167 * @param locale a <code>Locale</code> for which the return value
168 * should be localized.
169 *
170 * @return a <code>String</code> containing a description of this
171 * service provider.
172 */
173 public abstract String getDescription(Locale locale);
174 }
|