aoqi@0: /* aoqi@0: * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: aoqi@0: /** aoqi@0: *

The JAXB 2.0 runtime

. aoqi@0: * aoqi@0: *

Overview

aoqi@0: *

aoqi@0: * This module provides code that implements {@link JAXBContext}. aoqi@0: * Roughly speaking the runtime works like this: aoqi@0: * aoqi@0: *

    aoqi@0: *
  1. There's a set of classes and interfaces that model JAXB-bound types. aoqi@0: * You can think of this as a reflection library for JAXB. aoqi@0: *
  2. There's a set of classes that constitute the unmarshaller and marshaller. aoqi@0: * Each class represents a small portion, and they are composed to perform aoqi@0: * the operations. aoqi@0: *
  3. {@link JAXBContextImpl} builds itself by reading the model and aoqi@0: * composing unmarshallers and marshallers. aoqi@0: *
aoqi@0: * aoqi@0: *

Interesting Pieces inside Runtime

aoqi@0: *

aoqi@0: * The followings are the interesting pieces inside the runtime. aoqi@0: * aoqi@0: *

aoqi@0: *
{@link com.sun.xml.internal.bind.v2.model model} aoqi@0: *
aoqi@0: * This set of classes and interfaces models JAXB-bound types. aoqi@0: * aoqi@0: *
{@link com.sun.xml.internal.bind.v2.runtime XML I/O} aoqi@0: *
aoqi@0: * This set of classes implements the JAXB API and provides the XML I/O functionality. aoqi@0: *
aoqi@0: * aoqi@0: *

aoqi@0: * The classes NOT in the {@link com.sun.xml.internal.bind.v2} package (and its subpackages) aoqi@0: * are also used by old JAXB 1.0 clients. aoqi@0: * aoqi@0: *

Models

aoqi@0: *

aoqi@0: * "Model" is the portion of the code that represents JAXB-bound types. aoqi@0: * aoqi@0: *

aoqi@0: * The following picture illustrates the relationship among major aoqi@0: * packages of the binding model. aoqi@0: * aoqi@0: *

aoqi@0: * aoqi@0: *
aoqi@0: * aoqi@0: *

aoqi@0: * The core model contracts are all interfaces, and they are parameterized aoqi@0: * so that they can be used aoqi@0: * with different reflection libraries. This is necessary, as the model aoqi@0: * is used: aoqi@0: *

    aoqi@0: *
  1. at runtime to process loaded classes, aoqi@0: *
  2. at tool-time to process source files / class files, and aoqi@0: *
  3. at schema compile time to generate source code. aoqi@0: *
aoqi@0: * They all use different reflection libraries. aoqi@0: * aoqi@0: *

aoqi@0: * This portion is used by all aoqi@0: * three running mode of JAXB. aoqi@0: * The corresponding base-level implementaion aoqi@0: * is also parameterized. aoqi@0: * aoqi@0: *

aoqi@0: * The runtime model contract and implementation are used only at the run-time. aoqi@0: * These packages fix the parameterization to the Java reflection, aoqi@0: * and also exposes additional functionalities to actually do the aoqi@0: * unmarshalling/marshalling. These classes have "Runtime" prefix. aoqi@0: * aoqi@0: *

aoqi@0: * Finally XJC has its own implementation of the contract in aoqi@0: * its own package. This package also fixes the parameterization aoqi@0: * to its own reflection library. aoqi@0: * aoqi@0: *

aoqi@0: * When you work on the code, it is often helpful to know the layer you are in. aoqi@0: * aoqi@0: * aoqi@0: *

aoqi@0: * The binding model design roughly looks like the following. aoqi@0: * For more details, see the javadoc of each component. aoqi@0: * aoqi@0: *

aoqi@0: * aoqi@0: *
aoqi@0: * aoqi@0: * TODO: link to classes from above pictures aoqi@0: * aoqi@0: * aoqi@0: *

Evolution Rules

aoqi@0: * None of the class in this package or below should be directly aoqi@0: * referenced by the generated code. Hence they can be changed freely aoqi@0: * from versions to versions. aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: *

Performance Characteristics

aoqi@0: *

aoqi@0: * Model construction happens inside {@link JAXBContext#newInstance(Class[])}. aoqi@0: * It's desirable for this step to be fast and consume less memory, aoqi@0: * but it's not too performance sensitive. aoqi@0: * aoqi@0: *

aoqi@0: * Code that implements the unmarshaller and the marshaller OTOH aoqi@0: * needs to be very carefully written to achieve maximum sustaining aoqi@0: * performance. aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: * aoqi@0: *

Bootstrap Sequence

aoqi@0: *

aoqi@0: * The following picture illustrates how the {@link JAXBContext#newInstance(Class[])} method aoqi@0: * triggers activities. aoqi@0: * aoqi@0: * {@SequenceDiagram aoqi@0: boxwid=1.2; aoqi@0: aoqi@0: pobject(U,"user"); aoqi@0: object(A,"JAXB API"); aoqi@0: object(CF,"ContextFactory"); aoqi@0: pobject(JC); aoqi@0: step(); aoqi@0: aoqi@0: message(U,A,"JAXBContext.newInstance()"); aoqi@0: active(A); aoqi@0: message(A,A,"locate JAXB RI 2.0"); aoqi@0: active(A); aoqi@0: step(); aoqi@0: inactive(A); aoqi@0: aoqi@0: message(A,CF,"createContext"); aoqi@0: active(CF); aoqi@0: aoqi@0: create_message(CF,JC,"c:JAXBContextImpl"); aoqi@0: active(JC); aoqi@0: aoqi@0: message(JC,JC,"build runtime model"); aoqi@0: message(JC,JC,"build JaxBeanInfos"); aoqi@0: inactive(JC); aoqi@0: aoqi@0: rmessage(A,U,"return c"); aoqi@0: inactive(CF); aoqi@0: inactive(A); aoqi@0: aoqi@0: complete(JC); aoqi@0: complete(CF); aoqi@0: complete(A); aoqi@0: * } aoqi@0: * aoqi@0: * @ArchitectureDocument aoqi@0: */ aoqi@0: package com.sun.xml.internal.bind.v2;