001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036: package com.sun.tools.xjc;
037:
038: import java.io.IOException;
039: import java.util.Collections;
040: import java.util.List;
041:
042: import com.sun.tools.xjc.generator.bean.field.FieldRendererFactory;
043: import com.sun.tools.xjc.model.CPluginCustomization;
044: import com.sun.tools.xjc.model.Model;
045: import com.sun.tools.xjc.outline.Outline;
046:
047: import org.xml.sax.ErrorHandler;
048: import org.xml.sax.SAXException;
049:
050: /**
051: * Add-on that works on the generated source code.
052: *
053: * <p>
054: * This add-on will be called after the default bean generation
055: * has finished.
056: *
057: * @author
058: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
059: *
060: * @since
061: * JAXB RI 2.0 EA
062: */
063: public abstract class Plugin {
064:
065: /**
066: * Gets the option name to turn on this add-on.
067: *
068: * <p>
069: * For example, if "abc" is returned, "-abc" will
070: * turn on this plugin. A plugin needs to be turned
071: * on explicitly, or else no other methods of {@link Plugin}
072: * will be invoked.
073: *
074: * <p>
075: * Starting 2.1, when an option matches the name returned
076: * from this method, XJC will then invoke {@link #parseArgument(Options, String[], int)},
077: * allowing plugins to handle arguments to this option.
078: */
079: public abstract String getOptionName();
080:
081: /**
082: * Gets the description of this add-on. Used to generate
083: * a usage screen.
084: *
085: * @return
086: * localized description message. should be terminated by \n.
087: */
088: public abstract String getUsage();
089:
090: /**
091: * Parses an option <code>args[i]</code> and augment
092: * the <code>opt</code> object appropriately, then return
093: * the number of tokens consumed.
094: *
095: * <p>
096: * The callee doesn't need to recognize the option that the
097: * getOptionName method returns.
098: *
099: * <p>
100: * Once a plugin is activated, this method is called
101: * for options that XJC didn't recognize. This allows
102: * a plugin to define additional options to customize
103: * its behavior.
104: *
105: * <p>
106: * Since options can appear in no particular order,
107: * XJC allows sub-options of a plugin to show up before
108: * the option that activates a plugin (one that's returned
109: * by {@link #getOptionName().)
110: *
111: * But nevertheless a {@link Plugin} needs to be activated
112: * to participate in further processing.
113: *
114: * @return
115: * 0 if the argument is not understood.
116: * Otherwise return the number of tokens that are
117: * consumed, including the option itself.
118: * (so if you have an option like "-foo 3", return 2.)
119: * @exception BadCommandLineException
120: * If the option was recognized but there's an error.
121: * This halts the argument parsing process and causes
122: * XJC to abort, reporting an error.
123: */
124: public int parseArgument(Options opt, String[] args, int i)
125: throws BadCommandLineException, IOException {
126: return 0;
127: }
128:
129: /**
130: * Returns the list of namespace URIs that are supported by this plug-in
131: * as schema annotations.
132: *
133: * <p>
134: * If a plug-in returns a non-empty list, the JAXB RI will recognize
135: * these namespace URIs as vendor extensions
136: * (much like "http://java.sun.com/xml/ns/jaxb/xjc"). This allows users
137: * to write those annotations inside a schema, or in external binding files,
138: * and later plug-ins can access those annotations as DOM nodes.
139: *
140: * <p>
141: * See <a href="http://java.sun.com/webservices/docs/1.5/jaxb/vendorCustomizations.html">
142: * http://java.sun.com/webservices/docs/1.5/jaxb/vendorCustomizations.html</a>
143: * for the syntax that users need to use to enable extension URIs.
144: *
145: * @return
146: * can be empty, be never be null.
147: */
148: public List<String> getCustomizationURIs() {
149: return Collections.emptyList();
150: }
151:
152: /**
153: * Checks if the given tag name is a valid tag name for the customization element in this plug-in.
154: *
155: * <p>
156: * This method is invoked by XJC to determine if the user-specified customization element
157: * is really a customization or not. This information is used to pick the proper error message.
158: *
159: * <p>
160: * A plug-in is still encouraged to do the validation of the customization element in the
161: * {@link #run} method before using any {@link CPluginCustomization}, to make sure that it
162: * has proper child elements and attributes.
163: *
164: * @param nsUri
165: * the namespace URI of the element. Never null.
166: * @param localName
167: * the local name of the element. Never null.
168: */
169: public boolean isCustomizationTagName(String nsUri, String localName) {
170: return false;
171: }
172:
173: /**
174: * Notifies a plugin that it's activated.
175: *
176: * <p>
177: * This method is called when a plugin is activated
178: * through the command line option (as specified by {@link #getOptionName()}.
179: *
180: * <p>
181: * This is a good opportunity to use
182: * {@link Options#setFieldRendererFactory(FieldRendererFactory, Plugin)}
183: * if a plugin so desires.
184: *
185: * <p>
186: * Noop by default.
187: *
188: * @since JAXB 2.0 EA4
189: */
190: public void onActivated(Options opts)
191: throws BadCommandLineException {
192: // noop
193: }
194:
195: /**
196: * Performs the post-processing of the {@link Model}.
197: *
198: * <p>
199: * This method is invoked after XJC has internally finished
200: * the model construction. This is a chance for a plugin to
201: * affect the way code generation is performed.
202: *
203: * <p>
204: * Compared to the {@link #run(Outline, Options, ErrorHandler)}
205: * method, this method allows a plugin to work at the higher level
206: * conceptually closer to the abstract JAXB model, as opposed to
207: * Java syntax level.
208: *
209: * <p>
210: * Note that this method is invoked only when a {@link Plugin}
211: * is activated.
212: *
213: * @param model
214: * The object that represents the classes/properties to
215: * be generated.
216: *
217: * @param errorHandler
218: * Errors should be reported to this handler.
219: *
220: * @since JAXB 2.0.2
221: */
222: public void postProcessModel(Model model, ErrorHandler errorHandler) {
223: // noop
224: }
225:
226: /**
227: * Run the add-on.
228: *
229: * <p>
230: * This method is invoked after XJC has internally finished
231: * the code generation. Plugins can tweak some of the generated
232: * code (or add more code) by using {@link Outline} and {@link Options}.
233: *
234: * <p>
235: * Note that this method is invoked only when a {@link Plugin}
236: * is activated.
237: *
238: * @param outline
239: * This object allows access to various generated code.
240: *
241: * @param errorHandler
242: * Errors should be reported to this handler.
243: *
244: * @return
245: * If the add-on executes successfully, return true.
246: * If it detects some errors but those are reported and
247: * recovered gracefully, return false.
248: *
249: * @throws SAXException
250: * After an error is reported to {@link ErrorHandler}, the
251: * same exception can be thrown to indicate a fatal irrecoverable
252: * error. {@link ErrorHandler} itself may throw it, if it chooses
253: * not to recover from the error.
254: */
255: public abstract boolean run(Outline outline, Options opt,
256: ErrorHandler errorHandler) throws SAXException;
257: }
|