001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.internal.xjc.api;
027:
028: import javax.xml.stream.XMLStreamException;
029: import javax.xml.stream.XMLStreamReader;
030:
031: import com.sun.istack.internal.NotNull;
032: import com.sun.tools.internal.xjc.Options;
033:
034: import org.w3c.dom.Element;
035: import org.xml.sax.ContentHandler;
036: import org.xml.sax.EntityResolver;
037: import org.xml.sax.InputSource;
038:
039: /**
040: * Schema-to-Java compiler.
041: *
042: * <p>
043: * The caller can parse multiple schema documents,
044: * JAXB external binding files (or potentially WSDL
045: * and JSR-109.next mapping files in the future).
046: *
047: * <p>
048: * All the errors found during this process will be sent
049: * to the registered {@link ErrorListener}.
050: *
051: * <p>
052: * Once all the documents are parsed, call the {@link #bind()}
053: * method to get the compiled {@link JAXBModel} object.
054: *
055: *
056: * <h2>Tips: namespace URI -> package customization</h2>
057: * <p>
058: * The caller can feed the following synthesized schema
059: * to achive the namespace URI -> Java package customization:
060: * <pre><xmp>
061: * <schema targetNamespace="xml.namespace.uri"
062: * xmlns="http://www.w3.org/2001/XMLSchema"
063: * xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
064: * jaxb:version="1.0">
065: * <annotation><appinfo>
066: * <jaxb:schemaBindings>
067: * <jaxb:package name="java.package.name"/>
068: * </jaxb:schemaBindings>
069: * </appinfo></annotation>
070: * </schema>
071: * </xmp></pre>
072: * Feed this synthesized schema document for each namespace URI
073: * you need to map.
074: *
075: * @author
076: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
077: */
078: public interface SchemaCompiler {
079: /**
080: * Parses schemas or external bindings
081: * through SAX events by feeding events into
082: * SAX {@link ContentHandler}.
083: *
084: * @param systemId
085: * The system ID of the document to be read in.
086: *
087: * @see #parseSchema(String, XMLStreamReader)
088: */
089: ContentHandler getParserHandler(String systemId);
090:
091: /**
092: * Parses a schema or an external binding file
093: * from an external source.
094: *
095: * @param source
096: * Its system Id must be set to an absolute URI.
097: */
098: void parseSchema(InputSource source);
099:
100: /**
101: * Parses a schema or an external binding file
102: * from the specified DOM element.
103: *
104: * <p>
105: * The given DOM element is treated as if it's the root of a
106: * virtual document.
107: *
108: * <p>
109: * XJC will not be able to print location information for
110: * errors found in this document, since DOM doesn't have them.
111: * For this reason, use of this method is strongly discouraged.
112: *
113: * @param systemId
114: * We need an absolute system ID that uniquely designates the virtual
115: * document. This should be different from the system ID of
116: * the document which contains this element.
117: * <p>
118: * One way to do that is by adding a fragment identifier
119: * to the system ID of the document. For example, if the document
120: * is "foo.wsdl" and you are passing in its types section, you
121: * can use an unique identifier like "foo.wsdl#types"
122: */
123: void parseSchema(String systemId, Element element);
124:
125: /**
126: * Parses a schema or an external binding file
127: * from the given source.
128: *
129: * <p>
130: * A stream reader must be pointing at the element or
131: * at the start of the document.
132: * XML is parsed until the corresponding end tag, then the
133: * sub tree is processed as a schema document.
134: *
135: * <p>
136: * When this method returns successfully, the parser is at
137: * the next token of the end element.
138: *
139: * @param systemId
140: * The absolute system ID of the document that is being parsed.
141: * This information is necessary to avoid double-inclusion
142: * and etc.
143: *
144: * Note that {@link XMLStreamReader#getLocation()} only
145: * returns the system ID of the entity it is parsing, not
146: * necessarily the system ID of the document itself.
147: *
148: * @throws XMLStreamException
149: * If an error happens while parsing a document.
150: * Note that not only the parser but also the XJC itself
151: * may throw this error (as a result of the additional validation
152: * for example.)
153: */
154: void parseSchema(String systemId, XMLStreamReader reader)
155: throws XMLStreamException;
156:
157: void setErrorListener(ErrorListener errorListener);
158:
159: void setEntityResolver(EntityResolver entityResolver);
160:
161: /**
162: * Sets the default Java package name into which the generated code will be placed.
163: *
164: * <p>
165: * Customizations in the binding files/schemas will have precedence over this setting.
166: * Set to null to use the default package name computation algorithm as specified by
167: * the JAXB spec (which is the default behavior.)
168: *
169: * <p>
170: * Initially this parameter is set to null.
171: *
172: * @param packageName
173: * Java pckage name such as "org.foo.bar". Use "" to represent the root package,
174: * and null to defer to the default computation algorithm.
175: *
176: * @see #forcePackageName(String)
177: */
178: void setDefaultPackageName(String packageName);
179:
180: /**
181: * Forces all the JAXB-generated classes to go into the specific package.
182: *
183: * <p>
184: * This setting takes precedence over the {@link #setDefaultPackageName(String)}
185: * or any of the customization found in the JAXB binding files. This method
186: * is designed to implement the semantics of the command-line '-p' option.
187: *
188: * <p>
189: * This somewhat ugly semantics actually have a long history now and too late
190: * to change.
191: *
192: * @see #setDefaultPackageName(String)
193: */
194: void forcePackageName(String packageName);
195:
196: /**
197: * Sets the {@link ClassNameAllocator} to be used for the binding operation.
198: *
199: * <p>
200: * This mechanism would allow the caller to participate in the binding operation.
201: *
202: * @see ClassNameAllocator
203: */
204: void setClassNameAllocator(ClassNameAllocator allocator);
205:
206: /**
207: * Obtains the compiled schema object model.
208: *
209: * Once this method is called, no other method should be
210: * invoked on the {@link SchemaCompiler}.
211: *
212: * @return
213: * null if the compilation fails. The errors should have been
214: * delivered to the registered error handler in such a case.
215: */
216: S2JJAXBModel bind();
217:
218: /**
219: * Allows the calling code to tweak more schema compilation details.
220: *
221: * <p>
222: * The caller can use this method to obtain an {@link Options} instance,
223: * then tweak settings on it. The updated settings will be used when the
224: * {@link #bind()} method is invoked.
225: *
226: * @since 2.0.2
227: * @deprecated
228: * This method is not really "deprecated" (in the sense of being removed
229: * from future versions), but the JAXB team is not committed to evolve
230: * {@link Options} class in the compatible fashion. So please don't
231: * use this method unless you know what you're doing.
232: */
233: @NotNull
234: Options getOptions();
235: }
|