1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/jaxws_classes/com/sun/xml/internal/bind/v2/package-info.java Wed Apr 27 01:27:09 2016 +0800 1.3 @@ -0,0 +1,182 @@ 1.4 +/* 1.5 + * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +/** 1.30 + * <h1>The JAXB 2.0 runtime</h1>. 1.31 + * 1.32 + * <h1>Overview</h1> 1.33 + * <p> 1.34 + * This module provides code that implements {@link JAXBContext}. 1.35 + * Roughly speaking the runtime works like this: 1.36 + * 1.37 + * <ol> 1.38 + * <li>There's a set of classes and interfaces that model JAXB-bound types. 1.39 + * You can think of this as a reflection library for JAXB. 1.40 + * <li>There's a set of classes that constitute the unmarshaller and marshaller. 1.41 + * Each class represents a small portion, and they are composed to perform 1.42 + * the operations. 1.43 + * <li>{@link JAXBContextImpl} builds itself by reading the model and 1.44 + * composing unmarshallers and marshallers. 1.45 + * </ol> 1.46 + * 1.47 + * <h1>Interesting Pieces inside Runtime</h1> 1.48 + * <p> 1.49 + * The followings are the interesting pieces inside the runtime. 1.50 + * 1.51 + * <dl> 1.52 + * <dt>{@link com.sun.xml.internal.bind.v2.model model} 1.53 + * <dd> 1.54 + * This set of classes and interfaces models JAXB-bound types. 1.55 + * 1.56 + * <dt>{@link com.sun.xml.internal.bind.v2.runtime XML I/O} 1.57 + * <dd> 1.58 + * This set of classes implements the JAXB API and provides the XML I/O functionality. 1.59 + * </dl> 1.60 + * 1.61 + * <p> 1.62 + * The classes <b>NOT</b> in the {@link com.sun.xml.internal.bind.v2} package (and its subpackages) 1.63 + * are also used by old JAXB 1.0 clients. 1.64 + * 1.65 + * <h1>Models</h1> 1.66 + * <p> 1.67 + * "Model" is the portion of the code that represents JAXB-bound types. 1.68 + * 1.69 + * <p> 1.70 + * The following picture illustrates the relationship among major 1.71 + * packages of the binding model. 1.72 + * 1.73 + * <div> 1.74 + * <img src="doc-files/packages.png"/> 1.75 + * </div> 1.76 + * 1.77 + * <p> 1.78 + * The core model contracts are all interfaces, and they are parameterized 1.79 + * so that they can be used 1.80 + * with different reflection libraries. This is necessary, as the model 1.81 + * is used: 1.82 + * <ol> 1.83 + * <li> at runtime to process loaded classes, 1.84 + * <li> at tool-time to process source files / class files, and 1.85 + * <li> at schema compile time to generate source code. 1.86 + * </ol> 1.87 + * They all use different reflection libraries. 1.88 + * 1.89 + * <p> 1.90 + * This portion is used by all 1.91 + * three running mode of JAXB. 1.92 + * <a href="model/impl/package-summary.html">The corresponding base-level implementaion</a> 1.93 + * is also parameterized. 1.94 + * 1.95 + * <p> 1.96 + * The runtime model contract and implementation are used only at the run-time. 1.97 + * These packages fix the parameterization to the Java reflection, 1.98 + * and also exposes additional functionalities to actually do the 1.99 + * unmarshalling/marshalling. These classes have "Runtime" prefix. 1.100 + * 1.101 + * <p> 1.102 + * Finally XJC has its own implementation of the contract in 1.103 + * its own package. This package also fixes the parameterization 1.104 + * to its own reflection library. 1.105 + * 1.106 + * <p> 1.107 + * When you work on the code, it is often helpful to know the layer you are in. 1.108 + * 1.109 + * 1.110 + * <p> 1.111 + * The binding model design roughly looks like the following. 1.112 + * For more details, see the javadoc of each component. 1.113 + * 1.114 + * <div> 1.115 + * <img src="doc-files/j2s_architecture.gif"/> 1.116 + * </div> 1.117 + * 1.118 + * <b><i>TODO: link to classes from above pictures</i></b> 1.119 + * 1.120 + * 1.121 + * <h3>Evolution Rules</h3> 1.122 + * None of the class in this package or below should be directly 1.123 + * referenced by the generated code. Hence they can be changed freely 1.124 + * from versions to versions. 1.125 + * 1.126 + * 1.127 + * 1.128 + * 1.129 + * <h1>Performance Characteristics</h1> 1.130 + * <p> 1.131 + * Model construction happens inside {@link JAXBContext#newInstance(Class[])}. 1.132 + * It's desirable for this step to be fast and consume less memory, 1.133 + * but it's not too performance sensitive. 1.134 + * 1.135 + * <p> 1.136 + * Code that implements the unmarshaller and the marshaller OTOH 1.137 + * needs to be very carefully written to achieve maximum sustaining 1.138 + * performance. 1.139 + * 1.140 + * 1.141 + * 1.142 + * 1.143 + * <h1>Bootstrap Sequence</h1> 1.144 + * <p> 1.145 + * The following picture illustrates how the {@link JAXBContext#newInstance(Class[])} method 1.146 + * triggers activities. 1.147 + * 1.148 + * {@SequenceDiagram 1.149 + boxwid=1.2; 1.150 + 1.151 + pobject(U,"user"); 1.152 + object(A,"JAXB API"); 1.153 + object(CF,"ContextFactory"); 1.154 + pobject(JC); 1.155 + step(); 1.156 + 1.157 + message(U,A,"JAXBContext.newInstance()"); 1.158 + active(A); 1.159 + message(A,A,"locate JAXB RI 2.0"); 1.160 + active(A); 1.161 + step(); 1.162 + inactive(A); 1.163 + 1.164 + message(A,CF,"createContext"); 1.165 + active(CF); 1.166 + 1.167 + create_message(CF,JC,"c:JAXBContextImpl"); 1.168 + active(JC); 1.169 + 1.170 + message(JC,JC,"build runtime model"); 1.171 + message(JC,JC,"build JaxBeanInfos"); 1.172 + inactive(JC); 1.173 + 1.174 + rmessage(A,U,"return c"); 1.175 + inactive(CF); 1.176 + inactive(A); 1.177 + 1.178 + complete(JC); 1.179 + complete(CF); 1.180 + complete(A); 1.181 + * } 1.182 + * 1.183 + * @ArchitectureDocument 1.184 + */ 1.185 +package com.sun.xml.internal.bind.v2;