Author: alexsmirnov
Date: 2011-03-16 19:11:06 -0400 (Wed, 16 Mar 2011)
New Revision: 22245
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Alias.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Attribute.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Description.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Event.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/EventName.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Facet.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Function.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehavior.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehaviorRenderer.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfComponent.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfConverter.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfRenderer.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfValidator.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/RendererSpecificComponent.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Tag.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagLibrary.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagType.java
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/package-info.java
Log:
RESOLVED - issue RFPL-1347: CDK architecture: Annotations javadoc
https://issues.jboss.org/browse/RFPL-1347
Modified: trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Alias.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Alias.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Alias.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,7 +28,7 @@
/**
* <p class="changed_added_4_0">
- * Attribute aliases. CDK will generate getters/setters for these aliases which delegate
calls to the original attribute
+ * Attribute aliases. CDK will generate getter and setter methods for these aliases which
delegate calls to the original attribute
* methods.
* </p>
*
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Attribute.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Attribute.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Attribute.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -29,8 +29,12 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.component.behavior.ClientBehavior;
+import javax.faces.el.MethodBinding;
+
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Used to define Java class field or bean
property getter method as JSF attribute.
+ * It used on the abstract method, all necessary code for attribute, including state
save/restore code, will be generated by CDK.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -42,7 +46,7 @@
public @interface Attribute {
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Restricts attribute to literal values
only ( no EL expressions ).
* </p>
*
* @return
@@ -50,7 +54,7 @@
boolean literal() default false;
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Tells CDK to not include attribute in
the VDL tag.
* </p>
*
* @return
@@ -58,7 +62,7 @@
boolean hidden() default false;
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Marks attribute as read-only ( no
setter method ).
* </p>
*
* @return
@@ -68,26 +72,59 @@
// boolean transient() default false;
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">If true, attribute used as pass
through html attribue, eg. rendered directly into html
+ * without any transformations.
* </p>
*
* @return
*/
boolean passThrough() default false;
+ /**
+ * <p class="changed_added_4_0">Marks attribute as required.
Generated tag handler should check its presence.</p>
+ * @return
+ */
boolean required() default false;
+ /**
+ * <p class="changed_added_4_0">Tells CDK to generate getter and
setter for attribute.</p>
+ * @return
+ */
boolean generate() default true;
+ /**
+ * <p class="changed_added_4_0">Attribute default value. Should be
valid Java code that can be used in field initialiser of function call.</p>
+ * @return
+ */
String defaultValue() default "";
+ /**
+ * <p class="changed_added_4_0">Used by IDE to suggest attribute
value.</p>
+ * @return
+ */
String suggestedValue() default "";
+ /**
+ * <p class="changed_added_4_0">Attribute description to include in
generated faces-config.xml and taglibs.</p>
+ * @return
+ */
Description description() default @Description();
+ /**
+ * <p class="changed_added_4_0">Method signature for attributes with
EL method reference type, either {@link MethodBinding} or {@link
MethodExpression}.</p>
+ * @return
+ */
Signature signature() default @Signature(returnType=Signature.NONE.class);
+ /**
+ * <p class="changed_added_4_0">Event descriptions for {@link
ClientBehavior} binding.</p>
+ * @return
+ */
EventName[] events() default {};
+ /**
+ * <p class="changed_added_4_0">Attribute aliases.</p>
+ * @return
+ */
Alias[] aliases() default {};
}
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Description.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Description.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Description.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -25,7 +25,7 @@
/**
* <p class="changed_added_4_0">
- * Description used that would be used in IDE to display.
+ * Object or attribute description. Included into generated faces-config.xml or tag
library, so it can be used by IDE.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -35,7 +35,7 @@
public static final String NAME =
"org.richfaces.cdk.annotations.Description";
/**
- * <p class="changed_added_4_0">Long description of the
object.</p>
+ * <p class="changed_added_4_0">Long description of the object. If
omited, javadoc comment for associated Java element.</p>
* @return
*/
public String value() default "";
@@ -50,7 +50,7 @@
/**
* <p class="changed_added_4_0">
- * URL that defines IDE icon.
+ * URL that defines small IDE icon.
* </p>
*
* @return Description url.
@@ -58,7 +58,9 @@
public String smallIcon() default "";
/**
- * <p class="changed_added_4_0"></p>
+ * <p class="changed_added_4_0">
+ * URL that defines large IDE icon.
+ * </p>
* @return
*/
public String largeIcon() default "";
Modified: trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Event.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Event.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Event.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -38,7 +38,7 @@
* <ul>
* <li>Event listener interface</li>
* <li>Event source interface</li>
- * <li>Event tag handler and binding wrapper.</li>
+ * <li>Listener tag handler and wrapper to bind listener to the
EL-expression.</li>
* </ul>
* </p>
*
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/EventName.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/EventName.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/EventName.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -29,8 +29,10 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.component.behavior.ClientBehavior;
+
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Description of client-side event that can
be associated with {@link ClientBehavior}.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -42,7 +44,7 @@
public @interface EventName {
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Event name ( click,change,mouseover
... ).
* </p>
*
* @return
@@ -50,7 +52,7 @@
public String value() default "";
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Defines default event. There should
be only one default event per component.
* </p>
*
* @return
Modified: trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Facet.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Facet.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Facet.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -29,8 +29,10 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.component.UIComponent;
+
/**
- * <p class="changed_added_4_0">
+ * <p class="changed_added_4_0">Describes facet of {@link UIComponent}.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -50,19 +52,19 @@
* @return
*/
/**
- * <p class="changed_added_4_0"></p>
+ * <p class="changed_added_4_0">Facet name</p>
* @return
*/
String name() default "";
/**
- * <p class="changed_added_4_0"></p>
+ * <p class="changed_added_4_0">If true, getter and setter methods
for this facet will be generated.</p>
* @return
*/
boolean generate() default true;
/**
- * <p class="changed_added_4_0"></p>
+ * <p class="changed_added_4_0">Facet description.</p>
* @return
*/
Description description() default @Description;
Modified: trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Function.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Function.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Function.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -40,13 +40,13 @@
public Description description() default @Description();
/**
- * <p class="changed_added_4_0">Function n</p>
+ * <p class="changed_added_4_0">EL-function name</p>
* @return
*/
public String name() default "";
/**
- * <p class="changed_added_4_0">Tag library for include given
function</p>
+ * <p class="changed_added_4_0">Tag library for which given function
will be included.</p>
* @return
*/
public TagType type() default TagType.Facelets;
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehavior.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehavior.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehavior.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,8 +28,13 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.component.behavior.ClientBehavior;
+import javax.faces.convert.Converter;
+
/**
* <p class="changed_added_4_0">
+ * This annotation defines concrete class as JSF {@link ClientBehavior}, or abstract
class as the base for generated
+ * Behavior implementation.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -50,10 +55,28 @@
*/
public String id() default "";
+ /**
+ * <p class="changed_added_4_0">
+ * fully qualified class name of the generated Behavior implementation. Default value
means nothing to genrate from concrete class,
+ * or infer name by convention for abstract class.</p>
+ * </p>
+ * @return
+ */
public String generate() default "";
+ /**
+ * <p class="changed_added_4_0">
+ * Tag description. If generated tags require special handlers, provide separate
description for every type of tag, JSP and Facelets.
+ * Otherwise, the only one tag tag description with name and type {@link
TagType#All}.
+ * </p>
+ * @return
+ */
public Tag[] tag() default {};
+ /**
+ * <p class="changed_added_4_0">Renderer associated with generated
{@link ClientBehavior}</p>
+ * @return
+ */
public JsfBehaviorRenderer renderer() default @JsfBehaviorRenderer();
/**
* <p class="changed_added_4_0">
@@ -67,11 +90,10 @@
/**
* <p class="changed_added_4_0">
- * defines fragments of faces-config.xml that contain standard attribute definitions.
CDK also tries to read
- * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces, therefore it is not
- * necessary to explicit include definitions for UIComponent and any other standard
JSF classes. CDK defines couple
- * of its own "urn" namespaces: "urn:resource:" for classpath
resources, "urn:config:" for for project configuration
- * folder and "urn:attributes:" for META-INF/cdk/attributes/ in the
annotations library.
+ * Defines file names for fragment of faces-config.xml that contain standard
attribute definitions. All names relative to the
+ * META-INF/cdk/attributes/ folder in classpath. CDK also tries to read
+ * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces. Therefore, it is not
+ * necessary to explicitly include definitions for Converter and any other standard
JSF classes.
* </p>
*
* @return
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehaviorRenderer.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehaviorRenderer.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfBehaviorRenderer.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,10 +28,14 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.component.behavior.ClientBehavior;
+import javax.faces.render.ClientBehaviorRenderer;
+import javax.faces.render.RenderKit;
import javax.faces.render.RenderKitFactory;
/**
- * <p class="changed_added_4_0"></p>
+ * <p class="changed_added_4_0">Defines annotated class as JSF {@link
ClientBehaviorRenderer}, or, if used in the {@link JsfBehavior} annotation,
+ * defines renderer type for {@link ClientBehavior}.</p>
* @author asmirnov(a)exadel.com
*
*/
@@ -39,12 +43,28 @@
@Target(ElementType.TYPE)
public @interface JsfBehaviorRenderer {
+ /**
+ * <p class="changed_added_4_0">ClientBehavior renderer
type.</p>
+ * @return
+ */
public String type() default "";
+ /**
+ * <p class="changed_added_4_0">Defines {@link RenderKit} for which
generated renderer is belong to.</p>
+ * @return
+ */
public String renderKitId() default RenderKitFactory.HTML_BASIC_RENDER_KIT;
+ /**
+ * <p class="changed_added_4_0">Fully qualified class name of the
generated renderer class.</p>
+ * @return
+ */
public String generate() default "";
+ /**
+ * <p class="changed_added_4_0">Renderer description to include into
generated faces-config.xml</p>
+ * @return
+ */
public Description description() default @Description();
}
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfComponent.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfComponent.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfComponent.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,12 +28,6 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-import javax.faces.component.UICommand;
-import javax.faces.component.UIComponentBase;
-import javax.faces.component.UIInput;
-import javax.faces.component.html.HtmlCommandButton;
-import javax.faces.component.html.HtmlCommandLink;
-import javax.faces.event.FacesEvent;
/**
* <p class="changed_added_4_0">
@@ -70,7 +64,7 @@
/**
* <p class="changed_added_4_0">
- * Component family. For default value, it is inferred from the COMPONENT_FAMILY
constant or by naming
+ * Component family. For default value, it could be got from the COMPONENT_FAMILY
constant or by inferred naming
* conventions.
* </p>
*
@@ -80,7 +74,8 @@
/**
* <p class="changed_added_4_0">
- * Name of the generated component implementation class.
+ * Name of the generated component implementation class. Default value means nothing
to genrate from concrete class,
+ * or infer name by convention for abstract class.
* </p>
*
* @return
@@ -116,7 +111,8 @@
/**
* <p class="changed_added_4_0">
- * Tag description, for JSP and Facelets, tags.
+ * Tag description. If generated tags require special handlers, provide separate
description for every type of tag, JSP and Facelets.
+ * Otherwise, the only one tag tag description with name and type {@link
TagType#All}.
* </p>
*
* @return
@@ -125,7 +121,7 @@
/**
* <p class="changed_added_4_0">
- * Faces Events fired by the component.
+ * @{link FacesEvent}s fired by the component.
* </p>
*
* @return
@@ -143,11 +139,10 @@
/**
* <p class="changed_added_4_0">
- * Defines fragments of faces-config.xml that contain standard attribute definitions.
CDK also tries to read
- * META-INF/cdk/attributes/[classname].xml file for all component superclass's
and interfaces. therefore it is not
- * necessary to explicitly include definitions for UIComponent and any other standard
JSF classes. CDK defines couple
- * of its own "urn" namespaces: "urn:resource:" for classpath
resources, "urn:config:" for for project configuration
- * folder and "urn:attributes:" for META-INF/cdk/attributes/ in the
annotations library.
+ * Defines file names for fragment of faces-config.xml that contain standard
attribute definitions. All names relative to the
+ * META-INF/cdk/attributes/ folder in classpath. CDK also tries to read
+ * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces. Therefore, it is not
+ * necessary to explicitly include definitions for UIComponent and any other standard
JSF classes.
* </p>
*
* @return
@@ -156,7 +151,7 @@
/**
* <p class="changed_added_4_0">
- * Interfaces that should be implemented in the generated component class. CDK
processes all {@link Attribute} and
+ * Interfaces that should be implemented by the generated component class. CDK
processes all {@link Attribute} and
* {@link Facet} annotations in these interfaces
* </p>
*
@@ -165,8 +160,8 @@
public Class<?>[] interfaces() default {};
/**
- * <p class="changed_added_4_0">Defines third-level renderer-specific
components. Used to generate a whole family of similar components.
- * For example, {@link UIComponentBase} provides {@link UICommand} subclass for all
command components, and {@link HtmlCommandLink} with {@link HtmlCommandButton} are
+ * <p class="changed_added_4_0">Defines third-level renderer specific
components. Used to generate a whole family of similar components.
+ * For example, {@link javax.faces.component.UIComponentBase} provides {@link
javax.faces.component.UICommand} subclass for all command components, and {@link
javax.faces.component.html.HtmlCommandLink} with {@link
javax.faces.component.HtmlCommandButton} are
* renderer-specific components for links and buttons.</p>
* @return
*/
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfConverter.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfConverter.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfConverter.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,8 +28,12 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.convert.Converter;
+
/**
* <p class="changed_added_4_0">
+ * This annotation defines concrete class as JSF {@link Converter}, or abstract class as
the base for generated
+ * Converter implementation.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -38,47 +42,83 @@
@Target(ElementType.TYPE)
public @interface JsfConverter {
+ /**
+ * <p class="changed_added_4_0">Default value for {@link #forClass}
attribute.</p>
+ * @author asmirnov(a)exadel.com
+ *
+ */
+ public static final class NONE {
+ }
+
public static final String NAME =
"org.richfaces.cdk.annotations.JsfConverter";
+ /**
+ * <p class="changed_added_4_0">
+ * The "converter-id" element represents the identifier under which the
corresponding Converter class should be
+ * registered.
+ * </p>
+ *
+ * @return converter-id
+ */
public String id() default "";
+ /**
+ * <p class="changed_added_4_0">
+ * represents the class for which a Converter class will be registered.
+ * </p>
+ *
+ * @return
+ */
public Class<?> forClass() default NONE.class;
-
+ /**
+ * <p class="changed_added_4_0">
+ * fully qualified class name of the generated Converter implementation. Default
value means nothing to genrate from concrete class,
+ * or infer name by convention for abstract class.</p>
+ * @return
+ */
public String generate() default "";
/**
* <p class="changed_added_4_0">
- * Description used by IDE.
+ * Converter description to include into generated faces-config and taglib.
* </p>
*
* @return
*/
public Description description() default @Description();
+ /**
+ * <p class="changed_added_4_0">
+ * Tag description. If generated tags require special handlers, provide separate
description for every type of tag, JSP and Facelets.
+ * Otherwise, the only one tag tag description with name and type {@link
TagType#All}.
+ * </p>
+ *
+ * @return
+ */
public Tag[] tag() default {};
-
- public static final class NONE {}
+
/**
* <p class="changed_added_4_0">
- * defines fragments of faces-config.xml that contain standard attribute definitions.
CDK also tries to read
- * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces, therefore it is not
- * necessary to explicit include definitions for UIComponent and any other standard
JSF classes. CDK defines couple
- * of its own "urn" namespaces: "urn:resource:" for classpath
resources, "urn:config:" for for project configuration
- * folder and "urn:attributes:" for META-INF/cdk/attributes/ in the
annotations library.
+ * Defines file names for fragment of faces-config.xml that contain standard
attribute definitions. All names relative to the
+ * META-INF/cdk/attributes/ folder in classpath. CDK also tries to read
+ * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces. Therefore, it is not
+ * necessary to explicitly include definitions for Converter and any other standard
JSF classes.
* </p>
*
* @return
*/
public String[] attributes() default {};
+
/**
* <p class="changed_added_4_0">
- * Interfaces that should be implemented in the generated class. CDK processes all
{@link Attribute} annotations in these interfaces
+ * Interfaces that should be implemented in the generated class. CDK processes all
{@link Attribute} annotations in
+ * these interfaces
* </p>
*
* @return
*/
public Class<?>[] interfaces() default {};
-
+
}
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfRenderer.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfRenderer.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfRenderer.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -32,7 +32,8 @@
/**
* <p class="changed_added_4_0">
- * The presence of this annotation in the JSF component class associated particular
renderer with component.
+ * This annotation defines concrete class as JSF {@link Renderer}, or abstract class as
the base for generated
+ * Renderer implementation.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -46,7 +47,7 @@
/**
* <p class="changed_added_4_0">
* The value of this annotation attribute is taken to be JSF
<em>renderer-type</em>. If this value was empty,
- * component type will be inferred from by the CDK.
+ * type will be inferred by the CDK.
* </p>
*
* @return JSF <em>renderer-type</em>.
@@ -54,26 +55,37 @@
public String type() default "";
/**
- * <p class="changed_added_4_0">Renderer Family</p>
+ * <p class="changed_added_4_0">Component Family for which renderer
from annotated class will be used.</p>
* @return
*/
public String family() default "";
/**
- * <p class="changed_added_4_0">Name of generated renderer
class.</p>
+ * <p class="changed_added_4_0">Name of the generated renderer class.
Default value means nothing to genrate from concrete class,
+ * or infer name by convention for abstract class.</p>
* @return
*/
public String generate() default "";
/**
- * <p class="changed_added_4_0">RenderKit for which this renderer is
belong to</p>
+ * <p class="changed_added_4_0">RenderKit ID for which this renderer
is belong to</p>
* @return
*/
public String renderKitId() default RenderKitFactory.HTML_BASIC_RENDER_KIT;
+ /**
+ * <p class="changed_added_4_0">Path to renderer template, relative
to templates folder defined by build ( Maven plugin or ant task ).</p>
+ * @return
+ */
public String template() default "";
+ /**
+ * <p class="changed_added_4_0">
+ * Description to include into generated faces-config and taglib.
+ * </p>
+ * @return
+ */
public Description description() default @Description();
}
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfValidator.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfValidator.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/JsfValidator.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -5,7 +5,13 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.faces.convert.Converter;
+import javax.faces.validator.Validator;
+
/**
+ * This annotation defines concrete class as JSF {@link Validator}, or abstract class as
the base for generated
+ * Validator implementation.
+ *
* @author akolonitsky
* @since Jan 13, 2010
*/
@@ -15,14 +21,36 @@
public static final String NAME =
"org.richfaces.cdk.annotations.JsfValidator";
+ /**
+ * <p class="changed_added_4_0">
+ * The "validator-id" element represents the identifier under which the
corresponding Validator class should be
+ * registered.
+ * </p>
+ *
+ * @return
+ */
public String id();
+ /**
+ * <p class="changed_added_4_0">
+ * fully qualified class name of the generated Converter implementation. Default
value means nothing to genrate from concrete class,
+ * or infer name by convention for abstract class.</p>
+ * @return
+ */
public String generate() default "";
+ /**
+ * <p class="changed_added_4_0">
+ * Tag description. If generated tags require special handlers, provide separate
description for every type of tag, JSP and Facelets.
+ * Otherwise, the only one tag tag description with name and type {@link
TagType#All}.
+ * </p>
+ * @return
+ */
public Tag[] tag() default {};
+
/**
* <p class="changed_added_4_0">
- * Description used by IDE.
+ * Description to include into generated faces-config and taglib.
* </p>
*
* @return
@@ -31,19 +59,20 @@
/**
* <p class="changed_added_4_0">
- * defines fragments of faces-config.xml that contain standard attribute definitions.
CDK also tries to read
- * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces, therefore it is not
- * necessary to explicit include definitions for UIComponent and any other standard
JSF classes. CDK defines couple
- * of its own "urn" namespaces: "urn:resource:" for classpath
resources, "urn:config:" for for project configuration
- * folder and "urn:attributes:" for META-INF/cdk/attributes/ in the
annotations library.
+ * Defines file names for fragment of faces-config.xml that contain standard
attribute definitions. All names relative to the
+ * META-INF/cdk/attributes/ folder in classpath. CDK also tries to read
+ * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces. Therefore, it is not
+ * necessary to explicitly include definitions for Converter and any other standard
JSF classes.
* </p>
*
* @return
*/
public String[] attributes() default {};
+
/**
* <p class="changed_added_4_0">
- * Interfaces that should be implemented in the generated class. CDK processes all
{@link Attribute} annotations in these interfaces
+ * Interfaces that should be implemented in the generated class. CDK processes all
{@link Attribute} annotations in
+ * these interfaces
* </p>
*
* @return
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/RendererSpecificComponent.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/RendererSpecificComponent.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/RendererSpecificComponent.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,7 +28,7 @@
/**
* <p class="changed_added_4_0">
- * That annotation defines class that is generated from the concrete class defined in
the {@link JsfComponent}
+ * That annotation defines third lvel component, specific for the concrete renderer,
that is generated from the concrete class defined in the {@link JsfComponent}
* </p>
*
* @author asmirnov(a)exadel.com
@@ -40,11 +40,10 @@
/**
* <p class="changed_added_4_0">
- * Type of the component. This is mandatory parameter because CDK uses
<em>component-type</em> as primary key for
- * components library model.
+ * Type of the JSF component.
* </p>
- * <p class="todo">
- * TODO if this value is an empty, component type will be inferred from class name.
+ * <p class="naming">
+ * if this value is an empty, component type would be inferred from class name.
* </p>
*
* @return component type.
@@ -63,7 +62,7 @@
/**
* <p class="changed_added_4_0">
- * Description used by IDE.
+ * Component description to include into generated faces-config and taglib.
* </p>
*
* @return
@@ -72,7 +71,7 @@
/**
* <p class="changed_added_4_0">
- * Cenerated Junit test.
+ * Junit test description. Isn't used in RichFaces 4.0, reserved for future
releases.
* </p>
*
* @return
@@ -90,7 +89,8 @@
/**
* <p class="changed_added_4_0">
- * View Description Language, JSP or Facelets, tags.
+ * Tag description. If generated tags require special handlers, provide separate
description for every type of tag, JSP and Facelets.
+ * Otherwise, the only one tag tag description with name and type {@link
TagType#All}.
* </p>
*
* @return
@@ -109,11 +109,10 @@
/**
* <p class="changed_added_4_0">
- * defines fragments of faces-config.xml that contain standard attribute definitions.
CDK also tries to read
- * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces, therefore it is not
- * necessary to explicit include definitions for UIComponent and any other standard
JSF classes. CDK defines couple
- * of its own "urn" namespaces: "urn:resource:" for classpath
resources, "urn:config:" for for project configuration
- * folder and "urn:attributes:" for META-INF/cdk/attributes/ in the
annotations library.
+ * Defines file names for fragment of faces-config.xml that contain standard
attribute definitions. All names relative to the
+ * META-INF/cdk/attributes/ folder in classpath. CDK also tries to read
+ * META-INF/cdk/attributes/[classname].xml file for all component superclasses and
interfaces. Therefore, it is not
+ * necessary to explicitly include definitions for UIComponent and any other standard
JSF classes.
* </p>
*
* @return
@@ -122,7 +121,7 @@
/**
* <p class="changed_added_4_0">
- * Interfaces that should be implemented in the generated component class. CDK
processes all {@link Attribute} and
+ * Interfaces that should be implemented by the generated component class. CDK
processes all {@link Attribute} and
* {@link Facet} annotations in these interfaces
* </p>
*
@@ -131,7 +130,7 @@
public Class<?>[] interfaces() default {};
/**
* <p class="changed_added_4_0">
- * Events fired by the component.
+ * @{link FacesEvent}s fired by the component.
* </p>
*
* @return
Modified: trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Tag.java
===================================================================
--- trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Tag.java 2011-03-16
22:17:01 UTC (rev 22244)
+++ trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/Tag.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -26,8 +26,12 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
+import javax.faces.view.facelets.TagHandler;
+import javax.faces.webapp.UIComponentTagBase;
+
/**
* <p class="changed_added_4_0">
+ * Defines Faces VDL ( Facelets,JSP )tag.
* </p>
*
* @author asmirnov(a)exadel.com
@@ -46,12 +50,30 @@
*/
public String name() default "";
+ /**
+ * <p class="changed_added_4_0">Defines target View Description
Language: JSP, Facelets, or both.</p>
+ * @return
+ */
public TagType type() default TagType.Facelets;
+ /**
+ * <p class="changed_added_4_0">Tag handler class. Fully qualified
class name of the generated or
+ * existing tag handler. For {@link TagType#Jsp} it's {@link JspTag} or, more
likely, {@link UIComponentTagBase} instance.
+ * For facelets, it's {@link TagHandler} instance.</p>
+ * @return
+ */
public String handler() default "";
+ /**
+ * <p class="changed_added_4_0">Base class for generated tag handler.
Default value depends from {@link #type()} attribute value.</p>
+ * @return
+ */
public String baseClass() default "";
+ /**
+ * <p class="changed_added_4_0">Flag indicates that special tag
handler should be generated.</p>
+ * @return
+ */
public boolean generate() default false;
}
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagLibrary.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagLibrary.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagLibrary.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -28,7 +28,9 @@
import java.lang.annotation.Target;
/**
- * This annotation defines taglib for which all tags for JSF components from that
packages belong to
+ * This annotation defines taglib for which all tags for JSF components from that
packages belong to.
+ * Current limitation - there sould be only one taglib package in the project, otherwise
the last processed package will
+ * override others.
*
* @author asmirnov
* @version $Id$
@@ -45,7 +47,7 @@
public String uri();
/**
- * <p class="changed_added_4_0">Library short name ( default prefix
)</p>
+ * <p class="changed_added_4_0">Library short name ( default prefix
). The same same also used for faces-config <name> element.</p>
* @return
*/
public String shortName();
@@ -76,13 +78,13 @@
public Class<?> listenerClass() default NONE.class;
/**
- * <p class="changed_added_4_0">Library description to use by
IDE</p>
+ * <p class="changed_added_4_0">Library description, included into
generated taglib and faces-config.E</p>
* @return
*/
public String displayName() default "";
/**
- * <p class="changed_added_4_0">Java Server Pages version for
generated tld.</p>
+ * <p class="changed_added_4_0">Java Server Pages version for
generated tld, for JSP taglib only.</p>
* @return
*/
public String jspVersion() default "2.0";
Modified: trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagType.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagType.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/TagType.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -23,6 +23,7 @@
package org.richfaces.cdk.annotations;
/**
+ * VDL type for {@link Tag} annotation.
* @author akolonitsky
* @since Feb 11, 2010
*/
Modified:
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/package-info.java
===================================================================
---
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/package-info.java 2011-03-16
22:17:01 UTC (rev 22244)
+++
trunk/cdk/annotations/src/main/java/org/richfaces/cdk/annotations/package-info.java 2011-03-16
23:11:06 UTC (rev 22245)
@@ -1,32 +1,41 @@
/**
* <h1>Java annotations used by the CDK.</h1>
+ * <h2>Package-level annotations</h2>
+ * <p> {@link org.richfaces.cdk.annotations.TagLibrary} defines library-wide
parameters</p>
* <h2>Class-level annotations:</h2>
- * <p>Mandatory:</p>
- * <p>@{@link JsfComponent}("component.Type") or
@{@link
javax.faces.component.FacesComponent}("component.Type").</p>
- * <p>Optional:</p>
* <ul>
- * <li>@{@link Family}("component.Family") defines component
family used in the generated class.<br /></li>
- * <li>@{@link Generate}("component.UIClass") tells CDK to
generate concrete component class ( base UI... or renderer-specific ).</li>
- * <li>@{@link
Test}(testClass="component.Test",testMethod="testFoo",testType={@link
TestType}.DECODE) tells CDK to generate unit test for that component.</li>
- * <li>@{@link JsfRenderer}("retnderer.Type") , @{@link
RendererTemplate}("/renderer/template.xml") associate renderer with that
component. The first one defines independently created renderer, while @{@link
RendererTemplate tells CDK to generate renderer class from that template. It is possible
to define more than one template with component class using @{@link
RendererTemplates}({@{@link
RendererTemplate}("one.xml"),@{@link
RendererTemplate}("two.xml").<br /></li>
- * <li>@{@link Attributes}({"base.xml","command.xml"})
defines fragments of faces-config.xml which contain standart attributes definitions. CDK
also tries to read META-INF/cdk/attributes/[classname].xml file for all component
superclasses and interfaces, therefore it is not necessary to explicit include definitions
for UIComponent and any other standard JSF classes. CDK defines couple of its own
"urn" namespaces: "urn:resource:" for classpath resources,
"urn:config:" for for project configuration folder and
"urn:attributes:" for META-INF/cdk/attributes/ in the annotations library.<br
/></li>
- * <li>@{@link Fires}({MyEvent.class}) defines event classes that this
component could fire.</li>
- * <li>@{@link Description} , @{@link DisplayName} - optional
IDE-related parameters.<br /></li>
+ * <li>@{@link
org.richfaces.cdk.annotations.JsfComponent}("component.Type") or
@{@link
javax.faces.component.FacesComponent}("component.Type").</li>
+ * <li>@{@link org.richfaces.cdk.annotations.JsfRenderer} Defines JSF
{@link javax.faces.render.Renderer} or link renderer with component.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.JsfConverter} Defines JSF
{@link javax.faces.convert.Converter}.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.JsfValidator} Defines JSF
{@link javax.faces.validator.Validator}.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.JsfBehavior} Defines JSF
{@link javax.faces.component.behavior.ClientBehavior}.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.JsfBehaviorRenderer} Defines
JSF {@link javax.faces.render.ClientBehaviorRenderer} or links renderer with
behavior.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Event} Defines JSF {@link
javax.faces.event.FacesEvent} or links event with component that fires it.</li>
* </ul>
+ * <h2>Annotations used to refine class top level definitions</h2>
+ * <li>@{@link org.richfaces.cdk.annotations.Test} tells CDK to generate
unit test for component.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Description} optional
IDE-related parameters.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Tag} VDL tag
description.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.RendererSpecificComponent}
defines renderer specific component for the family created from one base
component</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Description} optional
IDE-related parameters.<br /></li>
+ * </ul>
* <p> </p>
- * <h2>Attribute level annotations ( for getter or setter level ):</h2>
+ * <h2>Attribute level annotations ( for getter or field level ):</h2>
* <ul>
- * <li>@{@link
Attribute}(literal="false",hidden="false",readOnly="false",passTrough="true")
markes attribute getter/setter.</li>
- * <li>@{@link
Signature}(returnType=boolean.class,parameters={Object.class,String.class}) defines Java
method signature for attributes that holds MethodExpression objects.</li>
- * <li>@{@link Generate} forces CDK to generate attribute getter/setter.
Without that annotation CDK will generate implementation for abstract methods
only.</li>
- * <li>@{@link Alias}({"foo","bar"})</li>
- * <li>@{@link EventName}(value="click",defaultEvent=true)
defines behavior event name for that attribute. To define more than one event name they
could be grouped as @{@link EventNames}({@{@link
EventName}("foo),@{@link EventName}("bar")})</li>
- * <li>@{@link DefaultValue}("12"), @{@link
SuggestedValue}("12") ...</li>
- * <li>@{@link Description} , @{@link DisplayName} - optional
IDE-related parameters.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Attribute} Defines Faces
attribute, used on for attribute getter method or field.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Facet} for facet getter.
Also, used in {@link org.richfaces.cdk.annotations.JsfComponent} facets
property.</li>
+ * <li>@{@link org.richfaces.cdk.annotations.Function}, Used for public
static methods to define them as EL-functions.</li>
* </ul>
+ * <h2>Annotations used to refine method-level properties</h2>
+ * <ul>
+ * <li>@{@link Signature} defines Java method signature for attributes
that holds MethodExpression objects.</li>
+ * <li>@{@link Alias} defines alias for attribute.</li>
+ * <li>@{@link EventName}(value="click",defaultEvent=true)
defines behavior event name for that attribute.</li>
+ * <li>@{@link Description} optional IDE-related description.</li>
+ * </ul>
* <p> </p>
* <h3>Facet annotations.</h3>
- * <p>There are two methods to define component facet. At the class level,
developer could use @{@link Facets annotations. It is also possible to define
facet getter/setter methods for facet and mark one of them with @{@link Facet}
annotation.</p>
+ * <p>There are two methods to define component facet. At the class level,
developer could use @{@link org.richfaces.cdk.annotations.JsfComponent#facets()}
property. It is also possible to define facet getter/setter methods for facet and mark one
of them with @{@link Facet} annotation.</p>
*
*
*/