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

    Copyright (c) 2012, 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="jaxb-ri-extensions-develop-plugins"
         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>Develop Plugins</title>

    <para>This document describes how to write an XJC plugin to extend the
    code generation of XJC.</para>

    <section xml:id="section-5151430285858327">
        <title>What Can A Plugin Do?</title>

        <para>An XJC plugin participates in the code generation from a schema.
        It can define its own customizations that users can use to control it,
        it can access the code that the JAXB RI generates, it can generate
        additional classes/methods/fields/annotations/comments, and it can
        also replace some of the pluggability points in the compilation
        process, such as XML name -&gt; Java name conversion.</para>

        <para>As a show case of what a plugin can do, take a look at plugins hosted at
        JAXB2-commons.</para>

        <section xml:id="section-909129508009087">
            <title>Quick Start</title>

            <para>To write a plugin, do the following simple steps.</para>

            <orderedlist>
                <listitem>
                    <para>Write a class, say, <literal>org.acme.MyPlugin</literal>
                    by extending <literal>com.sun.tools.xjc.Plugin</literal>. See
                    javadoc for how to implement methods.</para>
                </listitem>

                <listitem>
                    <para>Write the name of your plugin class in a text file
                    and put it as
                    <filename>/META-INF/services/com.sun.tools.xjc.Plugin</filename>
                    in your jar file.</para>
                </listitem>
            </orderedlist>

            <para>Users can then use your plugins by declaring an XJC ant task
            with your jar files.</para>

            <informalexample>
                <programlisting language="xml"><![CDATA[<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask">
    <classpath>
        <fileset dir="jaxb-ri/lib" includes="*.jar"/>
        <fileset dir="your-plugin" includes="*.jar"/>
    </classpath>
</taskdef>]]></programlisting>
            </informalexample>
        </section>

        <section xml:id="section-5979897283139746">
            <title>Resources</title>

            <para>Although we will do our best to maintain the compatibility
            of the interfaces, it is still subject to change at this
            point.</para>
        </section>
    </section>
</section>
