<?xml version="1.0" encoding="UTF-8"?>
<!--

DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright (c) 2012-2014 Oracle and/or its affiliates. All rights reserved.

The contents of this file are subject to the terms of either the GNU
General Public License Version 2 only ("GPL") or the Common Development
and Distribution License("CDDL") (collectively, the "License").  You
may not use this file except in compliance with the License.  You can
obtain a copy of the License at
http://glassfish.java.net/public/CDDL+GPL_1_1.html
or packager/legal/LICENSE.txt.  See the License for the specific
language governing permissions and limitations under the License.

When distributing the software, include this License Header Notice in each
file and include the License file at packager/legal/LICENSE.txt.

GPL Classpath Exception:
Oracle designates this particular file as subject to the "Classpath"
exception as provided by Oracle in the GPL Version 2 section of the License
file that accompanied this code.

Modifications:
If applicable, add the following below the License Header, with the fields
enclosed by brackets [] replaced by your own identifying information:
"Portions Copyright [year] [name of copyright owner]"

Contributor(s):
If you wish your version of this file to be governed by only the CDDL or
only the GPL Version 2, indicate your decision by adding "[Contributor]
elects to include this software in this distribution under the [CDDL or GPL
Version 2] license."  If you don't indicate a single choice of license, a
recipient has the option to distribute your version of this file under
either the CDDL, the GPL Version 2 or to extend the choice of license to
its licensees as provided above.  However, if you add GPL Version 2 code
and therefore, elected the GPL Version 2 license, then the option applies
only if the new code is made subject to such option by the copyright
holder.

        -->
<!DOCTYPE book [
<!ENTITY % ents SYSTEM "docbook.ent">
%ents;
]>
<section version="5.0"
         xml:id="deployment-migrating-jaxb-2-0-applications-to-javase-6"
         xml:lang="en" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:ns5="http://www.w3.org/1999/xhtml"
         xmlns:ns3="http://www.w3.org/2000/svg"
         xmlns:ns="http://docbook.org/ns/docbook"
         xmlns:m="http://www.w3.org/1998/Math/MathML">
    <title>Migrating JAXB 2.0 applications to JavaSE 6</title>

    <para>JavaSE 6 ships with its own JAXB 2.0 implementation. This
    implementation is based on the JAXB RI, where the only differences
    are:</para>

    <itemizedlist>
        <listitem>
            <para><emphasis role="bold">No RI-specific vendor extensions are
            supported:</emphasis> This is so that portability across different
            JavaSE 6 implementations will be guaranteed.</para>
        </listitem>

        <listitem>
            <para><emphasis role="bold">Code in JavaSE 6 is hosted in its own
            packages to avoid conflicts:</emphasis> This allows applications
            to continue to use a specific version of the JAXB RI that they
            choose to use.</para>
        </listitem>
    </itemizedlist>

    <para>Therefore, if you develop an application that uses JAXB 2.0 for
    JavaSE 5 today, the easiest way to upgrade to JavaSE 6 is to do nothing.
    You should keep the JAXB RI in your development environment, keep bundling
    the JAXB RI runtime jars to your app, just like you do that today.</para>

    <section xml:id="Reducing_footprint">
        <title>Reducing footprint</title>

        <para>If you'd like to reduce the footprint of your application by
        taking advantage of a JAXB implementation in JavaSE, you can take
        the following steps:</para>

        <orderedlist>
            <listitem>
                <para>You will no longer have to ship
                <filename>jaxb-api.jar</filename> in your application. This doesn't
                require any change to your code.</para>
            </listitem>

            <listitem>
                <para>If your application does not use any of the vendor
                extension features of the JAXB RI runtime (such as
                unmarshaller/marshaller properties whose names start with
                "<literal>com.sun.</literal>"), then you will no longer have to ship
                <filename>jaxb-impl.jar</filename> (nor <filename>jaxb1-impl.jar</filename>,
                <filename>jaxb-libs.jar</filename>.) When you do this, be sure to test
                your application since it's not very easy to find all such
                dependencies.</para>
            </listitem>
        </orderedlist>
    </section>

    <section xml:id="Using_JAXB_with_JavaSE">
        <title>Using JAXB with Java SE</title>

        <para>JavaSE comes with JAXB 2.x API/implementation in <literal>rt.jar</literal>. Each 
        version of JavaSE (6, 7, 8, ...) contains different version of JAXB 2.x 
        API. Therefore, if you want to use different version of JAXB API/implementation 
        than the one present in your version of JDK, you are required to override 
        a portion of <literal>rt.jar</literal> with the new API. There are 
        several ways to achieve this:</para>

        <orderedlist>
            <listitem>
                <para>
                    Place the <filename>jaxb-api.jar</filename> into
                    <code>$JRE_HOME/lib/endorsed</code>. <emphasis role="bold">Do not put other JAXB jars into the
                    endorsed directory.</emphasis> And put jaxb-impl, jaxb-core to classpath of your application.
                    This essentially makes your JRE to "JRE X + JAXB 2.y". This would
                    affect any other applications that use this JRE, and it's easy.
                    On the other hand, in various scenarios you may not be able to
                    alter the JRE.
                </para>
            </listitem>

            <listitem>
                <para>
                    Use the system property <literal>java.endorsed.dirs</literal> when you launch your application, and
                    have it point to the directory which contains the <filename>jaxb-api.jar</filename> only.
                    <emphasis role="bold">The directory must not contain any other jaxb artifacts (like jaxb-impl.jar or
                    jaxb-xjc.jar).</emphasis> This allows you use to use different version of JAXB for different
                    applications.
                </para>
            </listitem>

        </orderedlist>

        <para>No matter which approach you take, make sure not to include jar
        files other than <filename>jaxb-api.jar</filename>. Doing so, for example
        including <filename>jaxb-xjc.jar</filename>, may result in classloading
        related errors such as "taskdef A class needed by class
        com.sun.tools.xjc.XJCTask cannot be found:
        org/apache/tools/ant/...."</para>

        <para>See <link
        xlink:href="http://docs.oracle.com/javase/6/docs/technotes/guides/standards/">the
        endorsed directory mechanism</link> for more details.</para>
    </section>

    <section xml:id="Where_s_the_XJC_ant_task_">
        <title>Where's the XJC ant task?</title>

        <para>JavaSE has never shipped an Ant task implementation, so we are
        just following that tradition. There's an (process-wise) overhead of
        adding additional dependencies during the JavaSE build, and there
        would likely be some runtime dependency issues in having a class in
        <literal>tools.jar</literal> that would require the ant classes, due to
        class loader delegation.</para>

        <para>We are thinking about perhaps releasing a small jar that only
        contains the ant task for JDK6.</para>

        <para>Please also note that the syntax of <literal>&lt;xjc&gt;</literal> task is neither
        defined in the JAXB spec nor in the JavaSE spec. Therefore other
        JavaSE vendors may not implement that at all, or do so in a different
        class name, etc. Therefore, from a portability perspective, if you
        choose to depend on the <literal>&lt;xjc&gt;</literal> task you should bundle the JAXB
        RI.</para>
    </section>
</section>
