001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036: package com.sun.xml.bind.api;
037:
038: import java.io.IOException;
039: import java.lang.reflect.Type;
040: import java.util.Collection;
041: import java.util.Collections;
042: import java.util.List;
043: import java.util.Map;
044:
045: import javax.xml.bind.JAXBContext;
046: import javax.xml.bind.JAXBException;
047: import javax.xml.bind.Marshaller;
048: import javax.xml.bind.SchemaOutputResolver;
049: import javax.xml.bind.annotation.XmlAttachmentRef;
050: import javax.xml.namespace.QName;
051: import javax.xml.transform.Result;
052:
053: import com.sun.istack.NotNull;
054: import com.sun.istack.Nullable;
055: import com.sun.xml.bind.api.impl.NameConverter;
056: import com.sun.xml.bind.v2.ContextFactory;
057: import com.sun.xml.bind.v2.model.annotation.RuntimeAnnotationReader;
058: import com.sun.xml.bind.v2.model.nav.Navigator;
059:
060: /**
061: * {@link JAXBContext} enhanced with JAXB RI specific functionalities.
062: *
063: * <p>
064: * <b>Subject to change without notice</b>.
065: *
066: * @since 2.0 EA1
067: * @author
068: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
069: */
070: public abstract class JAXBRIContext extends JAXBContext {
071:
072: protected JAXBRIContext() {
073: }
074:
075: /**
076: * Creates a new {@link JAXBRIContext}.
077: *
078: * <p>
079: * {@link JAXBContext#newInstance(Class[]) JAXBContext.newInstance()} methods may
080: * return other JAXB providers that are not compatible with the JAX-RPC RI.
081: * This method guarantees that the JAX-WS RI will finds the JAXB RI.
082: *
083: * @param classes
084: * Classes to be bound. See {@link JAXBContext#newInstance(Class[])} for the meaning.
085: * @param typeRefs
086: * See {@link #TYPE_REFERENCES} for the meaning of this parameter.
087: * Can be null.
088: * @param subclassReplacements
089: * See {@link #SUBCLASS_REPLACEMENTS} for the meaning of this parameter.
090: * Can be null.
091: * @param defaultNamespaceRemap
092: * See {@link #DEFAULT_NAMESPACE_REMAP} for the meaning of this parameter.
093: * Can be null (and should be null for ordinary use of JAXB.)
094: * @param c14nSupport
095: * See {@link #CANONICALIZATION_SUPPORT} for the meaning of this parameter.
096: * @param ar
097: * See {@link #ANNOTATION_READER} for the meaning of this parameter.
098: * Can be null.
099: * @since JAXB 2.1 EA2
100: */
101: public static JAXBRIContext newInstance(@NotNull
102: Class[] classes, @Nullable
103: Collection<TypeReference> typeRefs, @Nullable
104: Map<Class, Class> subclassReplacements, @Nullable
105: String defaultNamespaceRemap, boolean c14nSupport, @Nullable
106: RuntimeAnnotationReader ar) throws JAXBException {
107: return ContextFactory.createContext(classes, typeRefs,
108: subclassReplacements, defaultNamespaceRemap,
109: c14nSupport, ar, false, false);
110: }
111:
112: /**
113: * @deprecated
114: * Compatibility with older versions.
115: */
116: public static JAXBRIContext newInstance(@NotNull
117: Class[] classes, @Nullable
118: Collection<TypeReference> typeRefs, @Nullable
119: String defaultNamespaceRemap, boolean c14nSupport)
120: throws JAXBException {
121: return newInstance(classes, typeRefs, Collections
122: .<Class, Class> emptyMap(), defaultNamespaceRemap,
123: c14nSupport, null);
124: }
125:
126: /**
127: * Returns true if this context includes a class
128: * that has {@link XmlAttachmentRef}.
129: *
130: * @since 2.1
131: */
132: public abstract boolean hasSwaRef();
133:
134: /**
135: * If the given object is bound to an element in XML by JAXB,
136: * returns the element name.
137: *
138: * @return null
139: * if the object is not bound to an element.
140: * @throws JAXBException
141: * if the object is not known to this context.
142: *
143: * @since 2.0 EA1
144: */
145: public abstract @Nullable
146: QName getElementName(@NotNull
147: Object o) throws JAXBException;
148:
149: /**
150: * Creates a mini-marshaller/unmarshaller that can process a {@link TypeReference}.
151: *
152: * @return
153: * null if the specified reference is not given to {@link JAXBRIContext#newInstance}.
154: *
155: * @since 2.0 EA1
156: */
157: public abstract Bridge createBridge(@NotNull
158: TypeReference ref);
159:
160: /**
161: * Creates a new {@link BridgeContext} instance.
162: *
163: * @return
164: * always a valid non-null instance.
165: *
166: * @since 2.0 EA1
167: */
168: public abstract @NotNull
169: BridgeContext createBridgeContext();
170:
171: /**
172: * Gets a {@link RawAccessor} for the specified element property of the specified wrapper bean class.
173: *
174: * <p>
175: * This method is designed to assist the JAX-RPC RI fill in a wrapper bean (in the doc/lit/wrap mode.)
176: * In the said mode, a wrapper bean is supposed to only have properties that match elements,
177: * and for each element that appear in the content model there's one property.
178: *
179: * <p>
180: * Therefore, this method takes a wrapper bean and a tag name that identifies a property
181: * on the given wrapper bean, then returns a {@link RawAccessor} that allows the caller
182: * to set/get a value from the property of the bean.
183: *
184: * <p>
185: * This method is not designed for a performance. The caller is expected to cache the result.
186: *
187: * @param <B>
188: * type of the wrapper bean
189: * @param <V>
190: * type of the property of the bean
191: * @return
192: * always return non-null valid accessor object.
193: * @throws JAXBException
194: * if the specified wrapper bean is not bound by JAXB, or if it doesn't have an element property
195: * of the given name.
196: *
197: * @since 2.0 EA1
198: */
199: public abstract <B, V> RawAccessor<B, V> getElementPropertyAccessor(
200: Class<B> wrapperBean, String nsUri, String localName)
201: throws JAXBException;
202:
203: /**
204: * Gets the namespace URIs statically known to this {@link JAXBContext}.
205: *
206: * <p>
207: * When JAXB is used to marshal into sub-trees, it declares
208: * these namespace URIs at each top-level element that it marshals.
209: *
210: * To avoid repeated namespace declarations at sub-elements, the application
211: * may declare those namespaces at a higher level.
212: *
213: * @return
214: * always non-null.
215: *
216: * @since 2.0 EA2
217: */
218: public abstract @NotNull
219: List<String> getKnownNamespaceURIs();
220:
221: /**
222: * Generates the schema documents from the model.
223: *
224: * <p>
225: * The caller can use the additionalElementDecls parameter to
226: * add element declarations to the generate schema.
227: * For example, if the JAX-RPC passes in the following entry:
228: *
229: * {foo}bar -> DeclaredType for java.lang.String
230: *
231: * then JAXB generates the following element declaration (in the schema
232: * document for the namespace "foo")"
233: *
234: * <xs:element name="bar" type="xs:string" />
235: *
236: * This can be used for generating schema components necessary for WSDL.
237: *
238: * @param outputResolver
239: * this object controls the output to which schemas
240: * will be sent.
241: *
242: * @throws IOException
243: * if {@link SchemaOutputResolver} throws an {@link IOException}.
244: */
245: public abstract void generateSchema(@NotNull
246: SchemaOutputResolver outputResolver) throws IOException;
247:
248: /**
249: * Returns the name of the XML Type bound to the
250: * specified Java type.
251: *
252: * @param tr
253: * must not be null. This must be one of the {@link TypeReference}s specified
254: * in the {@link JAXBRIContext#newInstance} method.
255: *
256: * @throws IllegalArgumentException
257: * if the parameter is null or not a part of the {@link TypeReference}s specified
258: * in the {@link JAXBRIContext#newInstance} method.
259: *
260: * @return null
261: * if the referenced type is an anonymous and therefore doesn't have a name.
262: */
263: public abstract QName getTypeName(@NotNull
264: TypeReference tr);
265:
266: /**
267: * Gets the build information of the JAXB runtime.
268: *
269: * @return
270: * may be null, if the runtime is loaded by a class loader that doesn't support
271: * the access to the manifest informatino.
272: */
273: public abstract @NotNull
274: String getBuildId();
275:
276: /**
277: * Generates the episode file that represents the binding known to this {@link JAXBContext},
278: * so that XJC can later do separate compilation.
279: *
280: * <p>
281: * Episode file is really just a JAXB customization file, except that currently
282: * we use the RI-specific SCD to refer to schema components.
283: *
284: * @param output
285: * This receives the generated episode file.
286: *
287: * @since 2.1
288: */
289: public abstract void generateEpisode(Result output);
290:
291: /**
292: * Computes a Java identifier from a local name.
293: *
294: * <p>
295: * This method faithfully implements the name mangling rule as specified in the JAXB spec.
296: *
297: * <p>
298: * In JAXB, a collision with a Java reserved word (such as "return") never happens.
299: * Accordingly, this method may return an identifier that collides with reserved words.
300: *
301: * <p>
302: * Use <tt>JJavaName.isJavaIdentifier(String)</tt> to check for such collision.
303: *
304: * @return
305: * Typically, this method returns "nameLikeThis".
306: */
307: public static @NotNull
308: String mangleNameToVariableName(@NotNull
309: String localName) {
310: return NameConverter.standard.toVariableName(localName);
311: }
312:
313: /**
314: * Computes a Java class name from a local name.
315: *
316: * <p>
317: * This method faithfully implements the name mangling rule as specified in the JAXB spec.
318: *
319: * @return
320: * Typically, this method returns "NameLikeThis".
321: */
322: public static @NotNull
323: String mangleNameToClassName(@NotNull
324: String localName) {
325: return NameConverter.standard.toClassName(localName);
326: }
327:
328: /**
329: * Computes a Java class name from a local name.
330: *
331: * <p>
332: * This method faithfully implements the name mangling rule as specified in the JAXB spec.
333: * This method works like {@link #mangleNameToClassName(String)} except that it looks
334: * for "getClass" and returns something else.
335: *
336: * @return
337: * Typically, this method returns "NameLikeThis".
338: */
339: public static @NotNull
340: String mangleNameToPropertyName(@NotNull
341: String localName) {
342: return NameConverter.standard.toPropertyName(localName);
343: }
344:
345: /**
346: * Gets the parameterization of the given base type.
347: *
348: * <p>
349: * For example, given the following
350: * <pre><xmp>
351: * interface Foo<T> extends List<List<T>> {}
352: * interface Bar extends Foo<String> {}
353: * </xmp></pre>
354: * This method works like this:
355: * <pre><xmp>
356: * getBaseClass( Bar, List ) = List<List<String>
357: * getBaseClass( Bar, Foo ) = Foo<String>
358: * getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
359: * getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>
360: * </xmp></pre>
361: *
362: * @param type
363: * The type that derives from {@code baseType}
364: * @param baseType
365: * The class whose parameterization we are interested in.
366: * @return
367: * The use of {@code baseType} in {@code type}.
368: * or null if the type is not assignable to the base type.
369: * @since 2.0 FCS
370: */
371: public static @Nullable
372: Type getBaseType(@NotNull
373: Type type, @NotNull
374: Class baseType) {
375: return Navigator.REFLECTION.getBaseClass(type, baseType);
376: }
377:
378: /**
379: * The property that you can specify to {@link JAXBContext#newInstance}
380: * to reassign the default namespace URI to something else at the runtime.
381: *
382: * <p>
383: * The value of the property is {@link String}, and it is used as the namespace URI
384: * that succeeds the default namespace URI.
385: *
386: * @since 2.0 EA1
387: */
388: public static final String DEFAULT_NAMESPACE_REMAP = "com.sun.xml.bind.defaultNamespaceRemap";
389:
390: /**
391: * The property that you can specify to {@link JAXBContext#newInstance}
392: * to put additional JAXB type references into the {@link JAXBContext}.
393: *
394: * <p>
395: * The value of the property is {@link Collection}<{@link TypeReference}>.
396: * Those {@link TypeReference}s can then be used to create {@link Bridge}s.
397: *
398: * <p>
399: * This mechanism allows additional element declarations that were not a part of
400: * the schema into the created {@link JAXBContext}.
401: *
402: * @since 2.0 EA1
403: */
404: public static final String TYPE_REFERENCES = "com.sun.xml.bind.typeReferences";
405:
406: /**
407: * The property that you can specify to {@link JAXBContext#newInstance}
408: * and {@link Marshaller#setProperty(String, Object)}
409: * to enable the c14n marshalling support in the {@link JAXBContext}.
410: *
411: * @see C14nSupport_ArchitectureDocument
412: * @since 2.0 EA2
413: */
414: public static final String CANONICALIZATION_SUPPORT = "com.sun.xml.bind.c14n";
415:
416: /**
417: * The property that you can specify to {@link JAXBContext#newInstance}
418: * to allow unmarshaller to honor <tt>xsi:nil</tt> anywhere, even if they are
419: * not specifically allowed by the schema.
420: *
421: * @since 2.1.3
422: */
423: public static final String TREAT_EVERYTHING_NILLABLE = "com.sun.xml.bind.treatEverythingNillable";
424:
425: /**
426: * The property that you can specify to {@link JAXBContext#newInstance}
427: * to use alternative {@link RuntimeAnnotationReader} implementation.
428: *
429: * @since 2.1 EA2
430: */
431: public static final String ANNOTATION_READER = RuntimeAnnotationReader.class
432: .getName();
433:
434: /**
435: * Marshaller/Unmarshaller property to enable XOP processing.
436: *
437: * @since 2.0 EA2
438: */
439: public static final String ENABLE_XOP = "com.sun.xml.bind.XOP";
440:
441: /**
442: * The property that you can specify to {@link JAXBContext#newInstance}
443: * to specify specific classes that replace the reference to generic classes.
444: *
445: * <p>
446: * See the release notes for more details about this feature.
447: *
448: * @since 2.1 EA2
449: */
450: public static final String SUBCLASS_REPLACEMENTS = "com.sun.xml.bind.subclassReplacements";
451:
452: /**
453: * The property that you can specify to {@link JAXBContext#newInstance}
454: * enable support of XmlAccessorFactory annotation in the {@link JAXBContext}.
455: *
456: * @since 2.1 EA2
457: */
458: public static final String XMLACCESSORFACTORY_SUPPORT = "com.sun.xml.bind.XmlAccessorFactory";
459:
460: }
|