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;
027:
028: import java.io.IOException;
029: import java.util.Collections;
030: import java.util.List;
031:
032: import com.sun.tools.internal.xjc.generator.bean.field.FieldRendererFactory;
033: import com.sun.tools.internal.xjc.model.CPluginCustomization;
034: import com.sun.tools.internal.xjc.model.Model;
035: import com.sun.tools.internal.xjc.outline.Outline;
036:
037: import org.xml.sax.ErrorHandler;
038:
039: /**
040: * Add-on that works on the generated source code.
041: *
042: * <p>
043: * This add-on will be called after the default bean generation
044: * has finished.
045: *
046: * @author
047: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
048: *
049: * @since
050: * JAXB RI 2.0 EA
051: */
052: public abstract class Plugin {
053:
054: /**
055: * Gets the option name to turn on this add-on.
056: *
057: * <p>
058: * For example, if "abc" is returned, "-abc" will
059: * turn on this plugin. A plugin needs to be turned
060: * on explicitly, or else no other methods of {@link Plugin}
061: * will be invoked.
062: */
063: public abstract String getOptionName();
064:
065: /**
066: * Gets the description of this add-on. Used to generate
067: * a usage screen.
068: *
069: * @return
070: * localized description message. should be terminated by \n.
071: */
072: public abstract String getUsage();
073:
074: /**
075: * Parses an option <code>args[i]</code> and augment
076: * the <code>opt</code> object appropriately, then return
077: * the number of tokens consumed.
078: *
079: * <p>
080: * The callee doesn't need to recognize the option that the
081: * getOptionName method returns.
082: *
083: * <p>
084: * Once a plugin is activated, this method is called
085: * for options that XJC didn't recognize. This allows
086: * a plugin to define additional options to customize
087: * its behavior.
088: *
089: * <p>
090: * Since options can appear in no particular order,
091: * XJC allows sub-options of a plugin to show up before
092: * the option that activates a plugin (one that's returned
093: * by {@link #getOptionName().)
094: *
095: * But nevertheless a {@link Plugin} needs to be activated
096: * to participate in further processing.
097: *
098: * @return
099: * 0 if the argument is not understood.
100: * Otherwise return the number of tokens that are
101: * consumed, including the option itself.
102: * (so if you have an option like "-foo 3", return 2.)
103: * @exception BadCommandLineException
104: * If the option was recognized but there's an error.
105: * This halts the argument parsing process and causes
106: * XJC to abort, reporting an error.
107: */
108: public int parseArgument(Options opt, String[] args, int i)
109: throws BadCommandLineException, IOException {
110: return 0;
111: }
112:
113: /**
114: * Returns the list of namespace URIs that are supported by this plug-in
115: * as schema annotations.
116: *
117: * <p>
118: * If a plug-in returns a non-empty list, the JAXB RI will recognize
119: * these namespace URIs as vendor extensions
120: * (much like "http://java.sun.com/xml/ns/jaxb/xjc"). This allows users
121: * to write those annotations inside a schema, or in external binding files,
122: * and later plug-ins can access those annotations as DOM nodes.
123: *
124: * <p>
125: * See <a href="http://java.sun.com/webservices/docs/1.5/jaxb/vendorCustomizations.html">
126: * http://java.sun.com/webservices/docs/1.5/jaxb/vendorCustomizations.html</a>
127: * for the syntax that users need to use to enable extension URIs.
128: *
129: * @return
130: * can be empty, be never be null.
131: */
132: public List<String> getCustomizationURIs() {
133: return Collections.emptyList();
134: }
135:
136: /**
137: * Checks if the given tag name is a valid tag name for the customization element in this plug-in.
138: *
139: * <p>
140: * This method is invoked by XJC to determine if the user-specified customization element
141: * is really a customization or not. This information is used to pick the proper error message.
142: *
143: * <p>
144: * A plug-in is still encouraged to do the validation of the customization element in the
145: * {@link #run} method before using any {@link CPluginCustomization}, to make sure that it
146: * has proper child elements and attributes.
147: *
148: * @param nsUri
149: * the namespace URI of the element. Never null.
150: * @param localName
151: * the local name of the element. Never null.
152: */
153: public boolean isCustomizationTagName(String nsUri, String localName) {
154: return false;
155: }
156:
157: /**
158: * Notifies a plugin that it's activated.
159: *
160: * <p>
161: * This method is called when a plugin is activated
162: * through the command line option (as specified by {@link #getOptionName()}.
163: *
164: * <p>
165: * This is a good opportunity to use
166: * {@link Options#setFieldRendererFactory(FieldRendererFactory, Plugin)}
167: * if a plugin so desires.
168: *
169: * <p>
170: * Noop by default.
171: *
172: * @since JAXB 2.0 EA4
173: */
174: public void onActivated(Options opts)
175: throws BadCommandLineException {
176: // noop
177: }
178:
179: /**
180: * Performs the post-processing of the {@link Model}.
181: *
182: * <p>
183: * This method is invoked after XJC has internally finished
184: * the model construction. This is a chance for a plugin to
185: * affect the way code generation is performed.
186: *
187: * <p>
188: * Compared to the {@link #run(Outline, Options, ErrorHandler)}
189: * method, this method allows a plugin to work at the higher level
190: * conceptually closer to the abstract JAXB model, as opposed to
191: * Java syntax level.
192: *
193: * <p>
194: * Note that this method is invoked only when a {@link Plugin}
195: * is activated.
196: *
197: * @param model
198: * The object that represents the classes/properties to
199: * be generated.
200: *
201: * @param errorHandler
202: * Errors should be reported to this handler.
203: *
204: * @since JAXB 2.0.2
205: */
206: public void postProcessModel(Model model, ErrorHandler errorHandler) {
207: // noop
208: }
209:
210: /**
211: * Run the add-on.
212: *
213: * <p>
214: * This method is invoked after XJC has internally finished
215: * the code generation. Plugins can tweak some of the generated
216: * code (or add more code) by using {@link Outline} and {@link Options}.
217: *
218: * <p>
219: * Note that this method is invoked only when a {@link Plugin}
220: * is activated.
221: *
222: * @param outline
223: * This object allows access to various generated code.
224: *
225: * @param errorHandler
226: * Errors should be reported to this handler.
227: *
228: * @return
229: * If the add-on executes successfully, return true.
230: * If it detects some errors but those are reported and
231: * recovered gracefully, return false.
232: */
233: public abstract boolean run(Outline outline, Options opt,
234: ErrorHandler errorHandler);
235: }
|