diff -r 88b85470e72c -r f50545b5e2f1 src/share/jaxws_classes/com/sun/xml/internal/bind/v2/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/jaxws_classes/com/sun/xml/internal/bind/v2/package-info.java Tue Mar 06 16:09:35 2012 -0800 @@ -0,0 +1,186 @@ +/* + * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/** + *
+ * This module provides code that implements {@link JAXBContext}. + * Roughly speaking the runtime works like this: + * + *
+ * The followings are the interesting pieces inside the runtime. + * + *
+ * The classes NOT in the {@link com.sun.xml.internal.bind.v2} package (and its subpackages) + * are also used by old JAXB 1.0 clients. + * + *
+ * "Model" is the portion of the code that represents JAXB-bound types. + * + *
+ * The following picture illustrates the relationship among major + * packages of the binding model. + * + *
+ * The core model contracts are all interfaces, and they are parameterized + * so that they can be used + * with different reflection libraries. This is necessary, as the model + * is used: + *
+ * This portion is used by all + * three running mode of JAXB. + * The corresponding base-level implementaion + * is also parameterized. + * + *
+ * The runtime model contract and implementation are used only at the run-time. + * These packages fix the parameterization to the Java reflection, + * and also exposes additional functionalities to actually do the + * unmarshalling/marshalling. These classes have "Runtime" prefix. + * + *
+ * Finally XJC has its own implementation of the contract in + * its own package. This package also fixes the parameterization + * to its own reflection library. + * + *
+ * When you work on the code, it is often helpful to know the layer you are in. + * + * + *
+ * The binding model design roughly looks like the following. + * For more details, see the javadoc of each component. + * + *
+ * Model construction happens inside {@link JAXBContext#newInstance(Class[])}. + * It's desirable for this step to be fast and consume less memory, + * but it's not too performance sensitive. + * + *
+ * Code that implements the unmarshaller and the marshaller OTOH + * needs to be very carefully written to achieve maximum sustaining + * performance. + * + * + * + * + *
+ * The following picture illustrates how the {@link JAXBContext#newInstance(Class[])} method + * triggers activities. + * + * {@SequenceDiagram + boxwid=1.2; + + pobject(U,"user"); + object(A,"JAXB API"); + object(CF,"ContextFactory"); + pobject(JC); + step(); + + message(U,A,"JAXBContext.newInstance()"); + active(A); + message(A,A,"locate JAXB RI 2.0"); + active(A); + step(); + inactive(A); + + message(A,CF,"createContext"); + active(CF); + + create_message(CF,JC,"c:JAXBContextImpl"); + active(JC); + + message(JC,JC,"build runtime model"); + message(JC,JC,"build JaxBeanInfos"); + inactive(JC); + + rmessage(A,U,"return c"); + inactive(CF); + inactive(A); + + complete(JC); + complete(CF); + complete(A); + * } + * + * @ArchitectureDocument + */ +package com.sun.xml.internal.bind.v2; + +import javax.xml.bind.JAXBContext; + +import com.sun.xml.internal.bind.v2.runtime.JAXBContextImpl;