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;
27
28 import java.io.IOException;
29 import java.util.Collections;
30 import java.util.List;
31
32 import com.sun.tools.internal.xjc.generator.bean.field.FieldRendererFactory;
33 import com.sun.tools.internal.xjc.model.CPluginCustomization;
34 import com.sun.tools.internal.xjc.model.Model;
35 import com.sun.tools.internal.xjc.outline.Outline;
36
37 import org.xml.sax.ErrorHandler;
38 import org.xml.sax.SAXException;
39
40 /**
41 * Add-on that works on the generated source code.
42 *
43 * <p>
44 * This add-on will be called after the default bean generation
45 * has finished.
46 *
47 * @author
48 * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
49 *
50 * @since
51 * JAXB RI 2.0 EA
52 */
53 public abstract class Plugin {
54
55 /**
56 * Gets the option name to turn on this add-on.
57 *
58 * <p>
59 * For example, if "abc" is returned, "-abc" will
60 * turn on this plugin. A plugin needs to be turned
61 * on explicitly, or else no other methods of {@link Plugin}
62 * will be invoked.
63 *
64 * <p>
65 * Starting 2.1, when an option matches the name returned
66 * from this method, XJC will then invoke {@link #parseArgument(Options, String[], int)},
67 * allowing plugins to handle arguments to this option.
68 */
69 public abstract String getOptionName();
70
71 /**
72 * Gets the description of this add-on. Used to generate
73 * a usage screen.
74 *
75 * @return
76 * localized description message. should be terminated by \n.
77 */
78 public abstract String getUsage();
79
80 /**
81 * Parses an option <code>args[i]</code> and augment
82 * the <code>opt</code> object appropriately, then return
83 * the number of tokens consumed.
84 *
85 * <p>
86 * The callee doesn't need to recognize the option that the
87 * getOptionName method returns.
88 *
89 * <p>
90 * Once a plugin is activated, this method is called
91 * for options that XJC didn't recognize. This allows
92 * a plugin to define additional options to customize
93 * its behavior.
94 *
95 * <p>
96 * Since options can appear in no particular order,
97 * XJC allows sub-options of a plugin to show up before
98 * the option that activates a plugin (one that's returned
99 * by {@link #getOptionName()}.
100 *
101 * But nevertheless a {@link Plugin} needs to be activated
102 * to participate in further processing.
103 *
104 * @return
105 * 0 if the argument is not understood.
106 * Otherwise return the number of tokens that are
107 * consumed, including the option itself.
108 * (so if you have an option like "-foo 3", return 2.)
109 * @exception BadCommandLineException
110 * If the option was recognized but there's an error.
111 * This halts the argument parsing process and causes
112 * XJC to abort, reporting an error.
113 */
114 public int parseArgument( Options opt, String[] args, int i ) throws BadCommandLineException, IOException {
115 return 0;
116 }
117
118 /**
119 * Returns the list of namespace URIs that are supported by this plug-in
120 * as schema annotations.
121 *
122 * <p>
123 * If a plug-in returns a non-empty list, the JAXB RI will recognize
124 * these namespace URIs as vendor extensions
125 * (much like "http://java.sun.com/xml/ns/jaxb/xjc"). This allows users
126 * to write those annotations inside a schema, or in external binding files,
127 * and later plug-ins can access those annotations as DOM nodes.
128 *
129 * <p>
130 * See <a href="http://java.sun.com/webservices/docs/1.5/jaxb/vendorCustomizations.html">
131 * http://java.sun.com/webservices/docs/1.5/jaxb/vendorCustomizations.html</a>
132 * for the syntax that users need to use to enable extension URIs.
133 *
134 * @return
135 * can be empty, be never be null.
136 */
137 public List<String> getCustomizationURIs() {
138 return Collections.emptyList();
139 }
140
141 /**
142 * Checks if the given tag name is a valid tag name for the customization element in this plug-in.
143 *
144 * <p>
145 * This method is invoked by XJC to determine if the user-specified customization element
146 * is really a customization or not. This information is used to pick the proper error message.
147 *
148 * <p>
149 * A plug-in is still encouraged to do the validation of the customization element in the
150 * {@link #run} method before using any {@link CPluginCustomization}, to make sure that it
151 * has proper child elements and attributes.
152 *
153 * @param nsUri
154 * the namespace URI of the element. Never null.
155 * @param localName
156 * the local name of the element. Never null.
157 */
158 public boolean isCustomizationTagName(String nsUri,String localName) {
159 return false;
160 }
161
162 /**
163 * Notifies a plugin that it's activated.
164 *
165 * <p>
166 * This method is called when a plugin is activated
167 * through the command line option (as specified by {@link #getOptionName()}.
168 *
169 * <p>
170 * This is a good opportunity to use
171 * {@link Options#setFieldRendererFactory(FieldRendererFactory, Plugin)}
172 * if a plugin so desires.
173 *
174 * <p>
175 * Noop by default.
176 *
177 * @since JAXB 2.0 EA4
178 */
179 public void onActivated(Options opts) throws BadCommandLineException {
180 // noop
181 }
182
183 /**
184 * Performs the post-processing of the {@link Model}.
185 *
186 * <p>
187 * This method is invoked after XJC has internally finished
188 * the model construction. This is a chance for a plugin to
189 * affect the way code generation is performed.
190 *
191 * <p>
192 * Compared to the {@link #run(Outline, Options, ErrorHandler)}
193 * method, this method allows a plugin to work at the higher level
194 * conceptually closer to the abstract JAXB model, as opposed to
195 * Java syntax level.
196 *
197 * <p>
198 * Note that this method is invoked only when a {@link Plugin}
199 * is activated.
200 *
201 * @param model
202 * The object that represents the classes/properties to
203 * be generated.
204 *
205 * @param errorHandler
206 * Errors should be reported to this handler.
207 *
208 * @since JAXB 2.0.2
209 */
210 public void postProcessModel(Model model, ErrorHandler errorHandler) {
211 // noop
212 }
213
214 /**
215 * Run the add-on.
216 *
217 * <p>
218 * This method is invoked after XJC has internally finished
219 * the code generation. Plugins can tweak some of the generated
220 * code (or add more code) by using {@link Outline} and {@link Options}.
221 *
222 * <p>
223 * Note that this method is invoked only when a {@link Plugin}
224 * is activated.
225 *
226 * @param outline
227 * This object allows access to various generated code.
228 *
229 * @param errorHandler
230 * Errors should be reported to this handler.
231 *
232 * @return
233 * If the add-on executes successfully, return true.
234 * If it detects some errors but those are reported and
235 * recovered gracefully, return false.
236 *
237 * @throws SAXException
238 * After an error is reported to {@link ErrorHandler}, the
239 * same exception can be thrown to indicate a fatal irrecoverable
240 * error. {@link ErrorHandler} itself may throw it, if it chooses
241 * not to recover from the error.
242 */
243 public abstract boolean run(
244 Outline outline, Options opt, ErrorHandler errorHandler ) throws SAXException ;
245 }