Author: kentam
Date: Thu May 12 16:47:28 2005
New Revision: 169912
URL: http://svn.apache.org/viewcvs?rev=169912&view=rev
Log:
Improving Javadocs, and fixed a bug where we were swallowing exceptions thrown
during assembly.
Modified:
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssembler.java
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssemblyException.java
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/AnnotationMemberTypes.java
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/Controls.java
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/AssembleTask.java
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/Assembler.java
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/BaseAssemblyContext.java
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/bean/ControlBean.java
Modified:
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssembler.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssembler.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssembler.java
(original)
+++
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssembler.java
Thu May 12 16:47:28 2005
@@ -19,11 +19,27 @@
*/
/**
- * This interface provides the methods that can be called at assembly-time
- * by build tools.
+ * Control implementations may need to do build-time work on or impacted by
+ * their control client(s), such as side-effecting their client's deployment
+ * descriptors, or generating additional files that are implementation-
+ * specific.
+ *
+ * The build phase where this work is done is called assembly, and occurs
+ * at the granularity level of the J2EE module.
+ * The control author participates in this phase by authoring classes that
+ * implement the ControlAssembler interface, and associating such classes
+ * with control implementations. Instances of ControlAssembler are then
+ * called at assembly-time by build tools.
*/
public interface ControlAssembler
{
+ /**
+ * A ControlAssembler implementation's assemble method is called once
+ * per control assembler per module per assembly-time pass. The call
+ * passes a ControlAssemblyContext, from which information such as the
+ * list of client classes in the module that use the control can be
+ * obtained.
+ */
void assemble(ControlAssemblyContext cac) throws ControlAssemblyException;
}
Modified:
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssemblyException.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssemblyException.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssemblyException.java
(original)
+++
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/assembly/ControlAssemblyException.java
Thu May 12 16:47:28 2005
@@ -18,6 +18,11 @@
* $Header:$
*/
+/**
+ * Checked exceptions thrown during the assembly process. ControlAssembler
+ * implementations may throw this exception in their assemble() method, which
+ * will halt the assembly process.
+ */
public class ControlAssemblyException extends Exception
{
public ControlAssemblyException( String msg )
Modified:
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/AnnotationMemberTypes.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/AnnotationMemberTypes.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/AnnotationMemberTypes.java
(original)
+++
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/AnnotationMemberTypes.java
Thu May 12 16:47:28 2005
@@ -190,10 +190,16 @@
{
}
+ /**
+ * Member is a JNDI name.
+ */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface JndiName
{
+ /**
+ * Defines the type of JNDI resource reference by a member.
+ */
public enum ResourceType
{
DATASOURCE,
Modified:
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/Controls.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/Controls.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/Controls.java
(original)
+++
incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api/bean/Controls.java
Thu May 12 16:47:28 2005
@@ -32,7 +32,8 @@
import java.lang.reflect.InvocationTargetException;
/**
- * Helper class for using controls.
+ * Helper class for using controls. Includes static methods to help
instantiate controls, and initialize
+ * declarative control clients.
*/
public class Controls
{
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/AssembleTask.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/AssembleTask.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/AssembleTask.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/AssembleTask.java
Thu May 12 16:47:28 2005
@@ -38,6 +38,43 @@
/**
* AssembleTask defines a custom ant task to perform control assembly.
+ * <p>
+ * The core assembly algorithm is documented and implemented in [EMAIL
PROTECTED] Assembler}.
+ * <p>
+ * Required attributes:<br>
+ * <b>moduleDir</b>: path to the root of J2EE module on which to perform
assembly.<br>
+ * <b>srcOutputDir</b>: path to the dir where control assemblers may output
source files.
+ * It may be necessary to run additional build steps in order to process such
files (for example,
+ * if an assembler outputs Java source code, that code may need to be
compiled).<br>
+ * <b>contextFactoryClassname</b>: fully qualified classname of a factory
class that implements
+ * [EMAIL PROTECTED]
org.apache.beehive.controls.api.assembly.ControlAssemblyContext$Factory}.
Typically this
+ * would depend on the type of module on which assembly is being run (EJB,
webapp, etc). Different
+ * contexts will expose different APIs to control assemblers (making different
descriptors available,
+ * etc).
+ * <p>
+ * Supported nested elements:<br>
+ * <b>classpath</b>: specifies the classpath that will be searched for control
interfaces/implementations,
+ * control clients and control assemblers.<br>
+ * <b>fileset</b>: specifies the control client manifests that should be
processed by this assembly call.<br>
+ * <p>
+ * An example usage of the AssembleTask in an ant build script (build.xml):
+ * <p>
+<xmp>
+ <taskdef name="assemble"
classname="org.apache.beehive.controls.runtime.assembly.AssembleTask"
+ classpathref="controls.dependency.path" onerror="report" />
+
+ <assemble moduleDir="${build.beans}"
+ srcOutputDir="${build.beansrc}"
+
contextFactoryClassname="org.apache.beehive.controls.runtime.assembly.EJBAssemblyContext$Factory">
+ <classpath>
+ <path refid="test.classpath"/>
+ <pathelement location="${build.beans}"/>
+ </classpath>
+ <fileset dir="${build.beans}">
+ <include name="**\*.controls.properties"/>
+ </fileset>
+ </assemble>
+</xmp>
*/
public class AssembleTask extends Task
{
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/Assembler.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/Assembler.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/Assembler.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/Assembler.java
Thu May 12 16:47:28 2005
@@ -29,6 +29,9 @@
import java.util.Map;
import java.util.Set;
+/**
+ * Helper class to execute assembly logic.
+ */
public class Assembler
{
/**
@@ -97,9 +100,16 @@
}
}
}
- catch ( Exception e )
+ catch ( ControlAssemblyException cae )
{
- e.printStackTrace( );
+ // just rethrow ControlAssemblyExceptions, which will typically
come from user-provided assemblers.
+ throw cae;
+ }
+ catch ( Throwable t )
+ {
+ // Not expecting any throwables other than
ControlAssemblyExceptions, so consider them as
+ // unexpected infrastructure issues and wrap them in a CAE.
+ throw new ControlAssemblyException( "Assembly infrastructure
exception", t);
}
finally
{
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/BaseAssemblyContext.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/BaseAssemblyContext.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/BaseAssemblyContext.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/assembly/BaseAssemblyContext.java
Thu May 12 16:47:28 2005
@@ -32,7 +32,8 @@
import com.sun.mirror.util.SourcePosition;
/**
- * Base ControlAssemblyContext implementation
+ * Abstract ControlAssemblyContext implementation. Provides a basic
implementation of most non-module-specific
+ * APIs, meant to be extended by module-specific types.
*/
public abstract class BaseAssemblyContext implements ControlAssemblyContext
{
Modified:
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/bean/ControlBean.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/bean/ControlBean.java?rev=169912&r1=169911&r2=169912&view=diff
==============================================================================
---
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/bean/ControlBean.java
(original)
+++
incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls/runtime/bean/ControlBean.java
Thu May 12 16:47:28 2005
@@ -47,15 +47,15 @@
/**
* The ControlBean class is an abstract base class for the JavaBean classes
generated to support
* Workshop controls.
- *
+ * <p>
* The ControlBean class indirectly implements BeanContextProxy; the
ControlBeanContext that it contains/scopes
* acts as that proxy.
- *
+ * <p>
* All support APIs (which may be called from derived derived subclasses or
contextual services
* are generally marked as protected and have names that start with an
underscore. This avoids the
* possibility that the name might conflict with a user-defined method on a
control's public or
* extended (JCX) interface.
- *
+ * <p>
* NOTE: Adding public methods should be done with great care; any such method
becomes part of the
* public API, and occupies namespace for all controls.
*/
@@ -66,8 +66,8 @@
*
* @param context the containing ControlBeanContext. May be null,
in which case the bean will attempt to
* associate with an active context at runtime (via
thread-locals).
- * @param id
- * @param initProperties
+ * @param id the local ID for the control, scoped to the
control bean context.
+ * @param initProperties a PropertyMap containing initial properties for
the control
* @param controlIntf the control interface or extension directly
implemented by the control bean
*/
protected
ControlBean(org.apache.beehive.controls.api.context.ControlBeanContext context,
