|
1 /* |
|
2 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. |
|
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 /** |
|
27 * <h1>The JAXB 2.0 runtime</h1>. |
|
28 * |
|
29 * <h1>Overview</h1> |
|
30 * <p> |
|
31 * This module provides code that implements {@link JAXBContext}. |
|
32 * Roughly speaking the runtime works like this: |
|
33 * |
|
34 * <ol> |
|
35 * <li>There's a set of classes and interfaces that model JAXB-bound types. |
|
36 * You can think of this as a reflection library for JAXB. |
|
37 * <li>There's a set of classes that constitute the unmarshaller and marshaller. |
|
38 * Each class represents a small portion, and they are composed to perform |
|
39 * the operations. |
|
40 * <li>{@link JAXBContextImpl} builds itself by reading the model and |
|
41 * composing unmarshallers and marshallers. |
|
42 * </ol> |
|
43 * |
|
44 * <h1>Interesting Pieces inside Runtime</h1> |
|
45 * <p> |
|
46 * The followings are the interesting pieces inside the runtime. |
|
47 * |
|
48 * <dl> |
|
49 * <dt>{@link com.sun.xml.internal.bind.v2.model model} |
|
50 * <dd> |
|
51 * This set of classes and interfaces models JAXB-bound types. |
|
52 * |
|
53 * <dt>{@link com.sun.xml.internal.bind.v2.runtime XML I/O} |
|
54 * <dd> |
|
55 * This set of classes implements the JAXB API and provides the XML I/O functionality. |
|
56 * </dl> |
|
57 * |
|
58 * <p> |
|
59 * The classes <b>NOT</b> in the {@link com.sun.xml.internal.bind.v2} package (and its subpackages) |
|
60 * are also used by old JAXB 1.0 clients. |
|
61 * |
|
62 * <h1>Models</h1> |
|
63 * <p> |
|
64 * "Model" is the portion of the code that represents JAXB-bound types. |
|
65 * |
|
66 * <p> |
|
67 * The following picture illustrates the relationship among major |
|
68 * packages of the binding model. |
|
69 * |
|
70 * <div> |
|
71 * <img src="doc-files/packages.png"/> |
|
72 * </div> |
|
73 * |
|
74 * <p> |
|
75 * The core model contracts are all interfaces, and they are parameterized |
|
76 * so that they can be used |
|
77 * with different reflection libraries. This is necessary, as the model |
|
78 * is used: |
|
79 * <ol> |
|
80 * <li> at runtime to process loaded classes, |
|
81 * <li> at tool-time to process source files / class files, and |
|
82 * <li> at schema compile time to generate source code. |
|
83 * </ol> |
|
84 * They all use different reflection libraries. |
|
85 * |
|
86 * <p> |
|
87 * This portion is used by all |
|
88 * three running mode of JAXB. |
|
89 * <a href="model/impl/package-summary.html">The corresponding base-level implementaion</a> |
|
90 * is also parameterized. |
|
91 * |
|
92 * <p> |
|
93 * The runtime model contract and implementation are used only at the run-time. |
|
94 * These packages fix the parameterization to the Java reflection, |
|
95 * and also exposes additional functionalities to actually do the |
|
96 * unmarshalling/marshalling. These classes have "Runtime" prefix. |
|
97 * |
|
98 * <p> |
|
99 * Finally XJC has its own implementation of the contract in |
|
100 * its own package. This package also fixes the parameterization |
|
101 * to its own reflection library. |
|
102 * |
|
103 * <p> |
|
104 * When you work on the code, it is often helpful to know the layer you are in. |
|
105 * |
|
106 * |
|
107 * <p> |
|
108 * The binding model design roughly looks like the following. |
|
109 * For more details, see the javadoc of each component. |
|
110 * |
|
111 * <div> |
|
112 * <img src="doc-files/j2s_architecture.gif"/> |
|
113 * </div> |
|
114 * |
|
115 * <b><i>TODO: link to classes from above pictures</i></b> |
|
116 * |
|
117 * |
|
118 * <h3>Evolution Rules</h3> |
|
119 * None of the class in this package or below should be directly |
|
120 * referenced by the generated code. Hence they can be changed freely |
|
121 * from versions to versions. |
|
122 * |
|
123 * |
|
124 * |
|
125 * |
|
126 * <h1>Performance Characteristics</h1> |
|
127 * <p> |
|
128 * Model construction happens inside {@link JAXBContext#newInstance(Class[])}. |
|
129 * It's desirable for this step to be fast and consume less memory, |
|
130 * but it's not too performance sensitive. |
|
131 * |
|
132 * <p> |
|
133 * Code that implements the unmarshaller and the marshaller OTOH |
|
134 * needs to be very carefully written to achieve maximum sustaining |
|
135 * performance. |
|
136 * |
|
137 * |
|
138 * |
|
139 * |
|
140 * <h1>Bootstrap Sequence</h1> |
|
141 * <p> |
|
142 * The following picture illustrates how the {@link JAXBContext#newInstance(Class[])} method |
|
143 * triggers activities. |
|
144 * |
|
145 * {@SequenceDiagram |
|
146 boxwid=1.2; |
|
147 |
|
148 pobject(U,"user"); |
|
149 object(A,"JAXB API"); |
|
150 object(CF,"ContextFactory"); |
|
151 pobject(JC); |
|
152 step(); |
|
153 |
|
154 message(U,A,"JAXBContext.newInstance()"); |
|
155 active(A); |
|
156 message(A,A,"locate JAXB RI 2.0"); |
|
157 active(A); |
|
158 step(); |
|
159 inactive(A); |
|
160 |
|
161 message(A,CF,"createContext"); |
|
162 active(CF); |
|
163 |
|
164 create_message(CF,JC,"c:JAXBContextImpl"); |
|
165 active(JC); |
|
166 |
|
167 message(JC,JC,"build runtime model"); |
|
168 message(JC,JC,"build JaxBeanInfos"); |
|
169 inactive(JC); |
|
170 |
|
171 rmessage(A,U,"return c"); |
|
172 inactive(CF); |
|
173 inactive(A); |
|
174 |
|
175 complete(JC); |
|
176 complete(CF); |
|
177 complete(A); |
|
178 * } |
|
179 * |
|
180 * @ArchitectureDocument |
|
181 */ |
|
182 package com.sun.xml.internal.bind.v2; |