< prev index next >

src/java.xml.bind/share/classes/com/sun/xml/internal/bind/v2/package-info.java

Print this page


   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;
< prev index next >