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