author | mkos |
Fri, 05 Jun 2015 15:05:55 +0200 | |
changeset 31109 | a542f8dcbbf8 |
parent 29839 | 6d5d546e953b |
child 31501 | 1b48499c9e1c |
permissions | -rw-r--r-- |
12009 | 1 |
/* |
28887
88470f768658
8071585: Update JAX-WS RI integration to latest version (2.2.11-b150127.1410)
aefimov
parents:
25871
diff
changeset
|
2 |
* Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved. |
12009 | 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.xml.bind; |
|
27 |
||
28 |
import org.w3c.dom.Node; |
|
29 |
||
30 |
import java.util.Collections; |
|
31 |
import java.util.Map; |
|
32 |
import java.util.Properties; |
|
33 |
import java.io.IOException; |
|
34 |
import java.io.InputStream; |
|
35 |
||
36 |
/** |
|
37 |
* <p> |
|
38 |
* The <tt>JAXBContext</tt> class provides the client's entry point to the |
|
39 |
* JAXB API. It provides an abstraction for managing the XML/Java binding |
|
40 |
* information necessary to implement the JAXB binding framework operations: |
|
41 |
* unmarshal, marshal and validate. |
|
42 |
* |
|
43 |
* <p>A client application normally obtains new instances of this class using |
|
44 |
* one of these two styles for newInstance methods, although there are other |
|
45 |
* specialized forms of the method available: |
|
46 |
* |
|
47 |
* <ul> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
48 |
* <li>{@link #newInstance(String, ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
49 |
* The JAXBContext instance is initialized from a list of colon |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
50 |
* separated Java package names. Each java package contains |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
51 |
* JAXB mapped classes, schema-derived classes and/or user annotated |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
52 |
* classes. Additionally, the java package may contain JAXB package annotations |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
53 |
* that must be processed. (see JLS, Section 7.4.1 "Named Packages"). |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
54 |
* </li> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
55 |
* <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
56 |
* The JAXBContext instance is initialized with class(es) |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
57 |
* passed as parameter(s) and classes that are statically reachable from |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
58 |
* these class(es). See {@link #newInstance(Class...)} for details. |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
59 |
* </li> |
12009 | 60 |
* </ul> |
61 |
* |
|
62 |
* <p><i> |
|
63 |
* The following JAXB 1.0 requirement is only required for schema to |
|
64 |
* java interface/implementation binding. It does not apply to JAXB annotated |
|
65 |
* classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in |
|
66 |
* each package containing schema derived classes. The property file must |
|
67 |
* contain a property named <tt>javax.xml.bind.context.factory</tt> whose |
|
68 |
* value is the name of the class that implements the <tt>createContext</tt> |
|
69 |
* APIs.</i> |
|
70 |
* |
|
71 |
* <p><i> |
|
72 |
* The class supplied by the provider does not have to be assignable to |
|
73 |
* <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that |
|
74 |
* implements the <tt>createContext</tt> APIs.</i> |
|
75 |
* |
|
76 |
* <p><i> |
|
77 |
* In addition, the provider must call the |
|
78 |
* {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface) |
|
79 |
* DatatypeConverter.setDatatypeConverter} api prior to any client |
|
80 |
* invocations of the marshal and unmarshal methods. This is necessary to |
|
81 |
* configure the datatype converter that will be used during these operations.</i> |
|
82 |
* |
|
83 |
* <a name="Unmarshalling"></a> |
|
84 |
* <h3>Unmarshalling</h3> |
|
85 |
* <p> |
|
86 |
* The {@link Unmarshaller} class provides the client application the ability |
|
87 |
* to convert XML data into a tree of Java content objects. |
|
88 |
* The unmarshal method allows for |
|
89 |
* any global XML element declared in the schema to be unmarshalled as |
|
90 |
* the root of an instance document. |
|
91 |
* Additionally, the unmarshal method allows for an unrecognized root element that |
|
92 |
* has an xsi:type attribute's value that references a type definition declared in |
|
93 |
* the schema to be unmarshalled as the root of an instance document. |
|
94 |
* The <tt>JAXBContext</tt> object |
|
95 |
* allows the merging of global elements and type definitions across a set of schemas (listed |
|
96 |
* in the <tt>contextPath</tt>). Since each schema in the schema set can belong |
|
97 |
* to distinct namespaces, the unification of schemas to an unmarshalling |
|
98 |
* context should be namespace independent. This means that a client |
|
99 |
* application is able to unmarshal XML documents that are instances of |
|
100 |
* any of the schemas listed in the <tt>contextPath</tt>. For example: |
|
101 |
* |
|
102 |
* <pre> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
103 |
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" ); |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
104 |
* Unmarshaller u = jc.createUnmarshaller(); |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
105 |
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
106 |
* BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
107 |
* BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath |
12009 | 108 |
* </pre> |
109 |
* |
|
110 |
* <p> |
|
111 |
* The client application may also generate Java content trees explicitly rather |
|
112 |
* than unmarshalling existing XML data. For all JAXB-annotated value classes, |
|
113 |
* an application can create content using constructors. |
|
114 |
* For schema-derived interface/implementation classes and for the |
|
115 |
* creation of elements that are not bound to a JAXB-annotated |
|
116 |
* class, an application needs to have access and knowledge about each of |
|
117 |
* the schema derived <tt> ObjectFactory</tt> classes that exist in each of |
|
118 |
* java packages contained in the <tt>contextPath</tt>. For each schema |
|
119 |
* derived java class, there is a static factory method that produces objects |
|
120 |
* of that type. For example, |
|
121 |
* assume that after compiling a schema, you have a package <tt>com.acme.foo</tt> |
|
122 |
* that contains a schema derived interface named <tt>PurchaseOrder</tt>. In |
|
123 |
* order to create objects of that type, the client application would use the |
|
124 |
* factory method like this: |
|
125 |
* |
|
126 |
* <pre> |
|
127 |
* com.acme.foo.PurchaseOrder po = |
|
128 |
* com.acme.foo.ObjectFactory.createPurchaseOrder(); |
|
129 |
* </pre> |
|
130 |
* |
|
131 |
* <p> |
|
132 |
* Once the client application has an instance of the the schema derived object, |
|
133 |
* it can use the mutator methods to set content on it. |
|
134 |
* |
|
135 |
* <p> |
|
136 |
* For more information on the generated <tt>ObjectFactory</tt> classes, see |
|
137 |
* Section 4.2 <i>Java Package</i> of the specification. |
|
138 |
* |
|
139 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
140 |
* <i>The provider must generate a class in each |
12009 | 141 |
* package that contains all of the necessary object factory methods for that |
142 |
* package named ObjectFactory as well as the static |
|
143 |
* <tt>newInstance( javaContentInterface )</tt> method</i> |
|
144 |
* |
|
145 |
* <h3>Marshalling</h3> |
|
146 |
* <p> |
|
147 |
* The {@link Marshaller} class provides the client application the ability |
|
148 |
* to convert a Java content tree back into XML data. There is no difference |
|
149 |
* between marshalling a content tree that is created manually using the factory |
|
150 |
* methods and marshalling a content tree that is the result an <tt>unmarshal |
|
151 |
* </tt> operation. Clients can marshal a java content tree back to XML data |
|
152 |
* to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>. The |
|
153 |
* marshalling process can alternatively produce SAX2 event streams to a |
|
154 |
* registered <tt>ContentHandler</tt> or produce a DOM Node object. |
|
155 |
* Client applications have control over the output encoding as well as |
|
156 |
* whether or not to marshal the XML data as a complete document or |
|
157 |
* as a fragment. |
|
158 |
* |
|
159 |
* <p> |
|
160 |
* Here is a simple example that unmarshals an XML document and then marshals |
|
161 |
* it back out: |
|
162 |
* |
|
163 |
* <pre> |
|
164 |
* JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); |
|
165 |
* |
|
166 |
* // unmarshal from foo.xml |
|
167 |
* Unmarshaller u = jc.createUnmarshaller(); |
|
168 |
* FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); |
|
169 |
* |
|
170 |
* // marshal to System.out |
|
171 |
* Marshaller m = jc.createMarshaller(); |
|
172 |
* m.marshal( fooObj, System.out ); |
|
173 |
* </pre> |
|
174 |
* |
|
175 |
* |
|
176 |
* <h3>Validation</h3> |
|
177 |
* <p> |
|
178 |
* Validation has been changed significantly since JAXB 1.0. The {@link Validator} |
|
179 |
* class has been deprecated and made optional. This means that you are advised |
|
180 |
* not to use this class and, in fact, it may not even be available depending on |
|
181 |
* your JAXB provider. JAXB 1.0 client applications that rely on <tt>Validator</tt> |
|
182 |
* will still work properly when deployed with the JAXB 1.0 runtime system. |
|
183 |
* |
|
184 |
* In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose |
|
185 |
* the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the |
|
186 |
* {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more |
|
187 |
* information. |
|
188 |
* |
|
189 |
* |
|
190 |
* <h3>JAXB Runtime Binding Framework Compatibility</h3> |
|
191 |
* <p> |
|
192 |
* The following JAXB 1.0 restriction only applies to binding schema to |
|
193 |
* interfaces/implementation classes. |
|
194 |
* Since this binding does not require a common runtime system, a JAXB |
|
195 |
* client application must not attempt to mix runtime objects (<tt>JAXBContext, |
|
196 |
* Marshaller</tt>, etc. ) from different providers. This does not |
|
197 |
* mean that the client application isn't portable, it simply means that a |
|
198 |
* client has to use a runtime system provided by the same provider that was |
|
199 |
* used to compile the schema. |
|
200 |
* |
|
201 |
* |
|
202 |
* <h3>Discovery of JAXB implementation</h3> |
|
203 |
* <p> |
|
204 |
* When one of the <tt>newInstance</tt> methods is called, a JAXB implementation is discovered |
|
205 |
* by the following steps. |
|
206 |
* |
|
207 |
* <ol> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
208 |
* |
12009 | 209 |
* <li> |
210 |
* For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified, |
|
211 |
* <tt>jaxb.properties</tt> file is looked up in its package, by using the associated classloader — |
|
212 |
* this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package |
|
16791 | 213 |
* the specified {@link ClassLoader}. |
12009 | 214 |
* |
215 |
* <p> |
|
216 |
* If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and |
|
217 |
* the value of the {@link #JAXB_CONTEXT_FACTORY} key will be assumed to be the provider factory class. |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
218 |
* This class is then loaded by the associated class loader discussed above. |
12009 | 219 |
* |
220 |
* <p> |
|
221 |
* This phase of the look up allows some packages to force the use of a certain JAXB implementation. |
|
222 |
* (For example, perhaps the schema compiler has generated some vendor extension in the code.) |
|
223 |
* |
|
224 |
* <li> |
|
225 |
* If the system property {@link #JAXB_CONTEXT_FACTORY} exists, then its value is assumed to be the provider |
|
226 |
* factory class. This phase of the look up enables per-JVM override of the JAXB implementation. |
|
227 |
* |
|
228 |
* <li> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
229 |
* Provider of {@link javax.xml.bind.JAXBContextFactory} is loaded using the service-provider loading |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
230 |
* facilities, defined by the {@link java.util.ServiceLoader} class, to attempt |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
231 |
* to locate and load an implementation of the service using the {@linkplain |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
232 |
* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: the service-provider loading facility |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
233 |
* will use the {@linkplain java.lang.Thread#getContextClassLoader() current thread's context class loader} |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
234 |
* to attempt to load the context factory. If the context class loader is null, the |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
235 |
* {@linkplain ClassLoader#getSystemClassLoader() system class loader} will be used. |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
236 |
* <br> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
237 |
* In case of {@link java.util.ServiceConfigurationError service |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
238 |
* configuration error} a {@link javax.xml.bind.JAXBException} will be thrown. |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
239 |
* </li> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
240 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
241 |
* <li> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
242 |
* Look for resource {@code /META-INF/services/javax.xml.bind.JAXBContext} using provided class loader. |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
243 |
* Methods without class loader parameter use {@code Thread.currentThread().getContextClassLoader()}. |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
244 |
* If such a resource exists, its content is assumed to be the provider factory class and must supply |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
245 |
* an implementation class containing the following method signatures: |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
246 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
247 |
* <pre> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
248 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
249 |
* public static JAXBContext createContext( |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
250 |
* String contextPath, |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
251 |
* ClassLoader classLoader, |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
252 |
* Map<String,Object> properties throws JAXBException |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
253 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
254 |
* public static JAXBContext createContext( |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
255 |
* Class[] classes, |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
256 |
* Map<String,Object> properties ) throws JAXBException |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
257 |
* </pre> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
258 |
* This configuration method is deprecated. |
12009 | 259 |
* |
260 |
* <li> |
|
261 |
* Finally, if all the steps above fail, then the rest of the look up is unspecified. That said, |
|
262 |
* the recommended behavior is to simply look for some hard-coded platform default JAXB implementation. |
|
263 |
* This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort. |
|
264 |
* </ol> |
|
265 |
* |
|
266 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
267 |
* Once the provider factory class {@link javax.xml.bind.JAXBContextFactory} is discovered, one of its methods |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
268 |
* {@link javax.xml.bind.JAXBContextFactory#createContext(String, ClassLoader, java.util.Map)} or |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
269 |
* {@link javax.xml.bind.JAXBContextFactory#createContext(Class[], java.util.Map)} is invoked |
12009 | 270 |
* to create a {@link JAXBContext}. |
271 |
* |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
272 |
* <p/> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
273 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
274 |
* @apiNote |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
275 |
* <p>Service discovery method using file /META-INF/services/javax.xml.bind.JAXBContext (described in step 4) |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
276 |
* and leveraging provider's static methods is supported only to allow backwards compatibility, but it is strongly |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
277 |
* recommended to migrate to standard ServiceLoader mechanism (described in step 3). |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
278 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
279 |
* @implNote |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
280 |
* Within the last step, if Glassfish AS environment detected, its specific service loader is used to find factory class. |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
281 |
* |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
282 |
* @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
283 |
* <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
284 |
* <li>Joe Fialli, Sun Microsystems, Inc.</li></ul> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
285 |
* |
12009 | 286 |
* @see Marshaller |
287 |
* @see Unmarshaller |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
288 |
* @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1">S 7.4.1 "Named Packages" |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
289 |
* in Java Language Specification</a> |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
290 |
* |
25840 | 291 |
* @since 1.6, JAXB 1.0 |
12009 | 292 |
*/ |
293 |
public abstract class JAXBContext { |
|
294 |
||
295 |
/** |
|
296 |
* The name of the property that contains the name of the class capable |
|
297 |
* of creating new <tt>JAXBContext</tt> objects. |
|
298 |
*/ |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
299 |
public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.JAXBContextFactory"; |
12009 | 300 |
|
301 |
protected JAXBContext() { |
|
302 |
} |
|
303 |
||
304 |
||
305 |
/** |
|
306 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
307 |
* Create a new instance of a <tt>JAXBContext</tt> class. |
12009 | 308 |
* |
309 |
* <p> |
|
310 |
* This is a convenience method to invoke the |
|
311 |
* {@link #newInstance(String,ClassLoader)} method with |
|
312 |
* the context class loader of the current thread. |
|
313 |
* |
|
314 |
* @throws JAXBException if an error was encountered while creating the |
|
315 |
* <tt>JAXBContext</tt> such as |
|
316 |
* <ol> |
|
317 |
* <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
|
318 |
* <li>an ambiguity among global elements contained in the contextPath</li> |
|
319 |
* <li>failure to locate a value for the context factory provider property</li> |
|
320 |
* <li>mixing schema derived packages from different providers on the same contextPath</li> |
|
321 |
* </ol> |
|
322 |
*/ |
|
323 |
public static JAXBContext newInstance( String contextPath ) |
|
324 |
throws JAXBException { |
|
325 |
||
326 |
//return newInstance( contextPath, JAXBContext.class.getClassLoader() ); |
|
327 |
return newInstance( contextPath, getContextClassLoader()); |
|
328 |
} |
|
329 |
||
330 |
/** |
|
331 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
332 |
* Create a new instance of a <tt>JAXBContext</tt> class. |
12009 | 333 |
* |
334 |
* <p> |
|
335 |
* The client application must supply a context path which is a list of |
|
336 |
* colon (':', \u005Cu003A) separated java package names that contain |
|
337 |
* schema-derived classes and/or fully qualified JAXB-annotated classes. |
|
338 |
* Schema-derived |
|
339 |
* code is registered with the JAXBContext by the |
|
340 |
* ObjectFactory.class generated per package. |
|
341 |
* Alternatively than being listed in the context path, programmer |
|
342 |
* annotated JAXB mapped classes can be listed in a |
|
343 |
* <tt>jaxb.index</tt> resource file, format described below. |
|
344 |
* Note that a java package can contain both schema-derived classes and |
|
345 |
* user annotated JAXB classes. Additionally, the java package may |
|
346 |
* contain JAXB package annotations that must be processed. (see JLS, |
|
347 |
* Section 7.4.1 "Named Packages"). |
|
348 |
* </p> |
|
349 |
* |
|
350 |
* <p> |
|
351 |
* Every package listed on the contextPath must meet <b>one or both</b> of the |
|
352 |
* following conditions otherwise a <tt>JAXBException</tt> will be thrown: |
|
353 |
* </p> |
|
354 |
* <ol> |
|
355 |
* <li>it must contain ObjectFactory.class</li> |
|
356 |
* <li>it must contain jaxb.index</li> |
|
357 |
* </ol> |
|
358 |
* |
|
359 |
* <p> |
|
360 |
* <b>Format for jaxb.index</b> |
|
361 |
* <p> |
|
362 |
* The file contains a newline-separated list of class names. |
|
363 |
* Space and tab characters, as well as blank |
|
364 |
* lines, are ignored. The comment character |
|
365 |
* is '#' (0x23); on each line all characters following the first comment |
|
366 |
* character are ignored. The file must be encoded in UTF-8. Classes that |
|
367 |
* are reachable, as defined in {@link #newInstance(Class...)}, from the |
|
368 |
* listed classes are also registered with JAXBContext. |
|
369 |
* <p> |
|
370 |
* Constraints on class name occuring in a <tt>jaxb.index</tt> file are: |
|
371 |
* <ul> |
|
372 |
* <li>Must not end with ".class".</li> |
|
373 |
* <li>Class names are resolved relative to package containing |
|
374 |
* <tt>jaxb.index</tt> file. Only classes occuring directly in package |
|
375 |
* containing <tt>jaxb.index</tt> file are allowed.</li> |
|
376 |
* <li>Fully qualified class names are not allowed. |
|
377 |
* A qualified class name,relative to current package, |
|
378 |
* is only allowed to specify a nested or inner class.</li> |
|
379 |
* </ul> |
|
380 |
* |
|
381 |
* <p> |
|
382 |
* To maintain compatibility with JAXB 1.0 schema to java |
|
383 |
* interface/implementation binding, enabled by schema customization |
|
29839
6d5d546e953b
8076549: Update JAX-WS RI integration to latest version (2.2.11-b150402.1412)
aefimov
parents:
28887
diff
changeset
|
384 |
* <tt>{@literal <jaxb:globalBindings valueClass="false">}</tt>, |
12009 | 385 |
* the JAXB provider will ensure that each package on the context path |
386 |
* has a <tt>jaxb.properties</tt> file which contains a value for the |
|
387 |
* <tt>javax.xml.bind.context.factory</tt> property and that all values |
|
388 |
* resolve to the same provider. This requirement does not apply to |
|
389 |
* JAXB annotated classes. |
|
390 |
* |
|
391 |
* <p> |
|
392 |
* If there are any global XML element name collisions across the various |
|
393 |
* packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt> |
|
394 |
* will be thrown. |
|
395 |
* |
|
396 |
* <p> |
|
397 |
* Mixing generated interface/impl bindings from multiple JAXB Providers |
|
398 |
* in the same context path may result in a <tt>JAXBException</tt> |
|
399 |
* being thrown. |
|
400 |
* |
|
401 |
* <p> |
|
402 |
* The steps involved in discovering the JAXB implementation is discussed in the class javadoc. |
|
403 |
* |
|
404 |
* @param contextPath list of java package names that contain schema |
|
405 |
* derived class and/or java to schema (JAXB-annotated) |
|
406 |
* mapped classes |
|
407 |
* @param classLoader |
|
408 |
* This class loader will be used to locate the implementation |
|
409 |
* classes. |
|
410 |
* |
|
411 |
* @return a new instance of a <tt>JAXBContext</tt> |
|
412 |
* @throws JAXBException if an error was encountered while creating the |
|
413 |
* <tt>JAXBContext</tt> such as |
|
414 |
* <ol> |
|
415 |
* <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
|
416 |
* <li>an ambiguity among global elements contained in the contextPath</li> |
|
417 |
* <li>failure to locate a value for the context factory provider property</li> |
|
418 |
* <li>mixing schema derived packages from different providers on the same contextPath</li> |
|
419 |
* </ol> |
|
420 |
*/ |
|
421 |
public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException { |
|
422 |
||
423 |
return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap()); |
|
424 |
} |
|
425 |
||
426 |
/** |
|
427 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
428 |
* Create a new instance of a <tt>JAXBContext</tt> class. |
12009 | 429 |
* |
430 |
* <p> |
|
431 |
* This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)}, |
|
432 |
* but this version allows you to pass in provider-specific properties to configure |
|
433 |
* the instantiation of {@link JAXBContext}. |
|
434 |
* |
|
435 |
* <p> |
|
436 |
* The interpretation of properties is up to implementations. Implementations should |
|
437 |
* throw <tt>JAXBException</tt> if it finds properties that it doesn't understand. |
|
438 |
* |
|
439 |
* @param contextPath list of java package names that contain schema derived classes |
|
440 |
* @param classLoader |
|
441 |
* This class loader will be used to locate the implementation classes. |
|
442 |
* @param properties |
|
443 |
* provider-specific properties. Can be null, which means the same thing as passing |
|
444 |
* in an empty map. |
|
445 |
* |
|
446 |
* @return a new instance of a <tt>JAXBContext</tt> |
|
447 |
* @throws JAXBException if an error was encountered while creating the |
|
448 |
* <tt>JAXBContext</tt> such as |
|
449 |
* <ol> |
|
450 |
* <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li> |
|
451 |
* <li>an ambiguity among global elements contained in the contextPath</li> |
|
452 |
* <li>failure to locate a value for the context factory provider property</li> |
|
453 |
* <li>mixing schema derived packages from different providers on the same contextPath</li> |
|
454 |
* </ol> |
|
25840 | 455 |
* @since 1.6, JAXB 2.0 |
12009 | 456 |
*/ |
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
457 |
public static JAXBContext newInstance( String contextPath, |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
458 |
ClassLoader classLoader, |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
459 |
Map<String,?> properties ) throws JAXBException { |
12009 | 460 |
|
461 |
return ContextFinder.find( |
|
462 |
/* The default property name according to the JAXB spec */ |
|
463 |
JAXB_CONTEXT_FACTORY, |
|
464 |
||
465 |
/* the context path supplied by the client app */ |
|
466 |
contextPath, |
|
467 |
||
468 |
/* class loader to be used */ |
|
469 |
classLoader, |
|
470 |
properties ); |
|
471 |
} |
|
472 |
||
473 |
// TODO: resurrect this once we introduce external annotations |
|
474 |
// /** |
|
475 |
// * <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
476 |
// * Create a new instance of a <tt>JAXBContext</tt> class. |
12009 | 477 |
// * |
478 |
// * <p> |
|
479 |
// * The client application must supply a list of classes that the new |
|
480 |
// * context object needs to recognize. |
|
481 |
// * |
|
482 |
// * Not only the new context will recognize all the classes specified, |
|
483 |
// * but it will also recognize any classes that are directly/indirectly |
|
484 |
// * referenced statically from the specified classes. |
|
485 |
// * |
|
486 |
// * For example, in the following Java code, if you do |
|
487 |
// * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext} |
|
488 |
// * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt>: |
|
489 |
// * <pre> |
|
490 |
// * class Foo { |
|
491 |
// * Bar b; |
|
492 |
// * } |
|
493 |
// * class Bar { int x; } |
|
494 |
// * class Zot extends Bar { int y; } |
|
495 |
// * </pre> |
|
496 |
// * |
|
497 |
// * Therefore, a typical client application only needs to specify the |
|
498 |
// * top-level classes, but it needs to be careful. |
|
499 |
// * |
|
500 |
// * TODO: if we are to define other mechanisms, refer to them. |
|
501 |
// * |
|
502 |
// * @param externalBindings |
|
503 |
// * list of external binding files. Can be null or empty if none is used. |
|
504 |
// * when specified, those files determine how the classes are bound. |
|
505 |
// * |
|
506 |
// * @param classesToBeBound |
|
507 |
// * list of java classes to be recognized by the new {@link JAXBContext}. |
|
508 |
// * Can be empty, in which case a {@link JAXBContext} that only knows about |
|
509 |
// * spec-defined classes will be returned. |
|
510 |
// * |
|
511 |
// * @return |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
512 |
// * A new instance of a <tt>JAXBContext</tt>. |
12009 | 513 |
// * |
514 |
// * @throws JAXBException |
|
515 |
// * if an error was encountered while creating the |
|
516 |
// * <tt>JAXBContext</tt>, such as (but not limited to): |
|
517 |
// * <ol> |
|
518 |
// * <li>No JAXB implementation was discovered |
|
519 |
// * <li>Classes use JAXB annotations incorrectly |
|
520 |
// * <li>Classes have colliding annotations (i.e., two classes with the same type name) |
|
521 |
// * <li>Specified external bindings are incorrect |
|
522 |
// * <li>The JAXB implementation was unable to locate |
|
523 |
// * provider-specific out-of-band information (such as additional |
|
524 |
// * files generated at the development time.) |
|
525 |
// * </ol> |
|
526 |
// * |
|
527 |
// * @throws IllegalArgumentException |
|
528 |
// * if the parameter contains {@code null} (i.e., {@code newInstance(null);}) |
|
529 |
// * |
|
25840 | 530 |
// * @since JAXB 2.0 |
12009 | 531 |
// */ |
532 |
// public static JAXBContext newInstance( Source[] externalBindings, Class... classesToBeBound ) |
|
533 |
// throws JAXBException { |
|
534 |
// |
|
535 |
// // empty class list is not an error, because the context will still include |
|
536 |
// // spec-specified classes like String and Integer. |
|
537 |
// // if(classesToBeBound.length==0) |
|
538 |
// // throw new IllegalArgumentException(); |
|
539 |
// |
|
540 |
// // but it is an error to have nulls in it. |
|
541 |
// for( int i=classesToBeBound.length-1; i>=0; i-- ) |
|
542 |
// if(classesToBeBound[i]==null) |
|
543 |
// throw new IllegalArgumentException(); |
|
544 |
// |
|
545 |
// return ContextFinder.find(externalBindings,classesToBeBound); |
|
546 |
// } |
|
547 |
||
548 |
/** |
|
549 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
550 |
* Create a new instance of a <tt>JAXBContext</tt> class. |
12009 | 551 |
* |
552 |
* <p> |
|
553 |
* The client application must supply a list of classes that the new |
|
554 |
* context object needs to recognize. |
|
555 |
* |
|
556 |
* Not only the new context will recognize all the classes specified, |
|
557 |
* but it will also recognize any classes that are directly/indirectly |
|
558 |
* referenced statically from the specified classes. Subclasses of |
|
29839
6d5d546e953b
8076549: Update JAX-WS RI integration to latest version (2.2.11-b150402.1412)
aefimov
parents:
28887
diff
changeset
|
559 |
* referenced classes nor <tt>@XmlTransient</tt> referenced classes |
12009 | 560 |
* are not registered with JAXBContext. |
561 |
* |
|
562 |
* For example, in the following Java code, if you do |
|
563 |
* <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext} |
|
564 |
* will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt> or <tt>FooBar</tt>: |
|
565 |
* <pre> |
|
566 |
* class Foo { |
|
567 |
* @XmlTransient FooBar c; |
|
568 |
* Bar b; |
|
569 |
* } |
|
570 |
* class Bar { int x; } |
|
571 |
* class Zot extends Bar { int y; } |
|
572 |
* class FooBar { } |
|
573 |
* </pre> |
|
574 |
* |
|
575 |
* Therefore, a typical client application only needs to specify the |
|
576 |
* top-level classes, but it needs to be careful. |
|
577 |
* |
|
578 |
* <p> |
|
579 |
* Note that for each java package registered with JAXBContext, |
|
580 |
* when the optional package annotations exist, they must be processed. |
|
581 |
* (see JLS, Section 7.4.1 "Named Packages"). |
|
582 |
* |
|
583 |
* <p> |
|
584 |
* The steps involved in discovering the JAXB implementation is discussed in the class javadoc. |
|
585 |
* |
|
586 |
* @param classesToBeBound |
|
587 |
* list of java classes to be recognized by the new {@link JAXBContext}. |
|
588 |
* Can be empty, in which case a {@link JAXBContext} that only knows about |
|
589 |
* spec-defined classes will be returned. |
|
590 |
* |
|
591 |
* @return |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
592 |
* A new instance of a <tt>JAXBContext</tt>. |
12009 | 593 |
* |
594 |
* @throws JAXBException |
|
595 |
* if an error was encountered while creating the |
|
596 |
* <tt>JAXBContext</tt>, such as (but not limited to): |
|
597 |
* <ol> |
|
598 |
* <li>No JAXB implementation was discovered |
|
599 |
* <li>Classes use JAXB annotations incorrectly |
|
600 |
* <li>Classes have colliding annotations (i.e., two classes with the same type name) |
|
601 |
* <li>The JAXB implementation was unable to locate |
|
602 |
* provider-specific out-of-band information (such as additional |
|
603 |
* files generated at the development time.) |
|
604 |
* </ol> |
|
605 |
* |
|
606 |
* @throws IllegalArgumentException |
|
607 |
* if the parameter contains {@code null} (i.e., {@code newInstance(null);}) |
|
608 |
* |
|
25840 | 609 |
* @since 1.6, JAXB 2.0 |
12009 | 610 |
*/ |
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
611 |
public static JAXBContext newInstance( Class<?> ... classesToBeBound ) |
12009 | 612 |
throws JAXBException { |
613 |
||
614 |
return newInstance(classesToBeBound,Collections.<String,Object>emptyMap()); |
|
615 |
} |
|
616 |
||
617 |
/** |
|
618 |
* <p> |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
619 |
* Create a new instance of a <tt>JAXBContext</tt> class. |
12009 | 620 |
* |
621 |
* <p> |
|
622 |
* An overloading of {@link JAXBContext#newInstance(Class...)} |
|
623 |
* to configure 'properties' for this instantiation of {@link JAXBContext}. |
|
624 |
* |
|
625 |
* <p> |
|
626 |
* The interpretation of properties is up to implementations. Implementations should |
|
627 |
* throw <tt>JAXBException</tt> if it finds properties that it doesn't understand. |
|
628 |
* |
|
629 |
* @param classesToBeBound |
|
630 |
* list of java classes to be recognized by the new {@link JAXBContext}. |
|
631 |
* Can be empty, in which case a {@link JAXBContext} that only knows about |
|
632 |
* spec-defined classes will be returned. |
|
633 |
* @param properties |
|
634 |
* provider-specific properties. Can be null, which means the same thing as passing |
|
635 |
* in an empty map. |
|
636 |
* |
|
637 |
* @return |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
638 |
* A new instance of a <tt>JAXBContext</tt>. |
12009 | 639 |
* |
640 |
* @throws JAXBException |
|
641 |
* if an error was encountered while creating the |
|
642 |
* <tt>JAXBContext</tt>, such as (but not limited to): |
|
643 |
* <ol> |
|
644 |
* <li>No JAXB implementation was discovered |
|
645 |
* <li>Classes use JAXB annotations incorrectly |
|
646 |
* <li>Classes have colliding annotations (i.e., two classes with the same type name) |
|
647 |
* <li>The JAXB implementation was unable to locate |
|
648 |
* provider-specific out-of-band information (such as additional |
|
649 |
* files generated at the development time.) |
|
650 |
* </ol> |
|
651 |
* |
|
652 |
* @throws IllegalArgumentException |
|
653 |
* if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);}) |
|
654 |
* |
|
25840 | 655 |
* @since 1.6, JAXB 2.0 |
12009 | 656 |
*/ |
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
657 |
public static JAXBContext newInstance( Class<?>[] classesToBeBound, Map<String,?> properties ) |
12009 | 658 |
throws JAXBException { |
659 |
||
16791 | 660 |
if (classesToBeBound == null) { |
661 |
throw new IllegalArgumentException(); |
|
662 |
} |
|
12009 | 663 |
|
664 |
// but it is an error to have nulls in it. |
|
16791 | 665 |
for (int i = classesToBeBound.length - 1; i >= 0; i--) { |
666 |
if (classesToBeBound[i] == null) { |
|
12009 | 667 |
throw new IllegalArgumentException(); |
16791 | 668 |
} |
669 |
} |
|
12009 | 670 |
|
671 |
return ContextFinder.find(classesToBeBound,properties); |
|
672 |
} |
|
673 |
||
674 |
/** |
|
675 |
* Create an <tt>Unmarshaller</tt> object that can be used to convert XML |
|
676 |
* data into a java content tree. |
|
677 |
* |
|
678 |
* @return an <tt>Unmarshaller</tt> object |
|
679 |
* |
|
680 |
* @throws JAXBException if an error was encountered while creating the |
|
681 |
* <tt>Unmarshaller</tt> object |
|
682 |
*/ |
|
683 |
public abstract Unmarshaller createUnmarshaller() throws JAXBException; |
|
684 |
||
685 |
||
686 |
/** |
|
687 |
* Create a <tt>Marshaller</tt> object that can be used to convert a |
|
688 |
* java content tree into XML data. |
|
689 |
* |
|
690 |
* @return a <tt>Marshaller</tt> object |
|
691 |
* |
|
692 |
* @throws JAXBException if an error was encountered while creating the |
|
693 |
* <tt>Marshaller</tt> object |
|
694 |
*/ |
|
695 |
public abstract Marshaller createMarshaller() throws JAXBException; |
|
696 |
||
697 |
||
698 |
/** |
|
699 |
* {@link Validator} has been made optional and deprecated in JAXB 2.0. Please |
|
700 |
* refer to the javadoc for {@link Validator} for more detail. |
|
701 |
* <p> |
|
702 |
* Create a <tt>Validator</tt> object that can be used to validate a |
|
703 |
* java content tree against its source schema. |
|
704 |
* |
|
705 |
* @return a <tt>Validator</tt> object |
|
706 |
* |
|
707 |
* @throws JAXBException if an error was encountered while creating the |
|
708 |
* <tt>Validator</tt> object |
|
709 |
* @deprecated since JAXB2.0 |
|
710 |
*/ |
|
711 |
public abstract Validator createValidator() throws JAXBException; |
|
712 |
||
713 |
/** |
|
714 |
* Creates a <tt>Binder</tt> object that can be used for |
|
715 |
* associative/in-place unmarshalling/marshalling. |
|
716 |
* |
|
717 |
* @param domType select the DOM API to use by passing in its DOM Node class. |
|
718 |
* |
|
719 |
* @return always a new valid <tt>Binder</tt> object. |
|
720 |
* |
|
721 |
* @throws UnsupportedOperationException |
|
722 |
* if DOM API corresponding to <tt>domType</tt> is not supported by |
|
723 |
* the implementation. |
|
724 |
* |
|
25840 | 725 |
* @since 1.6, JAXB 2.0 |
12009 | 726 |
*/ |
727 |
public <T> Binder<T> createBinder(Class<T> domType) { |
|
728 |
// to make JAXB 1.0 implementations work, this method must not be |
|
729 |
// abstract |
|
730 |
throw new UnsupportedOperationException(); |
|
731 |
} |
|
732 |
||
733 |
/** |
|
734 |
* Creates a <tt>Binder</tt> for W3C DOM. |
|
735 |
* |
|
736 |
* @return always a new valid <tt>Binder</tt> object. |
|
737 |
* |
|
25840 | 738 |
* @since 1.6, JAXB 2.0 |
12009 | 739 |
*/ |
740 |
public Binder<Node> createBinder() { |
|
741 |
return createBinder(Node.class); |
|
742 |
} |
|
743 |
||
744 |
/** |
|
745 |
* Creates a <tt>JAXBIntrospector</tt> object that can be used to |
|
746 |
* introspect JAXB objects. |
|
747 |
* |
|
748 |
* @return |
|
749 |
* always return a non-null valid <tt>JAXBIntrospector</tt> object. |
|
750 |
* |
|
751 |
* @throws UnsupportedOperationException |
|
752 |
* Calling this method on JAXB 1.0 implementations will throw |
|
753 |
* an UnsupportedOperationException. |
|
754 |
* |
|
25840 | 755 |
* @since 1.6, JAXB 2.0 |
12009 | 756 |
*/ |
757 |
public JAXBIntrospector createJAXBIntrospector() { |
|
758 |
// to make JAXB 1.0 implementations work, this method must not be |
|
759 |
// abstract |
|
760 |
throw new UnsupportedOperationException(); |
|
761 |
} |
|
762 |
||
763 |
/** |
|
764 |
* Generates the schema documents for this context. |
|
765 |
* |
|
766 |
* @param outputResolver |
|
767 |
* this object controls the output to which schemas |
|
768 |
* will be sent. |
|
769 |
* |
|
770 |
* @throws IOException |
|
771 |
* if {@link SchemaOutputResolver} throws an {@link IOException}. |
|
772 |
* |
|
773 |
* @throws UnsupportedOperationException |
|
774 |
* Calling this method on JAXB 1.0 implementations will throw |
|
775 |
* an UnsupportedOperationException. |
|
776 |
* |
|
25840 | 777 |
* @since 1.6, JAXB 2.0 |
12009 | 778 |
*/ |
779 |
public void generateSchema(SchemaOutputResolver outputResolver) throws IOException { |
|
780 |
// to make JAXB 1.0 implementations work, this method must not be |
|
781 |
// abstract |
|
782 |
throw new UnsupportedOperationException(); |
|
783 |
} |
|
784 |
||
785 |
private static ClassLoader getContextClassLoader() { |
|
786 |
if (System.getSecurityManager() == null) { |
|
787 |
return Thread.currentThread().getContextClassLoader(); |
|
788 |
} else { |
|
31109
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
789 |
return java.security.AccessController.doPrivileged( |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
790 |
new java.security.PrivilegedAction<ClassLoader>() { |
a542f8dcbbf8
8072839: JAX-B Plugability Layer: using java.util.ServiceLoader
mkos
parents:
29839
diff
changeset
|
791 |
public ClassLoader run() { |
12009 | 792 |
return Thread.currentThread().getContextClassLoader(); |
793 |
} |
|
794 |
}); |
|
795 |
} |
|
796 |
} |
|
797 |
||
798 |
} |