/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package com.sun.tools.internal.xjc.api;

import javax.xml.stream.XMLStreamException;

import javax.xml.stream.XMLStreamReader;

import com.sun.istack.internal.NotNull;

import com.sun.tools.internal.xjc.Options;

import org.w3c.dom.Element;

import org.xml.sax.ContentHandler;

import org.xml.sax.EntityResolver;

import org.xml.sax.InputSource;

/**

 * Schema-to-Java compiler.

 *

 * <p>

 * The caller can parse multiple schema documents,

 * JAXB external binding files (or potentially WSDL

 * and JSR-109.next mapping files in the future).

 *

 * <p>

 * All the errors found during this process will be sent

 * to the registered {@link ErrorListener}.

 *

 * <p>

 * Once all the documents are parsed, call the {@link #bind()}

 * method to get the compiled {@link JAXBModel} object.

 *

 *

 * <h2>Tips: namespace URI -> package customization</h2>

 * <p>

 * The caller can feed the following synthesized schema

 * to achive the namespace URI -> Java package customization:

 * <pre><xmp>

 * <schema targetNamespace="xml.namespace.uri"

 *   xmlns="http://www.w3.org/2001/XMLSchema"

 *   xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"

 *   jaxb:version="1.0">

 *   <annotation><appinfo>

 *     <jaxb:schemaBindings>

 *       <jaxb:package name="java.package.name"/>

 *     </jaxb:schemaBindings>

 *   </appinfo></annotation>

 * </schema>

 * </xmp></pre>

 * Feed this synthesized schema document for each namespace URI

 * you need to map.

 *

 * @author

 *     Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)

 */

public interface SchemaCompiler {

    /**

     * Parses schemas or external bindings

     * through SAX events by feeding events into

     * SAX {@link ContentHandler}.

     *

     * @param systemId

     *      The system ID of the document to be read in.

     *

     * @see #parseSchema(String, XMLStreamReader)

     */

    ContentHandler getParserHandler( String systemId );

    /**

     * Parses a schema or an external binding file

     * from an external source.

     *

     * @param source

     *      Its system Id must be set to an absolute URI.

     */

    void parseSchema( InputSource source );

    /**

     * Specifies the target spec version for this compilaion.

     *

     * @param version

     *      If null, XJC will generate the source code that

     *      takes advantage of the latest JAXB spec that it understands.

     * @since 2.1 EA2

     */

    void setTargetVersion( SpecVersion version );

    /**

     * Parses a schema or an external binding file

     * from the specified DOM element.

     *

     * <p>

     * The given DOM element is treated as if it's the root of a

     * virtual document.

     *

     * <p>

     * XJC will not be able to print location information for

     * errors found in this document, since DOM doesn't have them.

     * For this reason, use of this method is strongly discouraged.

     *

     * @param systemId

     *      We need an absolute system ID that uniquely designates the virtual

     *      document. This should be different from the system ID of

     *      the document which contains this element.

     *      <p>

     *      One way to do that is by adding a fragment identifier

     *      to the system ID of the document. For example, if the document

     *      is "foo.wsdl" and you are passing in its types section, you

     *      can use an unique identifier like "foo.wsdl#types"

     */

    void parseSchema( String systemId, Element element );

    /**

     * Parses a schema or an external binding file

     * from the given source.

     *

     * <p>

     * A stream reader must be pointing at the element or

     * at the start of the document.

     * XML is parsed until the corresponding end tag, then the

     * sub tree is processed as a schema document.

     *

     * <p>

     * When this method returns successfully, the parser is at

     * the next token of the end element.

     *

     * @param systemId

     *      The absolute system ID of the document that is being parsed.

     *      This information is necessary to avoid double-inclusion

     *      and etc.

     *

     *      Note that {@link XMLStreamReader#getLocation()} only

     *      returns the system ID of the entity it is parsing, not

     *      necessarily the system ID of the document itself.

     *

     * @throws XMLStreamException

     *      If an error happens while parsing a document.

     *      Note that not only the parser but also the XJC itself

     *      may throw this error (as a result of the additional validation

     *      for example.)

     */

    void parseSchema( String systemId, XMLStreamReader reader ) throws XMLStreamException;

    void setErrorListener( ErrorListener errorListener );

    void setEntityResolver( EntityResolver entityResolver );

    /**

     * Sets the default Java package name into which the generated code will be placed.

     *

     * <p>

     * Customizations in the binding files/schemas will have precedence over this setting.

     * Set to null to use the default package name computation algorithm as specified by

     * the JAXB spec (which is the default behavior.)

     *

     * <p>

     * Initially this parameter is set to null.

     *

     * @param packageName

     *      Java pckage name such as "org.foo.bar". Use "" to represent the root package,

     *      and null to defer to the default computation algorithm.

     *

     * @see #forcePackageName(String)

     */

    void setDefaultPackageName( String packageName );

    /**

     * Forces all the JAXB-generated classes to go into the specific package.

     *

     * <p>

     * This setting takes precedence over the {@link #setDefaultPackageName(String)}

     * or any of the customization found in the JAXB binding files. This method

     * is designed to implement the semantics of the command-line '-p' option.

     *

     * <p>

     * This somewhat ugly semantics actually have a long history now and too late

     * to change.

     *

     * @see #setDefaultPackageName(String)

     */

    void forcePackageName( String packageName );

    /**

     * Sets the {@link ClassNameAllocator} to be used for the binding operation.

     *

     * <p>

     * This mechanism would allow the caller to participate in the binding operation.

     *

     * @see ClassNameAllocator

     */

    void setClassNameAllocator( ClassNameAllocator allocator );

    /**

     * Clears all the schema files parsed so far.

     *

     * @since 2.1.1

     */

    void resetSchema();

    /**

     * Obtains the compiled schema object model.

     *

     * Once this method is called, no other method should be

     * invoked on the {@link SchemaCompiler}.

     *

     * @return

     *      null if the compilation fails. The errors should have been

     *      delivered to the registered error handler in such a case.

     */

    S2JJAXBModel bind();

    /**

     * Allows the calling code to tweak more schema compilation details.

     *

     * <p>

     * The caller can use this method to obtain an {@link Options} instance,

     * then tweak settings on it. The updated settings will be used when the

     * {@link #bind()} method is invoked.

     *

     * <p>

     * The returned {@link Options} object is useful for example to specify

     * command-line arguments.

     *

     * @since 2.0.2

     * @deprecated

     *      This method is not really "deprecated" (in the sense of being removed

     *      from future versions), but the JAXB team is not committed to evolve

     *      {@link Options} class in the compatible fashion. So please don't

     *      use this method unless you know what you're doing.

     */

    @NotNull Options getOptions();

}