1 /* 2 * Copyright (c) 1997, 2013, 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; | 1 /* 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. 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 javax.xml.bind.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 com.sun.xml.internal.bind.v2.runtime.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" alt=""> 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" alt=""> 113 * </div> 114 * 115 * <b><i>TODO: link to classes from above pictures</i></b> 116 * 117 * 118 * <h2>Evolution Rules</h2> 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 javax.xml.bind.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 javax.xml.bind.JAXBContext#newInstance(Class[])} method 143 * triggers activities. 144 * 145 * {@code 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 * It's part of ArchitectureDocument. 181 */ 182 package com.sun.xml.internal.bind.v2; |