1 /* |
1 /* |
2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
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 |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
26 /** |
26 /** |
27 * <h1>The JAXB 2.0 runtime</h1>. |
27 * <h1>The JAXB 2.0 runtime</h1>. |
28 * |
28 * |
29 * <h1>Overview</h1> |
29 * <h1>Overview</h1> |
30 * <p> |
30 * <p> |
31 * This module provides code that implements {@link JAXBContext}. |
31 * This module provides code that implements {@link javax.xml.bind.JAXBContext}. |
32 * Roughly speaking the runtime works like this: |
32 * Roughly speaking the runtime works like this: |
33 * |
33 * |
34 * <ol> |
34 * <ol> |
35 * <li>There's a set of classes and interfaces that model JAXB-bound types. |
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. |
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. |
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 |
38 * Each class represents a small portion, and they are composed to perform |
39 * the operations. |
39 * the operations. |
40 * <li>{@link JAXBContextImpl} builds itself by reading the model and |
40 * <li>{@link com.sun.xml.internal.bind.v2.runtime.JAXBContextImpl} builds itself by reading the model and |
41 * composing unmarshallers and marshallers. |
41 * composing unmarshallers and marshallers. |
42 * </ol> |
42 * </ol> |
43 * |
43 * |
44 * <h1>Interesting Pieces inside Runtime</h1> |
44 * <h1>Interesting Pieces inside Runtime</h1> |
45 * <p> |
45 * <p> |
66 * <p> |
66 * <p> |
67 * The following picture illustrates the relationship among major |
67 * The following picture illustrates the relationship among major |
68 * packages of the binding model. |
68 * packages of the binding model. |
69 * |
69 * |
70 * <div> |
70 * <div> |
71 * <img src="doc-files/packages.png"/> |
71 * <img src="doc-files/packages.png" alt=""> |
72 * </div> |
72 * </div> |
73 * |
73 * |
74 * <p> |
74 * <p> |
75 * The core model contracts are all interfaces, and they are parameterized |
75 * The core model contracts are all interfaces, and they are parameterized |
76 * so that they can be used |
76 * so that they can be used |
107 * <p> |
107 * <p> |
108 * The binding model design roughly looks like the following. |
108 * The binding model design roughly looks like the following. |
109 * For more details, see the javadoc of each component. |
109 * For more details, see the javadoc of each component. |
110 * |
110 * |
111 * <div> |
111 * <div> |
112 * <img src="doc-files/j2s_architecture.gif"/> |
112 * <img src="doc-files/j2s_architecture.gif" alt=""> |
113 * </div> |
113 * </div> |
114 * |
114 * |
115 * <b><i>TODO: link to classes from above pictures</i></b> |
115 * <b><i>TODO: link to classes from above pictures</i></b> |
116 * |
116 * |
117 * |
117 * |
118 * <h3>Evolution Rules</h3> |
118 * <h2>Evolution Rules</h2> |
119 * None of the class in this package or below should be directly |
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 |
120 * referenced by the generated code. Hence they can be changed freely |
121 * from versions to versions. |
121 * from versions to versions. |
122 * |
122 * |
123 * |
123 * |
124 * |
124 * |
125 * |
125 * |
126 * <h1>Performance Characteristics</h1> |
126 * <h1>Performance Characteristics</h1> |
127 * <p> |
127 * <p> |
128 * Model construction happens inside {@link JAXBContext#newInstance(Class[])}. |
128 * Model construction happens inside {@link javax.xml.bind.JAXBContext#newInstance(Class[])}. |
129 * It's desirable for this step to be fast and consume less memory, |
129 * It's desirable for this step to be fast and consume less memory, |
130 * but it's not too performance sensitive. |
130 * but it's not too performance sensitive. |
131 * |
131 * |
132 * <p> |
132 * <p> |
133 * Code that implements the unmarshaller and the marshaller OTOH |
133 * Code that implements the unmarshaller and the marshaller OTOH |
137 * |
137 * |
138 * |
138 * |
139 * |
139 * |
140 * <h1>Bootstrap Sequence</h1> |
140 * <h1>Bootstrap Sequence</h1> |
141 * <p> |
141 * <p> |
142 * The following picture illustrates how the {@link JAXBContext#newInstance(Class[])} method |
142 * The following picture illustrates how the {@link javax.xml.bind.JAXBContext#newInstance(Class[])} method |
143 * triggers activities. |
143 * triggers activities. |
144 * |
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 */ |
145 */ |
182 package com.sun.xml.internal.bind.v2; |
146 package com.sun.xml.internal.bind.v2; |