Date: 2004-08-25T13:30:45
Editor: KyleMarvin <[EMAIL PROTECTED]>
Wiki: Apache Beehive Wiki
Page: Controls/ControlPackaging
URL: http://wiki.apache.org/beehive/Controls/ControlPackaging
Initial version (incomplete)
New Page:
= 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 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.
== 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:
{{{
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.
[JavaBeans spec and API docs can be found at:
http://java.sun.com/products/javabeans/docs/spec.html]
These two mechanisms (manifest attributes and BeanInfo descriptor elements)
will be leveraged to provide an extended packaging model for Beehive Controls.
== 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''.
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:
{{{
<taskdef name="control-jar"
classname="org.apache.beehive.controls.runtime.packaging.ControlJarTask"
classpath="{beehive-lib-dir}/controls.jar"/>
}}}
A sample usage of this task (from the Controls checkin tests) is shown below:
{{{
<control-jar destfile="${build.jars}/drtbeans.jar" basedir="${build.beans}" />
}}}
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 ===
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:
{{{
package org.apache.beehive.samples.packaging;
import org.apache.beehive.controls.api.packaging.ControlInterface;
import org.apache.beehive.controls.api.packaging.ManifestAttribute;
@ControlInterface
@ManifestAttribute(name="MyAttribute", value="MyValue")
public interface MyControl { ... }
}}}
This would result in the following JAR manifest section being created:
{{{
Name: org.apache.beehive.controls.samples.packaging.MyControlBean.class
JavaBean: true
MyAttribute: MyValue
}}}
A series of attribute name/value pairs for a Control public or extension
interface can be specified using the ManifestAttributes annotation type:
{{{
@ControlInterface
@ManifestAttributes({
@ManifestAttribute(name="MyAttribute", value="MyValue"),
@ManifestAttribute(name="MyOtherAttribute", value="MyOtherValue"),
...
})
public interface MyControl { ... }
}}}
== BeanInfo Attributes ==
JavaBeans provides a basic introspection model that enables tools to query a
JavaBean for information about its properties, methods, events, and other
attributes. Tools can access this information using the services of the
java.beans.Introspector class that will return a BeanInfo instance describing
the bean type and provides access to the various Descriptor types
''(PropertyDescriptor, MethodDescriptor, EventSetDescriptor, ...)'' elements
that provide useful information about the JavaBean.
Each of these Descriptor classes derives from a common class
(java.beans.FeatureDescriptor) that provides useful design-time information for
tools, such as the display name of the property, method, or event, a short
description, whether the ''feature'' should be hidden or displayed, is for
basic or expert use, etc. Additionally, the FeatureDescriptor can also
contain a set of attributes (name/value pairs) that be used to provide
customized or tool-specific attributes that related to the JavaBean ''feature''.
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:
=== Setting FeatureDescriptor values using @FeatureInfo ===
The FeatureInfo annotation type can be used to set any or all of the various
FeatureDescriptor elements for JavaBean types, properties, methods, event sets,
or events. A supporting type (@FeatureAttribute) also enables custom
attributes to be set for the feature.
Here is the JSR-175 annotation type declaration for FeatureInfo:
{{{
package org.apache.beehive.controls.api.packaging;
import java.lang.annotation.*;
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface FeatureInfo
{
public String displayName() default ""; // default: use
reflection name
public String name() default ""; // default: use
reflection name
public String shortDescription() default "";
public boolean isExpert() default false;
public boolean isHidden() default false;
public boolean isPreferred() default false;
public FeatureAttribute [] attributes() default {};
}
}}}
Default values are provided for the members of this type, meaning only
non-default values need to be set on use. Here is an example of using this
type to set FeatureDescriptor information for a Control JavaBean type:
{{{
@ControlInterface
@FeatureInfo(
displayName="My Control",
shortDescription="A simple packaging example control",
isExpert=true,
attributes=({
@FeatureAttribute(name="MyCustomAttribute", value="TheValue"),
...
})
)
public interface MyControl { ... }
}}}
... To Be Continued ...
