| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| package org.apache.myfaces.buildtools.maven2.plugin.builder.annotation; |
| |
| import java.lang.annotation.Documented; |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| |
| /** |
| * This annotation identifies a class as being a JSF component, an ancestor of |
| * one, or a template for one. |
| * <p> |
| * A JSF component is a concrete class that is a subclass of UIComponent, and |
| * is registered in a faces-config.xml file. It always implements the StateHolder |
| * interface, and typically has several properties that can be defined from a |
| * view file (jsp, facelets or other similar technology). |
| * <p> |
| * The myfaces-builder-plugin uses this annotation information to generate the |
| * correct faces-config.xml declarations, thus ensuring that the config declarations |
| * are consistent with the code. The plugin can also optionally use this information |
| * to generate JSP tag classes, and concrete UIComponent implementations. |
| * <p> |
| * This tag can be used in several ways: |
| * <ul> |
| * <li>To mark an interface as one that declares component properties. |
| * <li>To mark a class that will be used as a base class by other hand-written |
| * classes. |
| * <li>To mark a class as an actual concrete JSF Component class which should be |
| * registered as a component in faces-config etc. |
| * <li>To mark a class as a base class for which a concrete component subclass should |
| * be created using code generation. |
| * <li>To mark a class as a "template" from which a concrete component class should |
| * be created using code generation. |
| * </ul> |
| * Any class or interface marked with this annotation will also have its "metadata" |
| * stored in the metadata file that the builder plugin creates and stores in the |
| * META-INF directory of the processed project. |
| * <p> |
| * Note that a JSPProperty annotation (on a method) is not processed unless the class |
| * is marked with this JSPComponent annotation. |
| * |
| * <h2>Annotating an Interface</h2> |
| * |
| * When an interface is marked with this annotation, then classes which implement that |
| * interface and are themselves marked with this annotation inherit the JSFProperty |
| * settings declared on the methods in the interface. |
| * <p> |
| * This allows common groups of JSF properties to be defined as an interface, and each |
| * JSF component class that is expected to provide those properties simply declares that |
| * it implements that interface. The normal java compilation rules ensure that the concrete |
| * JSF component class implements all of the methods on the interface, and the builder |
| * plugin ensures that the inherited JSFProperty settings are used. |
| * |
| * <h2>Annotating an Abstract Base Class</h2> |
| * |
| * When an abstract class is marked with this annotation, and the name attribute is |
| * not set, then this is a base class that concrete components can extend. Any |
| * JSFProperty settings defined on this class are inherited by subclasses. |
| * |
| * <h2>Annotating a Concrete Component Class</h2> |
| * |
| * When a non-abstract class is marked with this annotation, and the name attribute |
| * is defined then an entry will be created in the generated faces-config.xml file |
| * marking this class as a component. |
| * <p> |
| * In addition, a JSP TagHandler class will be created using code-generation and an |
| * entry will be created in the generated .tld file so that the tag class can be |
| * used from JSP applications. |
| * |
| * <h2>Annotating a Class for Subclass Generation</h2> |
| * |
| * When an abstract class is marked with this annotation, the name attribute is |
| * defined, and the "clazz" attribute is defined then code-generation will be |
| * used to create a concrete UIComponent class which is a subclass of this class. |
| * The subclass will be registered in the generated faces-config.xml file, a |
| * JSP TagHandler class will be created and registered in the .tld file, etc. |
| * <p> |
| * Using code-generation to create a subclass allows automatic generation of |
| * the "boilerplate code" that is commonly needed for implementing component |
| * property getter/setter methods and the saveState/restoreState methods. |
| * <p> |
| * Any abstract property getter/setter methods on the annotated class will have |
| * the appropriate implementation automatically written for it in the new |
| * subclass. However the parent class can override this for any particular |
| * method simply by providing a concrete implementation of the method. |
| * |
| * <h2>Annotating a Class as a Component Template</h2> |
| * |
| * When an abstract class is marked with this annotation, the name attribute |
| * is set, the clazz attribute is set, and attribute template is set to "true" |
| * then code-generation will be used to create a new class that is a "copy" of |
| * the source code here. As for "subclass generation", any abstract methods will |
| * have an appropriate implementation generated. |
| * <p> |
| * This approach allows a component "template" to be written as a normal class |
| * (with the usual support tools provided by IDEs etc) while allowing the |
| * actual UIComponent classes to have a hierarchy that is completely under |
| * the control of the annotations. In particular, this is useful for generating |
| * components for a JSF specification implementation, which is very specific |
| * about the inheritance hierarchy of the standard component classes. |
| * <p> |
| * When using this "template" approach, the annotated class itself can (and |
| * probably should be) package-scoped. |
| * |
| * @author Leonardo Uribe (latest modification by $Author$) |
| * @version $Revision$ $Date$ |
| */ |
| @Documented |
| @Target(ElementType.TYPE) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface JSFComponent |
| { |
| /** |
| * The name of the component in a page. This is the name by which the |
| * component will be referenced by the used (the name used to register |
| * JSP TagHandlers for example). For example: "mycomp". |
| * <p> |
| * When a project is generating components that live in more than one |
| * namespace, then the name can optionally include a namespace prefix, |
| * for example "x:mycomp". |
| * <p> |
| * If a class is marked with the JSFComponent annotation, but does not |
| * define the name attribute then it is a "base class" that other |
| * UIComponent classes can extend (and therefore inherit any JSFProperty |
| * definitions from the base class), but is not a component that can be |
| * instantiated. |
| * <p> |
| * This property should never be set for an interface. |
| * <p> |
| * This property should only be set for an abstract class when code |
| * generation is expected to automatically create a component based on |
| * this one (ie when clazz and perhaps template are set). |
| * <p> |
| * This attribute is not inheritable. |
| */ |
| String name() default ""; |
| |
| /** |
| * The fully-qualified-name of a concrete component class. |
| * <p> |
| * This attribute is only relevant when "name" is also set, ie the |
| * annotation is indicating that a component is really being declared. |
| * <p> |
| * When this attribute is not defined then it is assumed that this |
| * annotated class is the actual component class. |
| * <p> |
| * When this attribute is set to something other than the name of the |
| * annotated class then the specified class is the one that the JSF |
| * component registration in faces-config.xml will refer to. And if that |
| * class does not exist in the classpath (which will normally be the |
| * case) then code-generation will be triggered to create it. |
| * <p> |
| * This attribute is not inheritable. |
| * <p> |
| * The doclet-annotation equivalent of this attribute is named "class". |
| */ |
| String clazz() default ""; |
| |
| /** |
| * The JSF Component Family that this component belongs to. |
| * <p> |
| * A UIComponent instance's "family" setting is used together with a "renderer-type" to |
| * find a renderer for the component (see method UIComponent.getRenderer). Each |
| * Renderer implementation is registered in a faces-config.xml file using a |
| * (component-family, renderer-type) pair. |
| * <p> |
| * If this attribute is not set then the builder plugin will look for a |
| * constant on the class with name COMPONENT_FAMILY. It is an error if a |
| * concrete component has no such setting (but the value can be inherited from an |
| * ancestor class). |
| */ |
| String family() default ""; |
| |
| /** |
| * The type string used to create new instances of this component. |
| * <p> |
| * Components are registered in faces-config.xml using this type value, and |
| * new instances are created via Application.createComponent(type). |
| * <p> |
| * If this attribute is not set, then the builder plugin will look for a |
| * constant on the class with name COMPONENT_TYPE. It is an error if a |
| * component has no such setting. |
| * <p> |
| * This should only be set on concrete component classes (or classes for which |
| * code generation creates a concrete component class). The attribute is |
| * not inheritable. |
| */ |
| String type() default ""; |
| |
| /** |
| * Define the renderer-type attribute that (together with "family") is used to |
| * look up a renderer for instances of a component. |
| * <p> |
| * See attribute "family" for more details. |
| * <p> |
| * If this attribute is not defined, the builder plugin looks for a constant |
| * on the class with name DEFAULT_RENDERER_TYPE. It is an error if a |
| * concrete component has no such setting (but the value can be inherited from an |
| * ancestor class). |
| * <p> |
| * This attribute is inheritable. |
| */ |
| String defaultRendererType() default ""; |
| |
| /** |
| * Indicate if the component is allowed to have other UIComponent instances |
| * as children (ie "nested within it" in a page). |
| * <p> |
| * This information can be inserted into .tld files and similar to present |
| * users with an error message if an attempt is made to define child |
| * components for a component that does not support them. |
| * <p> |
| * Code generation might also use this information to ensure that an exception |
| * is thrown if an attempt to add child components occurs at runtime. |
| * <p> |
| * Note that this is related to, but not quite the same as, the "bodyContent" |
| * attribute. That attribute prevents anything being nested inside the component |
| * in the page, while this prevents UIComponents being nested. |
| * |
| * ?? TODO: but in JSF1.2, isn't static text a transient child?? |
| * <p> |
| * This attribute is inheritable. |
| */ |
| boolean canHaveChildren() default false; |
| |
| /** |
| * TODO: this is hopefully unused, and can be deleted. |
| * <p> |
| * Indicate that this component should not be defined on faces-config.xml. |
| * Anyway, if this is true or false does not have any significative impact. |
| */ |
| boolean configExcluded() default false; |
| |
| /** |
| * The name of the JSP Tag class that should be generated for this component. |
| * <p> |
| * It is an error to set this attribute if the annotated class is not a |
| * concrete JSF component. |
| * <p> |
| * TODO: ? WHat happens if a class is a concrete component but this is not |
| * set? Is a tagClass name automatically created? Or is no tag class created? |
| */ |
| String tagClass() default ""; |
| |
| /** |
| * Tag super class that the generated tag class extends. |
| * <p> |
| * The generated tag class for this component may need to be a subclass of |
| * different tag base classes depending upon the type of this component. |
| * For example, the JSF standard provides the following tag classes: |
| * <ul> |
| * <li>UIComponentTag (the default tag base class) |
| * <li>UIComponentBodyTag, for tags that "need to process their tag bodies". |
| * Examples from the JSF standard are h:panelGrid, h:panelGroup, h:dataTable, |
| * h:column. |
| * </ul> |
| * <p> |
| * This is optional; when not defined, the standard UIComponentTag class is |
| * used. This is appropriate for most JSF components. |
| */ |
| String tagSuperclass() default ""; |
| |
| /** |
| * Indicate tag handler class used for this component on facelets. |
| * |
| */ |
| String tagHandler() default ""; |
| |
| /** |
| * Indicate if the element accept inner elements (JSP) or not (empty). |
| */ |
| String bodyContent() default ""; |
| |
| /** |
| * A Short description of the purpose of this UIComponent. |
| * <p> |
| * This information is output into the .tld and faces-config.xml files as help |
| * for users of this component, and may be displayed by IDEs and similar tools. |
| * <p> |
| * If not set, then the javadoc "summary" sentence for the class will be |
| * used. If there is no javadoc for the class then the description will be |
| * an empty string (but that will never happen, right?). |
| * <p> |
| * Note that tld or faces-config files also have a "long description" field. |
| * That value is always the complete javadoc for the component class. |
| * <p> |
| * This attribute is not inheritable. |
| */ |
| String desc() default ""; |
| |
| /** |
| * Serial UID to be put on class when generated. |
| * <p> |
| * This should be set only for "component template" code generation, ie |
| * where the superClass attribute is set. In this case, the generated |
| * class will have a serialVersionUID constant defined which is set to |
| * this value. |
| * <p> |
| * TODO: is this valid? Why can't the code-generation just add a |
| * serialUid value based upon what version of the template was used? |
| * Maybe because the template generates different stuff based upon |
| * what attributes are defined here? |
| */ |
| String serialuid() default ""; |
| |
| /** |
| * Interfaces that generated classes should implement. |
| * <p> |
| * Used only when "component template" code generation is used. When |
| * defined, then the generated class will implement the listed |
| * interfaces in addition to the interfaces that this annotated class |
| * implements. |
| */ |
| String implementz() default ""; |
| |
| /** |
| * Indicate if the pattern used to generate component class code is |
| * template (true) or subclass (false). |
| */ |
| boolean template() default false; |
| |
| /** |
| * The name of the default client event to be return on method |
| * ClientBehaviorHolder.getDefaultEventName(). This property is |
| * JSF 2.0 specific, and the component must implement |
| * javax.faces.component.behavior.ClientBehaviorHolder interface. |
| * |
| * @since 1.0.4 |
| */ |
| String defaultEventName() default ""; |
| |
| /** |
| * |
| * @since 1.0.5 |
| */ |
| boolean composite() default false; |
| } |