You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beehive.apache.org by Jeremiah Johnson <je...@bea.com> on 2005/05/13 07:25:09 UTC
RE: 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/b
Great docs.
- jeremiah
> -----Original Message-----
> From: kentam@apache.org [mailto:kentam@apache.org]
> Sent: Thursday, May 12, 2005 5:47 PM
> To: beehive-cvs@incubator.apache.org
> 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
{@link
> 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
> + * {@link
>
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,
>