mcconnell 2003/01/28 05:26:12
Modified: assembly/src/java/org/apache/avalon/assembly/appliance
Appliance.java DefaultAppliance.java
Log:
Appliance documention updates - dedicated to Leo ;-)
Revision Changes Path
1.24 +11 -8
avalon-sandbox/assembly/src/java/org/apache/avalon/assembly/appliance/Appliance.java
Index: Appliance.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/assembly/src/java/org/apache/avalon/assembly/appliance/Appliance.java,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- Appliance.java 18 Jan 2003 16:19:31 -0000 1.23
+++ Appliance.java 28 Jan 2003 13:26:11 -0000 1.24
@@ -69,11 +69,13 @@
import org.apache.avalon.meta.info.Type;
/**
- * An appliance is a class that encapsulates the deployment criteria
- * for a particular component together with a the state supporting
- * component assembly and dependency solutions. The function of an appliance
- * is to serve as the aggregation point for the deployment of a component
- * and the access point for services provided by the component implemetation.
+ * An appliance manages the establishment of a component
+ * type relative to a deployment criteria. Once established, an appliance
+ * provides support for the deployment of component instances on request.
+ * An appliance is responsible for component lifestyle and lifecycle
+ * management during the deployment and decommission cycles.
+ *
+ * @see DefaultAppliance
*
* @author <a href="mailto:avalon-dev@jakarta.apache.org";>Avalon Development
Team</a>
* @version $Revision$ $Date$
@@ -184,9 +186,10 @@
Context getContext();
/**
- * Return the context provider.
+ * Return the context provider. This is a component that
+ * will be used to apply the contextualization strategy.
*
- * @return the appliance mapped as provider of the context
+ * @return the appliance mapped as provider of the context (may be null)
*/
Appliance getContextProvider();
1.28 +51 -4
avalon-sandbox/assembly/src/java/org/apache/avalon/assembly/appliance/DefaultAppliance.java
Index: DefaultAppliance.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/assembly/src/java/org/apache/avalon/assembly/appliance/DefaultAppliance.java,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- DefaultAppliance.java 23 Jan 2003 12:11:27 -0000 1.27
+++ DefaultAppliance.java 28 Jan 2003 13:26:12 -0000 1.28
@@ -90,10 +90,57 @@
/**
- * Default implementation of an appliance that supports the association of
- * depedent appliance instances, appliance lifestyle handler, and establishes
- * the appliance URL.
+ * <p>The DefaultAppliance class manages the establishment of a component
+ * type relative to a deployment criteria. Once established, an appliance
+ * provides support for the deployment of component instances on request.
+ * An appliance is responsible for component lifestyle and lifecycle
+ * management during the deployment and decommission cycles.</p>
+
+ * <p>The implementation supports the association of possibly multiple
+ * appliance instances as service providers in accordance with component
+ * type dependency declarations during assembly. Once assembled, an
+ * appliance is capable of handling <code>resolve</code> and
<code>release</code>
+ * requests. Components instances returned from the <code>resolve</code>
+ * method are guaranteed to be fully deployed. Client applications may
+ * subsequently <code>release</code> the acquired component back to the
+ * appliance when no longer needed. The appliance implementation will apply
+ * appropriate recovery policies based on the lifestyle policy associated
+ * with the component type.</p>
*
+ * <p><b>Code Example</b></p>
+ * <pre>
+ *
+ * //
+ * // get a deployment template for a component and use this to
+ * // create an appliance context
+ * //
+ *
+ * [EMAIL PROTECTED] Engine} engine = (Engine)
Thread.currentThread().getContextClassLoader();
+ * [EMAIL PROTECTED] RepositoryManager} repository =
engine.getRepository();
+ * [EMAIL PROTECTED] Type} type = repository.getTypeManager().getType(
"MyComponent" );
+ * [EMAIL PROTECTED] Profile} profile =
repository.getProfileManager().getProfile( type );
+ * [EMAIL PROTECTED] DefaultApplianceContext} context = new
DefaultApplianceContext( profile );
+ * context.makeReadOnly();
+ *
+ * //
+ * // create and assembly an appliance then use the appliance to get
+ * // a fully deployed component reference
+ * //
+ *
+ * [EMAIL PROTECTED] Appliance} appliance = engine.createAppliance(
context );
+ * [EMAIL PROTECTED] DependencyGraph} graph = new DependencyGraph();
+ * appliance.assemble( graph );
+ * Object object = appliance.resolve( this );
+ *
+ * //
+ * // after finishing with the return object, release it back to
+ * // the appliance
+ * //
+ *
+ * appliance.release( object, this );
+ *
+ * </pre>
+ * @see ApplianceContext
* @author <a href="mailto:avalon-dev@jakarta.apache.org";>Avalon Development
Team</a>
* @version $Revision$ $Date$
*/
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
