jaxb-ri/docs/release-documentation/src/docbook/users-guide-deployment-maven-coordinates.xml

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

    Copyright (c) 2018, 2021 Oracle and/or its affiliates. All rights reserved.

    This program and the accompanying materials are made available under the
    terms of the Eclipse Distribution License v. 1.0, which is available at
    http://www.eclipse.org/org/documents/edl-v10.php.

    SPDX-License-Identifier: BSD-3-Clause

-->

<!DOCTYPE book [
<!ENTITY % ents SYSTEM "docbook.ent">
%ents;
]>
<section version="5.0"
         xml:id="deployment-maven-coordinates"
         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>Using &binding.impl.name; with Maven</title>


    <section xml:id="Maven_artifacts">
        <title>Maven coordinates for &binding.impl.name; artifacts</title>
        <itemizedlist>
            <listitem>
                <para><emphasis role="bold">jakarta.xml.bind:jakarta.xml.bind-api:</emphasis> API classes for &binding.spec.name;.
                    Required to compile against &binding.spec.name;.</para>
            </listitem>
            <listitem>
                <para><emphasis role="bold">org.glassfish.jaxb:jaxb-runtime:</emphasis> Contains the main runtime used
                    for serialization and deserialization java objects to/from xml.</para>
            </listitem>
            <listitem>
                <para><emphasis role="bold">org.glassfish.jaxb:jaxb-xjc:</emphasis> Tool to generate &binding.spec.name; java sources
                    from XML representation.</para>
            </listitem>
            <listitem>
                <para><emphasis role="bold">org.glassfish.jaxb:jaxb-jxc:</emphasis> Tool to generate XML schema from
                    &binding.spec.name; java sources.</para>
            </listitem>
        </itemizedlist>
        <para>In general <literal>com.sun.xml.bind</literal> artifacts are supposed to be used instead.</para>
    </section>

    <section xml:id="Fat-jar">
        <title>JAXB RI bundles</title>
        <itemizedlist>
            <listitem>
                <para><emphasis role="bold">com.sun.xml.bind:jaxb-impl:</emphasis> &binding.impl.name; runtime jar.</para>
            </listitem>
            <listitem>
                <para><emphasis role="bold">com.sun.xml.bind:jaxb-xjc:</emphasis> Class generation tool jar.</para>
            </listitem>
            <listitem>
                <para><emphasis role="bold">com.sun.xml.bind:jaxb-jxc:</emphasis> Schema generation tool jar.</para>
            </listitem>
        </itemizedlist>
        <para>In contrast to <literal>org.glassfish.jaxb</literal> artifacts, these jars have all dependency classes included inside.
            </para>
    </section>

    <section xml:id="Binary-distribution">
        <title>Binary distribution</title>
        <itemizedlist>
            <listitem>
                <para><emphasis role="bold">com.sun.xml.bind:jaxb-ri:</emphasis> Zip distribution containing tooling
                    scripts and all dependency jars in one archive.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section xml:id="Api_and_runtime">
        <title>&binding.spec.name; API and Runtime</title>
        <para>
            Minimum requirement to compile is jakarta.xml.bind-api.jar. If a client application is running on an environment
            where &binding.spec.name;
            runtime is provided, <literal>jakarta.xml.bind-api.jar</literal> is all that is needed.
                <example><title>API only</title>

                <programlisting language="xml"><![CDATA[
                <!-- API -->
                <dependency>
                    <groupId>jakarta.xml.bind</groupId>
                    <artifactId>jakarta.xml.bind-api</artifactId>
                    <version>${jakarta.xml.bind-api.version}</version>
                </dependency>
             ]]></programlisting>
            </example></para>

        <para>
            If client application needs to include the runtime, e.g. running standalone on JavaSE
            <literal>jaxb-impl</literal> should be also included.
            <example><title>API + Runtime</title>

            <programlisting language="xml"><![CDATA[
                <!-- API -->
                <dependency>
                    <groupId>jakarta.xml.bind</groupId>
                    <artifactId>jakarta.xml.bind-api</artifactId>
                    <version>${jakarta.xml.bind-api.version}</version>
                </dependency>

                <!-- Runtime -->
                <dependency>
                    <groupId>com.sun.xml.bind</groupId>
                    <artifactId>jaxb-impl</artifactId>
                    <version>${impl.version}</version>
                </dependency>
    ]]></programlisting>
        </example></para>
    </section>


    <section xml:id="Jaxb_tooling">
        <title>Using &binding.impl.name; tools for java sources and XML schema generation</title>

        <para>
            To generate &binding.spec.name; classes from schema in Maven project, a community
            <link xlink:href="https://github.com/highsource/maven-jaxb2-plugin">maven-jaxb2-plugin</link> can be used.
            <example><title>Using maven-jaxb2-plugin</title>

                <programlisting language="xml"><![CDATA[
                <build>
                    <plugins>
                        <plugin>
                            <groupId>org.jvnet.jaxb2.maven2</groupId>
                            <artifactId>maven-jaxb2-plugin</artifactId>
                            <executions>
                                <execution>
                                    <id>generate</id>
                                    <goals>
                                        <goal>generate</goal>
                                    </goals>
                                </execution>
                            </executions>
                        </plugin>
                    </plugins>
                </build>
    ]]></programlisting>
            </example>
            See the <link xlink:href="https://github.com/highsource/maven-jaxb2-plugin">maven-jaxb2-plugin documentation</link> for configuration details.</para>

    <para>
        Alternatively to community plugins, there are tooling artifacts jaxb-xjc and jaxb-jxc,
        which can be used for
        java from XML schema generation and vice versa.
        <example><title>Using &binding.impl.name; tooling artifacts</title>

            <programlisting language="xml"><![CDATA[
            <!-- Tooling dependencies -->
            <dependency>
                <groupId>com.sun.xml.bind</groupId>
                <artifactId>jaxb-xjc</artifactId>
                <version>${xjc.version}</version>
            </dependency>
            <dependency>
                <groupId>com.sun.xml.bind</groupId>
                <artifactId>jaxb-jxc</artifactId>
                <version>${jxc.version}</version>
            </dependency>

            <!-- Invoke tooling API (Java 11) -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                    <!-- Generate java sources from schema -->
                    <execution>
                        <id>xjc</id>
                        <goals>
                            <goal>exec</goal>
                        </goals>
                        <configuration>
                            <executable>java</executable>
                            <arguments>
                                <argument>--module-path</argument>
                                <modulepath/>
                                <argument>-m</argument>
                                <argument>com.sun.tools.xjc</argument>
                                <argument>-p</argument>
                                <argument>com.example</argument>
                                <argument>-d</argument>
                                <argument>${project.build.directory}/generated-sources</argument>
                                <argument>${project.build.directory}/classes/schema.xsd</argument>
                            </arguments>
                        </configuration>
                    </execution>

                    <!-- Generate XML Schema from sources -->
                    <execution>
                        <id>jxc</id>
                        <goals>
                            <goal>exec</goal>
                        </goals>
                        <configuration>
                            <executable>java</executable>
                            <arguments>
                                <argument>--module-path</argument>
                                <modulepath/>
                                <argument>-m</argument>
                                <argument>com.sun.tools.jxc</argument>
                                <argument>-d</argument>
                                <argument>${project.build.directory}/generated-sources</argument>
                                <argument>${project.build.directory}/classes/com/example/Author.java</argument>
                                <argument>${project.build.directory}/classes/com/example/Book.java</argument>
                            </arguments>
                            <longModulepath>false</longModulepath>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
]]></programlisting>
        </example>
    See also <link linkend='schema-generation-invoking-schemagen-programatically'>xml schema compiler usage</link>.</para>

    <para>Where are schemagen and xjc command line scripts available in JavaSE prior to 11?
        These are included only in the <link linkend="Maven_artifacts">zip distribution.</link></para>
    </section>

</section>