Date: 2004-08-25T15:33:44
Editor: KyleMarvin <[EMAIL PROTECTED]>
Wiki: Apache Beehive Wiki
Page: Controls/ControlPackaging
URL: http://wiki.apache.org/beehive/Controls/ControlPackaging
no comment
Change Log:
------------------------------------------------------------------------------
@@ -1,23 +1,23 @@
= Controls Packaging Model =
-The Beehive Control framework includes a JAR-based packaging model that allows
a collection of controls (and supporting control implementations) to be bundled
into a JAR file, and defines an additional manifest file that enumerates the
controls contained within the jar and other attributes of the control (such as
icons, display names, etc).
+The Beehive Control framework includes a JAR-based packaging model that allows
a collection of controls (and supporting control implementations) to be bundled
into a JAR file.
-The primary goal is to enable a tool to quickly scan a jar file for a list of
available controls (and certain key attributes) and then introspect individual
classes within the JAR.
+* The primary goal is to enable a tool to quickly scan a jar file for a list
of available controls (and certain key attributes) and then introspect
individual classes within the JAR.
-A secondary goal is to provide an annotation model that enables the creation
of JAR manifest attributes and custom BeanInfo associated with a Control
JavaBean simply by annotating the original source artifacts.
+* A secondary goal is to provide an annotation model that enables the creation
of JAR manifest attributes and custom BeanInfo associated with a Control
JavaBean simply by annotating the original source artifacts.
== Relationship to JavaBeans packaging model ==
'''The goal is to fully support the JavaBeans packaging and introspection
model for Controls'''. There is no point in re-inventing the wheel and/or
doing something different where the existing JavaBeans spec describes useful
functionality. To make the model easier to use for developers and tools, the
Controls packaging model defines a set of JSR-175 annotation types that enable
packaging information to specified declaratively inside Control source files.
-Section 11 of the JavaBeans specification actually defines a simple packaging
model based upon entries in META-INF/MANIFEST.MF. The spec states that this
file will contain entries describing JavaBeans in the form:
+Section 11 of the JavaBeans specification actually defines a simple packaging
model based upon entries in META-INF/MANIFEST.MF. The spec states that the
manifest will contain a section describing each JavaBean of the form:
{{{
Name: org.apache.beehive.controls.samples.SampleBean.class
JavaBean: true
}}}
-There is also a basic introspection model (based upon the
java.beans.Introspector class) that enables a JavaBean class to be queried for
its BeanInfo, BeanDescriptor, MethodDescriptors, PropertyDescriptors, etc to
provide information about the JavaBean based upon introspection. The various
Descriptor types all derive from a common base class (FeatureDescriptor) that
enables customized design-time attributes to be associated with bean types,
properties, methods, and events.
+There is also a basic introspection model (based upon the
java.beans.Introspector class) that enables a JavaBean class to be queried for
its java.BeanInfo, BeanDescriptor, MethodDescriptors, PropertyDescriptors, etc.
to provide additional information about the JavaBean. These various
Descriptor types all derive from a common base class (FeatureDescriptor) that
enables customized design-time attributes to be associated with bean types,
properties, methods, and events.
[JavaBeans spec and API docs can be found at:
http://java.sun.com/products/javabeans/docs/spec.html]
@@ -25,7 +25,7 @@
== JAR Manifest Attributes ==
-The standard Control processing/build infrastructure provides support for
''automatically'' generating the basic set of JAR manifest entries for all
JavaBeans generated to support Beehive controls. When the annotation processor
for Control JSR-175 annotations is run, the processor will generate JAR
manifest fragments for each Control JavaBean that has been generated. These
fragments will be written to the class build output directory have and the name
''<fully-qualified-bean-classname>.class.manifest''.
+The standard Control processing/build infrastructure provides support for
''automatically'' generating the basic set of JAR manifest entries for
JavaBeans generated to support Beehive controls. When the annotation processor
for Control JSR-175 annotations is run, the processor will generate JAR
manifest fragments for each Control JavaBean that has been generated. These
fragments will be written to the class build output directory have and the name
''<fully-qualified-bean-classname>.class.manifest''.
A special Controls Jar Ant task is provided that can be used to generate a JAR
file containing Controls that will merge the generated manifest fragments into
the JAR manifest. '''The Controls Jar task derives directly from the
base-level Ant <jar> task, and support all of its standard attributes and
nested elements'''. This task can be imported into an Ant build file for a
Controls JAR as follows:
@@ -43,7 +43,7 @@
The resulting META-INF/MANIFEST.MF manifest file will contain the contents of
any input manifest file (passing as an attribute or inline to the <control-jar>
task merged with the auto-generated manifest descriptor attributes.
-=== Declaring custom JAR manifest attributes using @ManifestAttribute ===
+=== Declaring custom JAR manifest attributes using @ManifestAttribute and
@ManifestAttributes ===
The Controls packaging model also provides a simple JSR-175 annotation syntax
that enables a developer or tool to add custom manifest attributes for a
generated Control JavaBean by annotating the Control public or extension
interface, as follows:
@@ -66,7 +66,7 @@
MyAttribute: MyValue
}}}
-A series of attribute name/value pairs for a Control public or extension
interface can be specified using the ManifestAttributes annotation type:
+A collection of attribute name/value pairs for a Control public or extension
interface can be specified using the ManifestAttributes annotation type:
{{{
@ControlInterface
@@ -86,7 +86,7 @@
The Controls packaging model augments the standard JavaBeans model by
providing a set of JSR-175 annotations that allow JavaBean Descriptor values to
be specified directly on declarations in a Control public or extension
interface, and providing the necessary infrastructure to generate customized
BeanInfo support classes that will expose this information to tools. Once
generated, '''the customized BeanInfo is accessible using the standard
JavaBeans introspection model'''.
-The subsequent sections describe these annotations:
+The subsequent sections describe these annotations. There is a base
FeatureInfo type that can be used to set the generic FeatureDescriptor
information for a Control ''feature'' and then Descriptor-specific annotation
types to set the specific values for bean, property, method, and event
descriptors.
=== Setting FeatureDescriptor values using @FeatureInfo ===
@@ -128,4 +128,73 @@
public interface MyControl { ... }
}}}
-... To Be Continued ...
+The above annotation would result in the following result from using the
JavaBeans introspection API:
+
+{{{
+String desc =
java.beans.Introspector.getBeanInfo(MyControlBean.class).getBeanDescriptor().getShortDescription();
+}}}
+The value of ''desc'' after this call would be "A simple packaging example
control".
+
+The @FeatureInfo annotation can be used in the following locations:
+
+* '''An interface annotated with @ControlInterface or @ControlExtension''' to
set feature attributes for the BeanDescriptor
+associated with the generated JavaBean type.
+
+* '''A method declaration within an @Control or @ControlExtension interface'''
to set feature attributes for the
+MethodDescriptor associated with a Control operation
+
+* '''A method declaration with an @PropertySet interface''' to set feature
attribute for the PropertyDescriptor associated with the Control property.
+
+* '''An interface annotation with the @EventSet annotation''' to set feature
attributes for the EventSetDescriptor associated
+with a Control event set.
+
+* '''A method declaration within an @EventSet interface''' to set feature
attributes for the MethodDescriptor associated with a Control event
+
+=== Setting BeanDescriptor attributes using @BeanInfo ===
+
+'''TBD'''
+
+== Setting PropertyDescriptor attributes using @PropertyInfo ===
+
+The @PropertyInfo annotation can be placed on a property method declaration to
specify the eventing behavior of the annotated property.
+
+Here is the declaration of PropertyInfo:
+
+{{{
[EMAIL PROTECTED]({ElementType.METHOD}) // appears on PropertySet method
declaration (i.e. properties)
+public @interface PropertyInfo
+{
+ public boolean bound() default false; // Sends PropertyChange
events
+ public boolean constrained() default false; // Sends VetoableChange
events
+}
+}}}
+
+An example usage of PropertyInfo is:
+
+{{{
[EMAIL PROTECTED]
+public interface MyControl
+{
+ @PropertySet
+ public @interface SampleProps
+ {
+ @FeatureInfo(shortDesc="This property send no events")
+ public int basicProp()
+
+ @PropertyInfo(bound=true)
+ @FeatureInfo(shortDesc="This property will send PropertyChange
events")
+ public int boundProp();
+
+ @PropertyInfo(constrained=true)
+ @FeatureInfo(shortDesc="This property will send VetoableChange
events")
+ public int constrainedProp();
+ }
+}
+
+== Setting MethodDescriptor attributes using @MethodInfo ===
+
+'''TBD'''
+
+=== Setting EventSet attributes using @EventSetInfo ===
+
+''' TBD '''
