001: /*
002: * Copyright 2006 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 com.sun.xml.internal.bind.api;
027:
028: import java.io.IOException;
029: import java.lang.reflect.InvocationTargetException;
030: import java.lang.reflect.Method;
031: import java.lang.reflect.Type;
032: import java.util.Collection;
033: import java.util.List;
034:
035: import javax.xml.bind.JAXBContext;
036: import javax.xml.bind.JAXBException;
037: import javax.xml.bind.Marshaller;
038: import javax.xml.bind.SchemaOutputResolver;
039: import javax.xml.namespace.QName;
040:
041: import com.sun.istack.internal.NotNull;
042: import com.sun.istack.internal.Nullable;
043: import com.sun.xml.internal.bind.api.impl.NameConverter;
044: import com.sun.xml.internal.bind.v2.model.nav.Navigator;
045:
046: /**
047: * {@link JAXBContext} enhanced with JAXB RI specific functionalities.
048: *
049: * <p>
050: * <b>Subject to change without notice</b>.
051: *
052: * @since 2.0 EA1
053: * @author
054: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
055: */
056: public abstract class JAXBRIContext extends JAXBContext {
057: protected JAXBRIContext() {
058: }
059:
060: /**
061: * Creates a new {@link JAXBRIContext}.
062: *
063: * <p>
064: * {@link JAXBContext#newInstance(Class[]) JAXBContext.newInstance()} methods may
065: * return other JAXB providers that are not compatible with the JAX-RPC RI.
066: * This method guarantees that the JAX-WS RI will finds the JAXB RI.
067: *
068: * @param classes
069: * Classes to be bound. See {@link JAXBContext#newInstance(Class[])} for the meaning.
070: * @param typeRefs
071: * See {@link #TYPE_REFERENCES} for the meaning of this parameter.
072: * Can be null.
073: * @param defaultNamespaceRemap
074: * See {@link #DEFAULT_NAMESPACE_REMAP} for the meaning of this parameter.
075: * Can be null (and should be null for ordinary use of JAXB.)
076: * @param c14nSupport
077: * See {@link #CANONICALIZATION_SUPPORT} for the meaning of this parameter.
078: */
079: public static JAXBRIContext newInstance(@NotNull
080: Class[] classes, @Nullable
081: Collection<TypeReference> typeRefs, @Nullable
082: String defaultNamespaceRemap, boolean c14nSupport)
083: throws JAXBException {
084: try {
085: Class c = Class
086: .forName("com.sun.xml.internal.bind.v2.ContextFactory");
087: Method method = c.getMethod("createContext", Class[].class,
088: Collection.class, String.class, boolean.class);
089: Object o = method.invoke(null, classes, typeRefs,
090: defaultNamespaceRemap, c14nSupport);
091: return (JAXBRIContext) o;
092: } catch (ClassNotFoundException e) {
093: throw new JAXBException(e);
094: } catch (NoSuchMethodException e) {
095: throw new JAXBException(e);
096: } catch (IllegalAccessException e) {
097: throw new JAXBException(e);
098: } catch (InvocationTargetException e) {
099: Throwable te = e.getTargetException();
100: if (te instanceof JAXBException)
101: throw (JAXBException) te;
102: if (te instanceof RuntimeException)
103: throw (RuntimeException) te;
104: if (te instanceof Error)
105: throw (Error) te;
106: throw new JAXBException(e);
107: }
108: }
109:
110: /**
111: * If the given object is bound to an element in XML by JAXB,
112: * returns the element name.
113: *
114: * @return null
115: * if the object is not bound to an element.
116: * @throws JAXBException
117: * if the object is not known to this context.
118: *
119: * @since 2.0 EA1
120: */
121: public abstract @Nullable
122: QName getElementName(@NotNull
123: Object o) throws JAXBException;
124:
125: /**
126: * Creates a mini-marshaller/unmarshaller that can process a {@link TypeReference}.
127: *
128: * @return
129: * null if the specified reference is not given to {@link JAXBRIContext#newInstance}.
130: *
131: * @since 2.0 EA1
132: */
133: public abstract Bridge createBridge(@NotNull
134: TypeReference ref);
135:
136: /**
137: * Creates a new {@link BridgeContext} instance.
138: *
139: * @return
140: * always a valid non-null instance.
141: *
142: * @since 2.0 EA1
143: */
144: public abstract @NotNull
145: BridgeContext createBridgeContext();
146:
147: /**
148: * Gets a {@link RawAccessor} for the specified element property of the specified wrapper bean class.
149: *
150: * <p>
151: * This method is designed to assist the JAX-RPC RI fill in a wrapper bean (in the doc/lit/wrap mode.)
152: * In the said mode, a wrapper bean is supposed to only have properties that match elements,
153: * and for each element that appear in the content model there's one property.
154: *
155: * <p>
156: * Therefore, this method takes a wrapper bean and a tag name that identifies a property
157: * on the given wrapper bean, then returns a {@link RawAccessor} that allows the caller
158: * to set/get a value from the property of the bean.
159: *
160: * <p>
161: * This method is not designed for a performance. The caller is expected to cache the result.
162: *
163: * @param <B>
164: * type of the wrapper bean
165: * @param <V>
166: * type of the property of the bean
167: * @return
168: * always return non-null valid accessor object.
169: * @throws JAXBException
170: * if the specified wrapper bean is not bound by JAXB, or if it doesn't have an element property
171: * of the given name.
172: *
173: * @since 2.0 EA1
174: */
175: public abstract <B, V> RawAccessor<B, V> getElementPropertyAccessor(
176: Class<B> wrapperBean, String nsUri, String localName)
177: throws JAXBException;
178:
179: /**
180: * Gets the namespace URIs statically known to this {@link JAXBContext}.
181: *
182: * <p>
183: * When JAXB is used to marshal into sub-trees, it declares
184: * these namespace URIs at each top-level element that it marshals.
185: *
186: * To avoid repeated namespace declarations at sub-elements, the application
187: * may declare those namespaces at a higher level.
188: *
189: * @return
190: * always non-null.
191: *
192: * @since 2.0 EA2
193: */
194: public abstract @NotNull
195: List<String> getKnownNamespaceURIs();
196:
197: /**
198: * Generates the schema documents from the model.
199: *
200: * <p>
201: * The caller can use the additionalElementDecls parameter to
202: * add element declarations to the generate schema.
203: * For example, if the JAX-RPC passes in the following entry:
204: *
205: * {foo}bar -> DeclaredType for java.lang.String
206: *
207: * then JAXB generates the following element declaration (in the schema
208: * document for the namespace "foo")"
209: *
210: * <xs:element name="bar" type="xs:string" />
211: *
212: * This can be used for generating schema components necessary for WSDL.
213: *
214: * @param outputResolver
215: * this object controls the output to which schemas
216: * will be sent.
217: *
218: * @throws IOException
219: * if {@link SchemaOutputResolver} throws an {@link IOException}.
220: */
221: public abstract void generateSchema(@NotNull
222: SchemaOutputResolver outputResolver) throws IOException;
223:
224: /**
225: * Returns the name of the XML Type bound to the
226: * specified Java type.
227: *
228: * @param tr
229: * must not be null. This must be one of the {@link TypeReference}s specified
230: * in the {@link JAXBRIContext#newInstance} method.
231: *
232: * @throws IllegalArgumentException
233: * if the parameter is null or not a part of the {@link TypeReference}s specified
234: * in the {@link JAXBRIContext#newInstance} method.
235: *
236: * @return null
237: * if the referenced type is an anonymous and therefore doesn't have a name.
238: */
239: public abstract QName getTypeName(@NotNull
240: TypeReference tr);
241:
242: /**
243: * Gets the build information of the JAXB runtime.
244: *
245: * @return
246: * may be null, if the runtime is loaded by a class loader that doesn't support
247: * the access to the manifest informatino.
248: */
249: public abstract @NotNull
250: String getBuildId();
251:
252: /**
253: * Computes a Java identifier from a local name.
254: *
255: * <p>
256: * This method faithfully implements the name mangling rule as specified in the JAXB spec.
257: *
258: * <p>
259: * In JAXB, a collision with a Java reserved word (such as "return") never happens.
260: * Accordingly, this method may return an identifier that collides with reserved words.
261: *
262: * <p>
263: * Use {@link JJavaName#isJavaIdentifier(String)} to check for such collision.
264: *
265: * @return
266: * Typically, this method returns "nameLikeThis".
267: *
268: * @see JJavaName#isJavaIdentifier(String)
269: */
270: public static @NotNull
271: String mangleNameToVariableName(@NotNull
272: String localName) {
273: return NameConverter.standard.toVariableName(localName);
274: }
275:
276: /**
277: * Computes a Java class name from a local name.
278: *
279: * <p>
280: * This method faithfully implements the name mangling rule as specified in the JAXB spec.
281: *
282: * @return
283: * Typically, this method returns "NameLikeThis".
284: */
285: public static @NotNull
286: String mangleNameToClassName(@NotNull
287: String localName) {
288: return NameConverter.standard.toClassName(localName);
289: }
290:
291: /**
292: * Gets the parameterization of the given base type.
293: *
294: * <p>
295: * For example, given the following
296: * <pre><xmp>
297: * interface Foo<T> extends List<List<T>> {}
298: * interface Bar extends Foo<String> {}
299: * </xmp></pre>
300: * This method works like this:
301: * <pre><xmp>
302: * getBaseClass( Bar, List ) = List<List<String>
303: * getBaseClass( Bar, Foo ) = Foo<String>
304: * getBaseClass( Foo<? extends Number>, Collection ) = Collection<List<? extends Number>>
305: * getBaseClass( ArrayList<? extends BigInteger>, List ) = List<? extends BigInteger>
306: * </xmp></pre>
307: *
308: * @param type
309: * The type that derives from {@code baseType}
310: * @param baseType
311: * The class whose parameterization we are interested in.
312: * @return
313: * The use of {@code baseType} in {@code type}.
314: * or null if the type is not assignable to the base type.
315: * @since 2.0 FCS
316: */
317: public static @Nullable
318: Type getBaseType(@NotNull
319: Type type, @NotNull
320: Class baseType) {
321: return Navigator.REFLECTION.getBaseClass(type, baseType);
322: }
323:
324: /**
325: * The property that you can specify to {@link JAXBContext#newInstance}
326: * to reassign the default namespace URI to something else at the runtime.
327: *
328: * <p>
329: * The value of the property is {@link String}, and it is used as the namespace URI
330: * that succeeds the default namespace URI.
331: *
332: * @since 2.0 EA1
333: */
334: public static final String DEFAULT_NAMESPACE_REMAP = "com.sun.xml.internal.bind.defaultNamespaceRemap";
335:
336: /**
337: * The property that you can specify to {@link JAXBContext#newInstance}
338: * to put additional JAXB type references into the {@link JAXBContext}.
339: *
340: * <p>
341: * The value of the property is {@link Collection}<{@link TypeReference}>.
342: * Those {@link TypeReference}s can then be used to create {@link Bridge}s.
343: *
344: * <p>
345: * This mechanism allows additional element declarations that were not a part of
346: * the schema into the created {@link JAXBContext}.
347: *
348: * @since 2.0 EA1
349: */
350: public static final String TYPE_REFERENCES = "com.sun.xml.internal.bind.typeReferences";
351:
352: /**
353: * The property that you can specify to {@link JAXBContext#newInstance}
354: * and {@link Marshaller#setProperty(String, Object)}
355: * to enable the c14n marshalling support in the {@link JAXBContext}.
356: *
357: * @see C14nSupport_ArchitectureDocument
358: * @since 2.0 EA2
359: */
360: public static final String CANONICALIZATION_SUPPORT = "com.sun.xml.internal.bind.c14n";
361:
362: /**
363: * Marshaller/Unmarshaller property to enable XOP processing.
364: *
365: * @since 2.0 EA2
366: */
367: public static final String ENABLE_XOP = "com.sun.xml.internal.bind.XOP";
368: }
|