1 /* 2 * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.tools.internal.xjc.api; 27 28 import javax.xml.stream.XMLStreamException; 29 import javax.xml.stream.XMLStreamReader; 30 31 import com.sun.istack.internal.NotNull; 32 import com.sun.tools.internal.xjc.Options; 33 34 import org.w3c.dom.Element; 35 import org.xml.sax.ContentHandler; 36 import org.xml.sax.EntityResolver; 37 import org.xml.sax.InputSource; 38 39 /** 40 * Schema-to-Java compiler. 41 * 42 * <p> 43 * The caller can parse multiple schema documents, 44 * JAXB external binding files (or potentially WSDL 45 * and JSR-109.next mapping files in the future). 46 * 47 * <p> 48 * All the errors found during this process will be sent 49 * to the registered {@link ErrorListener}. 50 * 51 * <p> 52 * Once all the documents are parsed, call the {@link #bind()} 53 * method to get the compiled {@link JAXBModel} object. 54 * 55 * 56 * <h2>Tips: namespace URI {@code -> } package customization</h2> 57 * <p> 58 * The caller can feed the following synthesized schema 59 * to achive the namespace URI {@code -> } Java package customization: 60 * <pre>{@code 61 * <schema targetNamespace="xml.namespace.uri" 62 * xmlns="http://www.w3.org/2001/XMLSchema" 63 * xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" 64 * jaxb:version="1.0"> 65 * <annotation><appinfo> 66 * <jaxb:schemaBindings> 67 * <jaxb:package name="java.package.name"/> 68 * </jaxb:schemaBindings> 69 * </appinfo></annotation> 70 * </schema> 71 * }</pre> 72 * Feed this synthesized schema document for each namespace URI 73 * you need to map. 74 * 75 * @author 76 * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com) 77 */ 78 public interface SchemaCompiler { 79 /** 80 * Parses schemas or external bindings 81 * through SAX events by feeding events into 82 * SAX {@link ContentHandler}. 83 * 84 * @param systemId 85 * The system ID of the document to be read in. 86 * 87 * @see #parseSchema(String, XMLStreamReader) 88 */ 89 ContentHandler getParserHandler( String systemId ); 90 91 /** 92 * Parses a schema or an external binding file 93 * from an external source. 94 * 95 * @param source 96 * Its system Id must be set to an absolute URI. 97 */ 98 void parseSchema( InputSource source ); 99 100 /** 101 * Specifies the target spec version for this compilaion. 102 * 103 * @param version 104 * If null, XJC will generate the source code that 105 * takes advantage of the latest JAXB spec that it understands. 106 * @since 2.1 EA2 107 */ 108 void setTargetVersion( SpecVersion version ); 109 110 /** 111 * Parses a schema or an external binding file 112 * from the specified DOM element. 113 * 114 * <p> 115 * The given DOM element is treated as if it's the root of a 116 * virtual document. 117 * 118 * <p> 119 * XJC will not be able to print location information for 120 * errors found in this document, since DOM doesn't have them. 121 * For this reason, use of this method is strongly discouraged. 122 * 123 * @param systemId 124 * We need an absolute system ID that uniquely designates the virtual 125 * document. This should be different from the system ID of 126 * the document which contains this element. 127 * <p> 128 * One way to do that is by adding a fragment identifier 129 * to the system ID of the document. For example, if the document 130 * is "foo.wsdl" and you are passing in its types section, you 131 * can use an unique identifier like "foo.wsdl#types" 132 */ 133 void parseSchema( String systemId, Element element ); 134 135 /** 136 * Parses a schema or an external binding file 137 * from the given source. 138 * 139 * <p> 140 * A stream reader must be pointing at the element or 141 * at the start of the document. 142 * XML is parsed until the corresponding end tag, then the 143 * sub tree is processed as a schema document. 144 * 145 * <p> 146 * When this method returns successfully, the parser is at 147 * the next token of the end element. 148 * 149 * @param systemId 150 * The absolute system ID of the document that is being parsed. 151 * This information is necessary to avoid double-inclusion 152 * and etc. 153 * 154 * Note that {@link XMLStreamReader#getLocation()} only 155 * returns the system ID of the entity it is parsing, not 156 * necessarily the system ID of the document itself. 157 * 158 * @throws XMLStreamException 159 * If an error happens while parsing a document. 160 * Note that not only the parser but also the XJC itself 161 * may throw this error (as a result of the additional validation 162 * for example.) 163 */ 164 void parseSchema( String systemId, XMLStreamReader reader ) throws XMLStreamException; 165 166 void setErrorListener( ErrorListener errorListener ); 167 void setEntityResolver( EntityResolver entityResolver ); 168 169 170 /** 171 * Sets the default Java package name into which the generated code will be placed. 172 * 173 * <p> 174 * Customizations in the binding files/schemas will have precedence over this setting. 175 * Set to null to use the default package name computation algorithm as specified by 176 * the JAXB spec (which is the default behavior.) 177 * 178 * <p> 179 * Initially this parameter is set to null. 180 * 181 * @param packageName 182 * Java pckage name such as "org.foo.bar". Use "" to represent the root package, 183 * and null to defer to the default computation algorithm. 184 * 185 * @see #forcePackageName(String) 186 */ 187 void setDefaultPackageName( String packageName ); 188 189 /** 190 * Forces all the JAXB-generated classes to go into the specific package. 191 * 192 * <p> 193 * This setting takes precedence over the {@link #setDefaultPackageName(String)} 194 * or any of the customization found in the JAXB binding files. This method 195 * is designed to implement the semantics of the command-line '-p' option. 196 * 197 * <p> 198 * This somewhat ugly semantics actually have a long history now and too late 199 * to change. 200 * 201 * @see #setDefaultPackageName(String) 202 */ 203 void forcePackageName( String packageName ); 204 205 /** 206 * Sets the {@link ClassNameAllocator} to be used for the binding operation. 207 * 208 * <p> 209 * This mechanism would allow the caller to participate in the binding operation. 210 * 211 * @see ClassNameAllocator 212 */ 213 void setClassNameAllocator( ClassNameAllocator allocator ); 214 215 /** 216 * Clears all the schema files parsed so far. 217 * 218 * @since 2.1.1 219 */ 220 void resetSchema(); 221 222 /** 223 * Obtains the compiled schema object model. 224 * 225 * Once this method is called, no other method should be 226 * invoked on the {@link SchemaCompiler}. 227 * 228 * @return 229 * null if the compilation fails. The errors should have been 230 * delivered to the registered error handler in such a case. 231 */ 232 S2JJAXBModel bind(); 233 234 /** 235 * Allows the calling code to tweak more schema compilation details. 236 * 237 * <p> 238 * The caller can use this method to obtain an {@link Options} instance, 239 * then tweak settings on it. The updated settings will be used when the 240 * {@link #bind()} method is invoked. 241 * 242 * <p> 243 * The returned {@link Options} object is useful for example to specify 244 * command-line arguments. 245 * 246 * @since 2.0.2 247 * @deprecated 248 * This method is not really "deprecated" (in the sense of being removed 249 * from future versions), but the JAXB team is not committed to evolve 250 * {@link Options} class in the compatible fashion. So please don't 251 * use this method unless you know what you're doing. 252 */ 253 @NotNull Options getOptions(); 254 }