Great docs. - jeremiah
> -----Original Message----- > From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] > Sent: Thursday, May 12, 2005 5:47 PM > To: [EMAIL PROTECTED] > Subject: svn commit: r169912 - in /incubator/beehive/trunk/controls/src: > api/org/apache/beehive/controls/api/assembly/ > api/org/apache/beehive/controls/api/bean/ > runtime/org/apache/beehive/controls/runtime/assembly/ > runtime/org/apache/beehive/controls/runtime/bean/ > > 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 /a > ssembly/ControlAssembler.java > > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /a > ssembly/ControlAssemblyException.java > > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /b > ean/AnnotationMemberTypes.java > > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /b > ean/Controls.java > > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/assembly/AssembleTask.java > > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/assembly/Assembler.java > > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/assembly/BaseAssemblyContext.java > > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/bean/ControlBean.java > > Modified: > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /a > ssembly/ControlAssembler.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/o rg > /apache/beehive/controls/api/assembly/ControlAssembler.java?rev=169912&r 1= > 169911&r2=169912&view=diff > ======================================================================== == > ==== > --- > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /a > ssembly/ControlAssembler.java (original) > +++ > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /a > ssembly/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 /a > ssembly/ControlAssemblyException.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/o rg > /apache/beehive/controls/api/assembly/ControlAssemblyException.java?rev= 16 > 9912&r1=169911&r2=169912&view=diff > ======================================================================== == > ==== > --- > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /a > ssembly/ControlAssemblyException.java (original) > +++ > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /a > ssembly/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 /b > ean/AnnotationMemberTypes.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/o rg > /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 /b > ean/AnnotationMemberTypes.java (original) > +++ > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /b > ean/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 /b > ean/Controls.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/api/o rg > /apache/beehive/controls/api/bean/Controls.java?rev=169912&r1=169911&r2= 16 > 9912&view=diff > ======================================================================== == > ==== > --- > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /b > ean/Controls.java (original) > +++ > incubator/beehive/trunk/controls/src/api/org/apache/beehive/controls/api /b > ean/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 /r > untime/assembly/AssembleTask.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runti me > /org/apache/beehive/controls/runtime/assembly/AssembleTask.java?rev=1699 12 > &r1=169911&r2=169912&view=diff > ======================================================================== == > ==== > --- > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/assembly/AssembleTask.java (original) > +++ > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/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.EJ BA > ssemblyContext$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 /r > untime/assembly/Assembler.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runti me > /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 /r > untime/assembly/Assembler.java (original) > +++ > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/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 /r > untime/assembly/BaseAssemblyContext.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runti me > /org/apache/beehive/controls/runtime/assembly/BaseAssemblyContext.java?r ev > =169912&r1=169911&r2=169912&view=diff > ======================================================================== == > ==== > --- > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/assembly/BaseAssemblyContext.java (original) > +++ > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/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 /r > untime/bean/ControlBean.java > URL: > http://svn.apache.org/viewcvs/incubator/beehive/trunk/controls/src/runti me > /org/apache/beehive/controls/runtime/bean/ControlBean.java?rev=169912&r1 =1 > 69911&r2=169912&view=diff > ======================================================================== == > ==== > --- > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/bean/ControlBean.java (original) > +++ > incubator/beehive/trunk/controls/src/runtime/org/apache/beehive/controls /r > untime/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, >
