Thu, 31 Aug 2017 15:18:52 +0800
merge
aoqi@0 | 1 | /* |
aoqi@0 | 2 | * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. |
aoqi@0 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
aoqi@0 | 4 | * |
aoqi@0 | 5 | * This code is free software; you can redistribute it and/or modify it |
aoqi@0 | 6 | * under the terms of the GNU General Public License version 2 only, as |
aoqi@0 | 7 | * published by the Free Software Foundation. Oracle designates this |
aoqi@0 | 8 | * particular file as subject to the "Classpath" exception as provided |
aoqi@0 | 9 | * by Oracle in the LICENSE file that accompanied this code. |
aoqi@0 | 10 | * |
aoqi@0 | 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
aoqi@0 | 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
aoqi@0 | 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
aoqi@0 | 14 | * version 2 for more details (a copy is included in the LICENSE file that |
aoqi@0 | 15 | * accompanied this code). |
aoqi@0 | 16 | * |
aoqi@0 | 17 | * You should have received a copy of the GNU General Public License version |
aoqi@0 | 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
aoqi@0 | 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
aoqi@0 | 20 | * |
aoqi@0 | 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
aoqi@0 | 22 | * or visit www.oracle.com if you need additional information or have any |
aoqi@0 | 23 | * questions. |
aoqi@0 | 24 | */ |
aoqi@0 | 25 | |
aoqi@0 | 26 | /** |
aoqi@0 | 27 | * <h1>The JAXB 2.0 runtime</h1>. |
aoqi@0 | 28 | * |
aoqi@0 | 29 | * <h1>Overview</h1> |
aoqi@0 | 30 | * <p> |
aoqi@0 | 31 | * This module provides code that implements {@link JAXBContext}. |
aoqi@0 | 32 | * Roughly speaking the runtime works like this: |
aoqi@0 | 33 | * |
aoqi@0 | 34 | * <ol> |
aoqi@0 | 35 | * <li>There's a set of classes and interfaces that model JAXB-bound types. |
aoqi@0 | 36 | * You can think of this as a reflection library for JAXB. |
aoqi@0 | 37 | * <li>There's a set of classes that constitute the unmarshaller and marshaller. |
aoqi@0 | 38 | * Each class represents a small portion, and they are composed to perform |
aoqi@0 | 39 | * the operations. |
aoqi@0 | 40 | * <li>{@link JAXBContextImpl} builds itself by reading the model and |
aoqi@0 | 41 | * composing unmarshallers and marshallers. |
aoqi@0 | 42 | * </ol> |
aoqi@0 | 43 | * |
aoqi@0 | 44 | * <h1>Interesting Pieces inside Runtime</h1> |
aoqi@0 | 45 | * <p> |
aoqi@0 | 46 | * The followings are the interesting pieces inside the runtime. |
aoqi@0 | 47 | * |
aoqi@0 | 48 | * <dl> |
aoqi@0 | 49 | * <dt>{@link com.sun.xml.internal.bind.v2.model model} |
aoqi@0 | 50 | * <dd> |
aoqi@0 | 51 | * This set of classes and interfaces models JAXB-bound types. |
aoqi@0 | 52 | * |
aoqi@0 | 53 | * <dt>{@link com.sun.xml.internal.bind.v2.runtime XML I/O} |
aoqi@0 | 54 | * <dd> |
aoqi@0 | 55 | * This set of classes implements the JAXB API and provides the XML I/O functionality. |
aoqi@0 | 56 | * </dl> |
aoqi@0 | 57 | * |
aoqi@0 | 58 | * <p> |
aoqi@0 | 59 | * The classes <b>NOT</b> in the {@link com.sun.xml.internal.bind.v2} package (and its subpackages) |
aoqi@0 | 60 | * are also used by old JAXB 1.0 clients. |
aoqi@0 | 61 | * |
aoqi@0 | 62 | * <h1>Models</h1> |
aoqi@0 | 63 | * <p> |
aoqi@0 | 64 | * "Model" is the portion of the code that represents JAXB-bound types. |
aoqi@0 | 65 | * |
aoqi@0 | 66 | * <p> |
aoqi@0 | 67 | * The following picture illustrates the relationship among major |
aoqi@0 | 68 | * packages of the binding model. |
aoqi@0 | 69 | * |
aoqi@0 | 70 | * <div> |
aoqi@0 | 71 | * <img src="doc-files/packages.png"/> |
aoqi@0 | 72 | * </div> |
aoqi@0 | 73 | * |
aoqi@0 | 74 | * <p> |
aoqi@0 | 75 | * The core model contracts are all interfaces, and they are parameterized |
aoqi@0 | 76 | * so that they can be used |
aoqi@0 | 77 | * with different reflection libraries. This is necessary, as the model |
aoqi@0 | 78 | * is used: |
aoqi@0 | 79 | * <ol> |
aoqi@0 | 80 | * <li> at runtime to process loaded classes, |
aoqi@0 | 81 | * <li> at tool-time to process source files / class files, and |
aoqi@0 | 82 | * <li> at schema compile time to generate source code. |
aoqi@0 | 83 | * </ol> |
aoqi@0 | 84 | * They all use different reflection libraries. |
aoqi@0 | 85 | * |
aoqi@0 | 86 | * <p> |
aoqi@0 | 87 | * This portion is used by all |
aoqi@0 | 88 | * three running mode of JAXB. |
aoqi@0 | 89 | * <a href="model/impl/package-summary.html">The corresponding base-level implementaion</a> |
aoqi@0 | 90 | * is also parameterized. |
aoqi@0 | 91 | * |
aoqi@0 | 92 | * <p> |
aoqi@0 | 93 | * The runtime model contract and implementation are used only at the run-time. |
aoqi@0 | 94 | * These packages fix the parameterization to the Java reflection, |
aoqi@0 | 95 | * and also exposes additional functionalities to actually do the |
aoqi@0 | 96 | * unmarshalling/marshalling. These classes have "Runtime" prefix. |
aoqi@0 | 97 | * |
aoqi@0 | 98 | * <p> |
aoqi@0 | 99 | * Finally XJC has its own implementation of the contract in |
aoqi@0 | 100 | * its own package. This package also fixes the parameterization |
aoqi@0 | 101 | * to its own reflection library. |
aoqi@0 | 102 | * |
aoqi@0 | 103 | * <p> |
aoqi@0 | 104 | * When you work on the code, it is often helpful to know the layer you are in. |
aoqi@0 | 105 | * |
aoqi@0 | 106 | * |
aoqi@0 | 107 | * <p> |
aoqi@0 | 108 | * The binding model design roughly looks like the following. |
aoqi@0 | 109 | * For more details, see the javadoc of each component. |
aoqi@0 | 110 | * |
aoqi@0 | 111 | * <div> |
aoqi@0 | 112 | * <img src="doc-files/j2s_architecture.gif"/> |
aoqi@0 | 113 | * </div> |
aoqi@0 | 114 | * |
aoqi@0 | 115 | * <b><i>TODO: link to classes from above pictures</i></b> |
aoqi@0 | 116 | * |
aoqi@0 | 117 | * |
aoqi@0 | 118 | * <h3>Evolution Rules</h3> |
aoqi@0 | 119 | * None of the class in this package or below should be directly |
aoqi@0 | 120 | * referenced by the generated code. Hence they can be changed freely |
aoqi@0 | 121 | * from versions to versions. |
aoqi@0 | 122 | * |
aoqi@0 | 123 | * |
aoqi@0 | 124 | * |
aoqi@0 | 125 | * |
aoqi@0 | 126 | * <h1>Performance Characteristics</h1> |
aoqi@0 | 127 | * <p> |
aoqi@0 | 128 | * Model construction happens inside {@link JAXBContext#newInstance(Class[])}. |
aoqi@0 | 129 | * It's desirable for this step to be fast and consume less memory, |
aoqi@0 | 130 | * but it's not too performance sensitive. |
aoqi@0 | 131 | * |
aoqi@0 | 132 | * <p> |
aoqi@0 | 133 | * Code that implements the unmarshaller and the marshaller OTOH |
aoqi@0 | 134 | * needs to be very carefully written to achieve maximum sustaining |
aoqi@0 | 135 | * performance. |
aoqi@0 | 136 | * |
aoqi@0 | 137 | * |
aoqi@0 | 138 | * |
aoqi@0 | 139 | * |
aoqi@0 | 140 | * <h1>Bootstrap Sequence</h1> |
aoqi@0 | 141 | * <p> |
aoqi@0 | 142 | * The following picture illustrates how the {@link JAXBContext#newInstance(Class[])} method |
aoqi@0 | 143 | * triggers activities. |
aoqi@0 | 144 | * |
aoqi@0 | 145 | * {@SequenceDiagram |
aoqi@0 | 146 | boxwid=1.2; |
aoqi@0 | 147 | |
aoqi@0 | 148 | pobject(U,"user"); |
aoqi@0 | 149 | object(A,"JAXB API"); |
aoqi@0 | 150 | object(CF,"ContextFactory"); |
aoqi@0 | 151 | pobject(JC); |
aoqi@0 | 152 | step(); |
aoqi@0 | 153 | |
aoqi@0 | 154 | message(U,A,"JAXBContext.newInstance()"); |
aoqi@0 | 155 | active(A); |
aoqi@0 | 156 | message(A,A,"locate JAXB RI 2.0"); |
aoqi@0 | 157 | active(A); |
aoqi@0 | 158 | step(); |
aoqi@0 | 159 | inactive(A); |
aoqi@0 | 160 | |
aoqi@0 | 161 | message(A,CF,"createContext"); |
aoqi@0 | 162 | active(CF); |
aoqi@0 | 163 | |
aoqi@0 | 164 | create_message(CF,JC,"c:JAXBContextImpl"); |
aoqi@0 | 165 | active(JC); |
aoqi@0 | 166 | |
aoqi@0 | 167 | message(JC,JC,"build runtime model"); |
aoqi@0 | 168 | message(JC,JC,"build JaxBeanInfos"); |
aoqi@0 | 169 | inactive(JC); |
aoqi@0 | 170 | |
aoqi@0 | 171 | rmessage(A,U,"return c"); |
aoqi@0 | 172 | inactive(CF); |
aoqi@0 | 173 | inactive(A); |
aoqi@0 | 174 | |
aoqi@0 | 175 | complete(JC); |
aoqi@0 | 176 | complete(CF); |
aoqi@0 | 177 | complete(A); |
aoqi@0 | 178 | * } |
aoqi@0 | 179 | * |
aoqi@0 | 180 | * @ArchitectureDocument |
aoqi@0 | 181 | */ |
aoqi@0 | 182 | package com.sun.xml.internal.bind.v2; |