89 * <tr>
90 * <th>value</th>
91 * <th>language</th>
92 * </tr>
93 * </thead>
94 * <tbody>
95 * <tr>
96 * <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td>
97 * <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>
98 * </tr>
99 * <tr>
100 * <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td>
101 * <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>
102 * </tr>
103 * </tbody>
104 * </table>
105 *
106 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
107 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
108 *
109 * @since 1.5
110 */
111 public abstract class SchemaFactory {
112
113 private static SecuritySupport ss = new SecuritySupport();
114
115 /**
116 * <p>Constructor for derived classes.</p>
117 *
118 * <p>The constructor does nothing.</p>
119 *
120 * <p>Derived classes must create {@link SchemaFactory} objects that have
121 * <code>null</code> {@link ErrorHandler} and
122 * <code>null</code> {@link LSResourceResolver}.</p>
123 */
124 protected SchemaFactory() {
125 }
126
127 /**
128 * <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified
130 *
131 * <p>To find a <code>SchemaFactory</code> object for a given schema language,
132 * this method looks the following places in the following order
133 * where "the class loader" refers to the context class loader:</p>
134 * <ol>
135 * <li>
136 * If the system property
137 * <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code>
138 * is present (where <i>schemaLanguage</i> is the parameter
139 * to this method), then its value is read
140 * as a class name. The method will try to
141 * create a new instance of this class by using the class loader,
142 * and returns it if it is successfully created.
143 * </li>
144 * <li>
145 * <code>$java.home/lib/jaxp.properties</code> is read and
146 * the value associated with the key being the system property above
147 * is looked for. If present, the value is processed just like above.
148 * </li>
149 * <li>
150 * <p>The class loader is asked for service provider provider-configuration files matching
151 * <code>javax.xml.validation.SchemaFactory</code> in the resource directory META-INF/services.
152 * See the JAR File Specification for file format and parsing rules.
153 * Each potential service provider is required to implement the method:</p>
154 * <pre>
155 * {@link #isSchemaLanguageSupported(String schemaLanguage)}
156 * </pre>
157 * The first service provider found in class loader order that supports the specified schema language is returned.
158 * </li>
159 * <li>
160 * Platform default <code>SchemaFactory</code> is located
161 * in a implementation specific way. There must be a platform default
162 * <code>SchemaFactory</code> for W3C XML Schema.
163 * </li>
164 * </ol>
165 *
166 * <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p>
167 *
168 * <p><strong>Tip for Trouble-shooting:</strong></p>
169 * <p>See {@link java.util.Properties#load(java.io.InputStream)} for
170 * exactly how a property file is parsed. In particular, colons ':'
171 * need to be escaped in a property file, so make sure schema language
172 * URIs are properly escaped in it. For example:</p>
173 * <pre>
174 * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
175 * </pre>
176 *
177 * @param schemaLanguage
178 * Specifies the schema language which the returned
179 * SchemaFactory will understand. See
180 * <a href="#schemaLanguage">the list of available
181 * schema languages</a> for the possible values.
182 *
183 * @return New instance of a <code>SchemaFactory</code>
184 *
185 * @throws IllegalArgumentException
186 * If no implementation of the schema language is available.
187 * @throws NullPointerException
188 * If the <code>schemaLanguage</code> parameter is null.
189 *
190 * @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
191 */
192 public static final SchemaFactory newInstance(String schemaLanguage) {
193 ClassLoader cl;
194 cl = ss.getContextClassLoader();
195
196 if (cl == null) {
197 //cl = ClassLoader.getSystemClassLoader();
198 //use the current class loader
199 cl = SchemaFactory.class.getClassLoader();
200 }
201
202 SchemaFactory f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage);
203 if (f == null) {
204 throw new IllegalArgumentException(
205 "No SchemaFactory"
206 + " that implements the schema language specified by: " + schemaLanguage
207 + " could be loaded");
208 }
209 return f;
210 }
211
212 /**
213 * <p>Obtain a new instance of a <code>SchemaFactory</code> from class name. <code>SchemaFactory</code>
214 * is returned if specified factory class name supports the specified schema language.
215 * This function is useful when there are multiple providers in the classpath.
216 * It gives more control to the application as it can specify which provider
217 * should be loaded.</p>
218 *
219 * <h2>Tip for Trouble-shooting</h2>
220 * <p>Setting the <code>jaxp.debug</code> system property will cause
221 * this method to print a lot of debug messages
222 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
|
89 * <tr>
90 * <th>value</th>
91 * <th>language</th>
92 * </tr>
93 * </thead>
94 * <tbody>
95 * <tr>
96 * <td>{@link javax.xml.XMLConstants#W3C_XML_SCHEMA_NS_URI} ("<code>http://www.w3.org/2001/XMLSchema</code>")</td>
97 * <td><a href="http://www.w3.org/TR/xmlschema-1">W3C XML Schema 1.0</a></td>
98 * </tr>
99 * <tr>
100 * <td>{@link javax.xml.XMLConstants#RELAXNG_NS_URI} ("<code>http://relaxng.org/ns/structure/1.0</code>")</td>
101 * <td><a href="http://www.relaxng.org/">RELAX NG 1.0</a></td>
102 * </tr>
103 * </tbody>
104 * </table>
105 *
106 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
107 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
108 *
109 * @version $Revision: 1.10 $, $Date: 2010-11-01 04:36:13 $
110 * @since 1.5
111 */
112 public abstract class SchemaFactory {
113
114 private static SecuritySupport ss = new SecuritySupport();
115
116 /**
117 * <p>Constructor for derived classes.</p>
118 *
119 * <p>The constructor does nothing.</p>
120 *
121 * <p>Derived classes must create {@link SchemaFactory} objects that have
122 * <code>null</code> {@link ErrorHandler} and
123 * <code>null</code> {@link LSResourceResolver}.</p>
124 */
125 protected SchemaFactory() {
126 }
127
128 /**
129 * <p>Lookup an implementation of the <code>SchemaFactory</code> that supports the specified
131 *
132 * <p>To find a <code>SchemaFactory</code> object for a given schema language,
133 * this method looks the following places in the following order
134 * where "the class loader" refers to the context class loader:</p>
135 * <ol>
136 * <li>
137 * If the system property
138 * <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code>
139 * is present (where <i>schemaLanguage</i> is the parameter
140 * to this method), then its value is read
141 * as a class name. The method will try to
142 * create a new instance of this class by using the class loader,
143 * and returns it if it is successfully created.
144 * </li>
145 * <li>
146 * <code>$java.home/lib/jaxp.properties</code> is read and
147 * the value associated with the key being the system property above
148 * is looked for. If present, the value is processed just like above.
149 * </li>
150 * <li>
151 * <p>Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
152 * to locate and load an implementation of the service.
153 * Each potential service provider is required to implement the method:</p>
154 * <pre>
155 * {@link #isSchemaLanguageSupported(String schemaLanguage)}
156 * </pre>
157 * A service provider is deemed as valid if it supports the specified schema language.
158 *
159 * <p>In case of multiple providers, the first non-default implementation shall be
160 * instantiated and returned. The default implementation is returned if it is
161 * the only one found by the service loader.</p>
162 * <p>
163 * If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown,
164 * the error will be wrapped in a {@link javax.xml.validation.FactoryConfigurationError}.</p>
165 * </li>
166 * <li>
167 * Platform default <code>SchemaFactory</code> is located
168 * in a implementation specific way. There must be a platform default
169 * <code>SchemaFactory</code> for W3C XML Schema.
170 * </li>
171 * </ol>
172 *
173 * <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p>
174 *
175 * <p><strong>Tip for Trouble-shooting:</strong></p>
176 * <p>See {@link java.util.Properties#load(java.io.InputStream)} for
177 * exactly how a property file is parsed. In particular, colons ':'
178 * need to be escaped in a property file, so make sure schema language
179 * URIs are properly escaped in it. For example:</p>
180 * <pre>
181 * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
182 * </pre>
183 *
184 * @param schemaLanguage
185 * Specifies the schema language which the returned
186 * SchemaFactory will understand. See
187 * <a href="#schemaLanguage">the list of available
188 * schema languages</a> for the possible values.
189 *
190 * @return New instance of a <code>SchemaFactory</code>
191 *
192 * @throws IllegalArgumentException
193 * If no implementation of the schema language is available.
194 * @throws NullPointerException
195 * If the <code>schemaLanguage</code> parameter is null.
196 * @throws FactoryConfigurationError
197 * If a misconfigured provider is encountered
198 *
199 * @see #newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)
200 */
201 public static final SchemaFactory newInstance(String schemaLanguage)
202 {
203 ClassLoader cl;
204 cl = ss.getContextClassLoader();
205
206 if (cl == null) {
207 //cl = ClassLoader.getSystemClassLoader();
208 //use the current class loader
209 cl = SchemaFactory.class.getClassLoader();
210 }
211
212 SchemaFactory f = null;
213 try {
214 f = new SchemaFactoryFinder(cl).newFactory(schemaLanguage);
215 } catch (FactoryConfigurationError e) {
216 throw e;
217 }
218 if (f == null) {
219 throw new IllegalArgumentException(
220 "No SchemaFactory"
221 + " that implements the schema language specified by: " + schemaLanguage
222 + " could be loaded");
223 }
224 return f;
225 }
226
227 /**
228 * <p>Obtain a new instance of a <code>SchemaFactory</code> from class name. <code>SchemaFactory</code>
229 * is returned if specified factory class name supports the specified schema language.
230 * This function is useful when there are multiple providers in the classpath.
231 * It gives more control to the application as it can specify which provider
232 * should be loaded.</p>
233 *
234 * <h2>Tip for Trouble-shooting</h2>
235 * <p>Setting the <code>jaxp.debug</code> system property will cause
236 * this method to print a lot of debug messages
237 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
|