ohair@286: /*
ohair@286:  * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
ohair@286:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ohair@286:  *
ohair@286:  * This code is free software; you can redistribute it and/or modify it
ohair@286:  * under the terms of the GNU General Public License version 2 only, as
ohair@286:  * published by the Free Software Foundation.  Oracle designates this
ohair@286:  * particular file as subject to the "Classpath" exception as provided
ohair@286:  * by Oracle in the LICENSE file that accompanied this code.
ohair@286:  *
ohair@286:  * This code is distributed in the hope that it will be useful, but WITHOUT
ohair@286:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ohair@286:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
ohair@286:  * version 2 for more details (a copy is included in the LICENSE file that
ohair@286:  * accompanied this code).
ohair@286:  *
ohair@286:  * You should have received a copy of the GNU General Public License version
ohair@286:  * 2 along with this work; if not, write to the Free Software Foundation,
ohair@286:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ohair@286:  *
ohair@286:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@286:  * or visit www.oracle.com if you need additional information or have any
ohair@286:  * questions.
ohair@286:  */
ohair@286: 
ohair@286: package javax.xml.bind;
ohair@286: 
ohair@286: import javax.xml.transform.Result;
ohair@286: import java.io.IOException;
ohair@286: 
ohair@286: /**
ohair@286:  * Controls where a JAXB implementation puts the generates
ohair@286:  * schema files.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * An implementation of this abstract class has to be provided by the calling
ohair@286:  * application to generate schemas.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * This is a class, not an interface so as to allow future versions to evolve
ohair@286:  * without breaking the compatibility.
ohair@286:  *
ohair@286:  * @author
ohair@286:  *     Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
ohair@286:  */
ohair@286: public abstract class SchemaOutputResolver {
ohair@286:     /**
ohair@286:      * Decides where the schema file (of the given namespace URI)
ohair@286:      * will be written, and return it as a {@link Result} object.
ohair@286:      *
ohair@286:      * <p>
ohair@286:      * This method is called only once for any given namespace.
ohair@286:      * IOW, all the components in one namespace is always written
ohair@286:      * into the same schema document.
ohair@286:      *
ohair@286:      * @param namespaceUri
ohair@286:      *      The namespace URI that the schema declares.
ohair@286:      *      Can be the empty string, but never be null.
ohair@286:      * @param suggestedFileName
ohair@286:      *      A JAXB implementation generates an unique file name (like "schema1.xsd")
ohair@286:      *      for the convenience of the callee. This name can be
ohair@286:      *      used for the file name of the schema, or the callee can just
ohair@286:      *      ignore this name and come up with its own name.
ohair@286:      *      This is just a hint.
ohair@286:      *
ohair@286:      * @return
ohair@286:      *      a {@link Result} object that encapsulates the actual destination
ohair@286:      *      of the schema.
ohair@286:      *
ohair@286:      *      If the {@link Result} object has a system ID, it must be an
ohair@286:      *      absolute system ID. Those system IDs are relativized by the caller and used
ohair@286:      *      for &lt;xs:import> statements.
ohair@286:      *
ohair@286:      *      If the {@link Result} object does not have a system ID, a schema
ohair@286:      *      for the namespace URI is generated but it won't be explicitly
ohair@286:      *      &lt;xs:import>ed from other schemas.
ohair@286:      *
ohair@286:      *      If {@code null} is returned, the schema generation for this
ohair@286:      *      namespace URI will be skipped.
ohair@286:      */
ohair@286:     public abstract Result createOutput( String namespaceUri, String suggestedFileName ) throws IOException;
ohair@286: }