mcconnell 2002/07/13 17:55:12
Modified: assembly build.xml
assembly/src/java/org/apache/excalibur/merlin/model
Association.java CategoryDescriptor.java
ClasspathDescriptor.java ContainerDescriptor.java
DirsetDescriptor.java ExtensionsDescriptor.java
FileTargetProvider.java FilesetDescriptor.java
IncludeDescriptor.java KernelDescriptor.java
LoggingDescriptor.java Profile.java
TargetDescriptor.java TargetProvider.java
assembly/src/java/org/apache/excalibur/merlin/model/doc-files
uml.gif
Log:
complete updates on the javadoc for the meta data model
Revision Changes Path
1.19 +2 -2 jakarta-avalon-excalibur/assembly/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/build.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- build.xml 13 Jul 2002 13:39:00 -0000 1.18
+++ build.xml 14 Jul 2002 00:55:12 -0000 1.19
@@ -268,8 +268,8 @@
<target name="patch">
<replace
- token="getComponentProfiles"
- value="getComponents" dir="src/java">
+ token="AbstractContainer"
+ value="Parent" dir="src/java">
<include name="org/apache/excalibur/merlin/**/*.*"/>
</replace>
</target>
1.3 +8 -9
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Association.java
Index: Association.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Association.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Association.java 13 Jul 2002 21:28:18 -0000 1.2
+++ Association.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -7,14 +7,13 @@
*/
package org.apache.excalibur.merlin.model;
-
-
/**
* The Association is the mapping of a component as a dependency
* of another component. Each component declares dependencies (via Type)
* and for each dependency there must be a coressponding Association which
- * has a matching role. The name value in Association object must refer
- * to another Component that implements a service as specified in DependencyInfo.
+ * has a matching role. The profile value in the Association is a reference to
+ * an assigned component profile that will act as the service supplier in
+ * accordance with the dependency constraint.
*
* <p>Note that it is invalid to have circular dependencies.</p>
*
@@ -36,10 +35,10 @@
private final Profile m_provider;
/**
- * Create Profile with specified name and role.
+ * Create an Association with specified name and provider.
*
* @param role the name client uses to access component
- * @param providerName the name of <code>Profile</code> instance
+ * @param provider the <code>Profile</code> instance
* that is associated as a service provider
*/
public Association( final String role,
@@ -62,10 +61,10 @@
}
/**
- * Return the name of a <code>Profile</code> instance that will used to
+ * Return the <code>Profile</code> instance that will used to
* fulfill the dependency.
*
- * @return the name of the Component that will provide the dependency.
+ * @return the profile that will fulfill the dependency.
*/
public Profile getProvider()
{
1.3 +57 -6
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/CategoryDescriptor.java
Index: CategoryDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/CategoryDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- CategoryDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ CategoryDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,10 +10,25 @@
import java.util.Hashtable;
import java.io.Serializable;
-
/**
- * A logging category descriptor hierachy.
+ * A logging category descriptor hierachy. The descriptor contains a category
name, a
+ * optional priority value, and an optional target. If the priority or target
values
+ * null, the resulting value will be derived from the parent category desciptor. A
+ * category descriptor may 0-n subsidiary categories. Category names are relative.
+ * For example, the category "orb" will appear as "my-app.orb" if the parent
category
+ * name is "my-app".
*
+ * <p><b>XML</b></p>
+ * <pre>
+ * <loggers priority="<font color="darkred">INFO</font>">
+ * <category priority="<font color="darkred">DEBUG</font>" name="<font
color="darkred">loader</font>" />
+ * <category priority="<font color="darkred">WARN</font>" name="<font
color="darkred">types</font>" />
+ * <category priority="<font color="darkred">ERROR</font>" name="<font
color="darkred">types.builder</font>" target="<font
color="darkred">default</font>"/>
+ * <category name="<font color="darkred">profiles</font>" />
+ * <category name="<font color="darkred">lifecycle</font>" />
+ * <category name="<font color="darkred">verifier</font>" />
+ * </loggers>
+ * </pre>
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
@@ -55,6 +70,9 @@
/**
+ * Creation of a new CategoryDescriptor with a parent and category name.
+ * @param parent the parent category
+ * @param name the category name
*/
public CategoryDescriptor( CategoryDescriptor parent, final String name )
{
@@ -62,6 +80,13 @@
}
/**
+ * Creation of a new CategoryDescriptor using a supplied name, priority and
target.
+ *
+ * @param name the category name
+ * @param priority the category priority - DEBUG, INFO, WARN, or ERROR
+ * @param target the name of a logging category target
+ *
+ * @see TargetDescriptor
*/
public CategoryDescriptor( final String name, final String priority, final
String target )
{
@@ -69,6 +94,15 @@
}
/**
+ * Creation of a new CategoryDescriptor using a supplied name, priority, target
and
+ * collection of subsidiary categories.
+ *
+ * @param name the category name
+ * @param priority the category priority - DEBUG, INFO, WARN, or ERROR
+ * @param target the name of a logging category target
+ * @param categories an array of subsidiary categories
+ *
+ * @see TargetDescriptor
*/
public CategoryDescriptor(
final String name, final String priority, final String target,
@@ -78,6 +112,16 @@
}
/**
+ * Creation of a new CategoryDescriptor using a supplied name, priority, target
and
+ * collection of subsidiary categories.
+ *
+ * @param parent the parent category
+ * @param name the category name
+ * @param priority the category priority - DEBUG, INFO, WARN, or ERROR
+ * @param target the name of a logging category target
+ * @param categories an array of subsidiary categories
+ *
+ * @see TargetDescriptor
*/
public CategoryDescriptor(
CategoryDescriptor parent, final String name, final String priority, final
String target,
@@ -148,13 +192,20 @@
return m_target;
}
+ /**
+ * Sets the parent category.
+ * @param parent the parent category from which the category name is relative
+ * and from which default priority and target information is derived
+ */
public void setParent( CategoryDescriptor parent )
{
m_parent = parent;
}
/**
- * Return the category path.
+ * Return the category path. A category path is a result of the concatination
of
+ * the names of the parent category names with this category name. Names are
seperated
+ * by the period character.
*
* @return the category path
*/
@@ -179,7 +230,7 @@
}
/**
- * Return the set of logging categories.
+ * Return the set of logging categories locally container in the category
descriptor.
*
* @return the set of service provider assignments.
*/
@@ -189,7 +240,7 @@
}
/**
- * Return a named category.
+ * Return a named category from the set of categories contained within this
category.
* @param name the category name
* @return the named category of null if unknown
*/
1.3 +31 -4
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ClasspathDescriptor.java
Index: ClasspathDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ClasspathDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ClasspathDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ ClasspathDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,18 +10,45 @@
import java.io.Serializable;
/**
- * A classpath descriptor.
+ * <p>A classpath descriptor that describes a scoped set of jar files. Classpath
+ * descriptors are contained with {@link KernelDescriptor} and
+ * {@link ContainerDescriptor} declarations.
+ * A classpath contains 0-n {@link FilesetDescriptor} instances.</p>
*
+ * <p><b>XML</b></p>
+ * <p>The XML form for a classpath description is shown below. The classpath
element contains
+ * no attributes. The element may contain multiple fileset elements that
collectively define
+ * the scope of the classpath.
+ * </p>
+ * <pre>
+ * <classpath>
+ *
+ * <font color="gray"><i><!--
+ * Declaration of multiple filesets.
+ * --></i></font>
+ *
+ * <fileset dir=<font color="darkred">"dist"</font>>
+ * <include name="<font color="darkred">demo.jar</font>"/>
+ * <include name="<font
color="darkred">new-application-1.0.jar</font>"/>
+ * </fileset>
+ *
+ * <fileset dir="<font color="darkred">lib</font>">
+ * <include name="<font color="darkred">avalon-framework.jar</font>"/>
+ * </fileset>
+ *
+ * </classpath>
+ * </pre>
+ *
+ * @see FilesetDescriptor
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
public class ClasspathDescriptor implements Serializable
{
/**
- * The base directory
+ * The collection of filesets.
*/
private final FilesetDescriptor[] m_filesets;
-
/**
* Create a ClasspathDescriptor instance.
1.6 +102 -22
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ContainerDescriptor.java
Index: ContainerDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ContainerDescriptor.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- ContainerDescriptor.java 13 Jul 2002 21:28:18 -0000 1.5
+++ ContainerDescriptor.java 14 Jul 2002 00:55:12 -0000 1.6
@@ -10,17 +10,83 @@
import java.util.ArrayList;
/**
- * A container profile.
+ * <p>A container descriptor is a description of the crieria supporting the
+ * construction of a container. It may may include a classpath, multiple
+ * component profile declarations, and multiple nested container declarations.</p>
+ *
+ * <p><b>XML</b><p>
+ * A single container element is required within a kernel defintion. Multiple
+ * container declarations may appear within an enclosing container.
+ * <pre>
+ * <font color="gray"><i><!--
+ * Definition of a container. The name attribute declares bother the container
+ * name and the base logging category that will be supplied to the container
+ * by its parent. Logging category defintions declared within the container
+ * declaration are relative to the container name.
+ * --></i></font>
+ *
+ * <container name="<font color="darkred">root</font>">
+ *
+ * <font color="gray"><i><!--
+ * Classpath declaration. Classes accessible to a component are constrained
+ * to the classes available in the jar files declared within the immediate
+ * classpath, together with and resources declared in any parent container.
+ * --></i></font>
+ *
+ * <classpath>
+ * <fileset dir="<font color="darkred">dist</font>">
+ * <include name="<font color="darkred">demo.jar</font>"/>
+ * <include name="<font
color="darkred">new-application-1.0.jar</font>"/>
+ * </fileset>
+ * </classpath>
+ *
+ * <font color="gray"><i><!--
+ * Logging categories declaration. Logging categories are relative to the
name of the
+ * enaclosing container. Logging priorities and targets will default to the
parent
+ * containtains values if undefined.
+ * --></i></font>
+ *
+ * <loggers priority="<font color="darkred">INFO</font>">
+ * <category name="<font color="darkred">profiles</font>" />
+ * <category name="<font color="darkred">lifecycle</font>" />
+ * <category name="<font color="darkred">verifier</font>" />
+ * </loggers>
+ *
+ * <font color="gray"><i><!--
+ * Multiple component profile declarations. If a component declares
dependecies,
+ * the container will attempt to resolve the dependency locally relative to
any
+ * other declared components, otherwise, the container will attempt to resolve
+ * the dependecy using services established (explicitly or implicitly) in the
+ * parent containers before attempting a local implicit solution.
+ * --></i></font>
+ *
+ * <component name="<font color="darkred">my-component</font>"
+ * class="<font
color="darkred">org.apache.excalibur.playground.SimpleComponent</font>" />
+ *
+ * <font color="gray"><i><!--
+ * Multiple subsidiary container declarations.
+ * --></i></font>
+ *
+ * <container name="<font color="darkred">child</font>">
+ * <component name="<font color="darkred">demo-component</font>"
class="<font color="darkred">org.apache.excalibur.playground.BasicComponent</font>"
/>
+ * <container>
+ *
+ * </container>
+ * </pre>
+ *
+ * @see Profile
+ * @see CategoryDescriptor
+ * @see ClasspathDescriptor
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
-public class ContainerDescriptor extends AbstractContainer
+public class ContainerDescriptor extends Parent
{
/**
* The parent.
*/
- private AbstractContainer m_parent;
+ private Parent m_parent;
/**
* The container name.
@@ -45,12 +111,15 @@
/**
* The component described within the scope of the container.
*/
- //private final ContainerDescriptor[] m_containers;
private final ArrayList m_containers = new ArrayList();
/**
* Create a ContainerDescriptor instance.
- *
+ * @param name the container name
+ * @param loggers the logging category descriptors
+ * @param classpath the containers local classpath
+ * @param components the set of components to be included in the container
+ * @param containers the set of subsidiary containers to include in the
container
*/
public ContainerDescriptor( final String name,
final CategoryDescriptor loggers,
@@ -133,6 +202,7 @@
/**
* Return the set of enabled or disable components based on the supplied
criteria.
+ *
* @param enabled TRUE to select enabled components, FALSE returs disabled
components
* @return the descriptors matching the supplied enabled status
*/
@@ -152,6 +222,7 @@
/**
* Return the set of component descriptors contained within this container
matching
* the supplied mode.
+ *
* @param mode one of enumerated value {@link Profile#IMPLICIT}, {@link
Profile#PACKAGED},
* or {@link Profile#EXPLICIT}
* @param enabled TRUE to select enabled components, FALSE returs disabled
compoents
@@ -167,6 +238,7 @@
/**
* Return the set of component descriptors contained within this container
matching
* the supplied mode.
+ *
* @param mode one of enumerated value {@link Profile#IMPLICIT}, {@link
Profile#PACKAGED},
* or {@link Profile#EXPLICIT},
* @return the descriptors matching the supplied creation mode
@@ -176,22 +248,10 @@
return selectComponentsByMode( getComponents(), mode );
}
- private Profile[] selectComponentsByMode( Profile[] components, int mode )
- {
- ArrayList list = new ArrayList();
- for( int i=0; i<components.length; i++ )
- {
- Profile component = components[i];
- if( component.getMode() == mode )
- list.add( component );
- }
- return (Profile[] ) list.toArray( new Profile[0] );
- }
-
/**
- * Add a container profile to this container.
+ * Add a container descriptor to this container.
*
- * @parent the container to add
+ * @param container the container to add
*/
public void addContainer( ContainerDescriptor container )
{
@@ -219,7 +279,7 @@
* @param the container containing this container.
* @exception IllegalStateException if the parent is already set
*/
- public void setParent( AbstractContainer parent ) throws IllegalStateException
+ public void setParent( Parent parent ) throws IllegalStateException
{
if( m_parent != null )
throw new IllegalStateException("parent");
@@ -232,8 +292,28 @@
*
* @return the container containing this container.
*/
- public AbstractContainer getParent()
+ public Parent getParent()
{
return m_parent;
}
+
+ /**
+ * Returns a sub-set of the supplied containers matching the supplied creation
mode.
+ * @param components the compoennts to select from
+ * @param mode the creation mode to retrict the returned selection to
+ * @param the subset of the supplied components with a creation mode matching
+ * the supplied mode value
+ */
+ private Profile[] selectComponentsByMode( Profile[] components, int mode )
+ {
+ ArrayList list = new ArrayList();
+ for( int i=0; i<components.length; i++ )
+ {
+ Profile component = components[i];
+ if( component.getMode() == mode )
+ list.add( component );
+ }
+ return (Profile[] ) list.toArray( new Profile[0] );
+ }
+
}
1.3 +18 -7
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/DirsetDescriptor.java
Index: DirsetDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/DirsetDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- DirsetDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ DirsetDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,8 +10,18 @@
import java.io.Serializable;
/**
- * A description of a directory set.
+ * <p>A description of a directory set. A directory set is a declaration of a
+ * a set of directories scoped relative to a parent directory.</p>
*
+ * <p><b>XML</b></p>
+ * <pre>
+ * <dirset dir="<font color="darkred">../system</font>">
+ * <include name="<font color="darkred">extensions</font>"/>
+ * <include name="<font color="darkred">lib</font>"/>
+ * </dirset>
+ * </pre>
+ *
+ * @see IncludeDescriptor
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
@@ -28,9 +38,11 @@
private final IncludeDescriptor[] m_includes;
/**
- * Create a FilesetDescriptor instance.
+ * Create a DirsetDescriptor instance using a base directory and a set of
+ * include statements that should reference directories relative to the base.
*
- * @param filesets the set of filesets to include in the classpath
+ * @param base the base directory from which include directory name will be
resolved
+ * @param includes the set of include directives
*/
public DirsetDescriptor( final String base, final IncludeDescriptor[] includes )
{
@@ -48,11 +60,10 @@
return m_base;
}
-
/**
- * Return the filesets held within the classpath descriptor.
+ * Return the set of include deirectives.
*
- * @return the filesets
+ * @return the include directives
*/
public IncludeDescriptor[] getIncludeDescriptors()
{
1.3 +17 -5
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ExtensionsDescriptor.java
Index: ExtensionsDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/ExtensionsDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ExtensionsDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ ExtensionsDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,7 +10,19 @@
import java.io.Serializable;
/**
- * An extensions descriptor.
+ * <p>An extensions descriptor that declares a set of directories to be used
+ * referenced as the installed extension directories. An extensions descriptor
+ * may contain multiple {@link DirsetDescriptor} instances.</p>
+ *
+ * <p><b>XML</b></p>
+ * <pre>
+ * <extensions>
+ * <dirset dir="<font color="darkred">.</font>">
+ * <include name="<font color="darkred">extensions</font>"/>
+ * <include name="<font color="darkred">lib</font>"/>
+ * </dirset>
+ * </extensions>
+ * </pre>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
@@ -26,7 +38,7 @@
/**
* Create a ExtensionsDescriptor instance.
*
- * @param filesets the set of filesets to include in the classpath
+ * @param dirs the set of dirsets to include in the classpath
*/
public ExtensionsDescriptor( final DirsetDescriptor[] dirs )
{
@@ -34,9 +46,9 @@
}
/**
- * Return the dirset held within the extensions descriptor.
+ * Return the dirsets held within the extensions descriptor.
*
- * @return the directory set
+ * @return the set of directory set instances
*/
public DirsetDescriptor[] getDirsetDescriptors()
{
1.3 +21 -2
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FileTargetProvider.java
Index: FileTargetProvider.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FileTargetProvider.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- FileTargetProvider.java 13 Jul 2002 00:09:45 -0000 1.2
+++ FileTargetProvider.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -9,8 +9,19 @@
/**
- * File target provider type.
+ * File target provider descriptor declares the criteria for the creation of
+ * an file based logging target provider.
+ *
+ * <p><b>XML</b></p>
+ * <p>A file target element may be contained within a target element to declare
+ * the target as a file based logging sink.</p>
+ * <pre>
+ * <font color="gray"><target name="kernel"></font>
+ * <file location="<font color="darkred">kernel.log</font>" />
+ * <font color="gray"></target></font>
+ * </pre>
*
+ * @see TargetDescriptor
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
@@ -18,11 +29,19 @@
{
private final String m_location;
+ /**
+ * Creation of a new file target.
+ * @param location the filename of the logging destination
+ */
public FileTargetProvider( final String location )
{
m_location = location;
}
+ /**
+ * Return the filename of the logging target.
+ * @return the filename
+ */
public String getLocation()
{
return m_location;
1.3 +15 -4
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FilesetDescriptor.java
Index: FilesetDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/FilesetDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- FilesetDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ FilesetDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,15 +10,26 @@
import java.io.Serializable;
/**
- * A fileset descriptor.
+ * <p>A fileset descriptor is a scoped defintion of a set of files. A fileset
+ * a structurally defined as a base directory and a set of relative filenames
+ * represented as include directives.</p>
*
+ * <p><b>XML</b></p>
+ * <pre>
+ * <fileset dir="<font color="darkred">lib</font>">
+ * <include name="<font color="darkred">avalon-framework.jar</font>"/>
+ * <include name="<font color="darkred">logkit.jar</font>"/>
+ * </dirset>
+ * </pre>
+ *
+ * @see IncludeDescriptor
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
public class FilesetDescriptor implements Serializable
{
/**
- * The base directory
+ * The base directory from which include directives will be resolved.
*/
private final String m_base;
@@ -30,7 +41,7 @@
/**
* Create a FilesetDescriptor instance.
*
- * @param filesets the set of filesets to include in the classpath
+ * @param includes the set of includes to include in the fileset
*/
public FilesetDescriptor( final String base, final IncludeDescriptor[] includes
)
{
1.3 +13 -3
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/IncludeDescriptor.java
Index: IncludeDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/IncludeDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- IncludeDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ IncludeDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,7 +10,17 @@
import java.io.Serializable;
/**
- * An file include directive.
+ * <p>An file include directive.</p>
+ * <p><b>XML</b></p>
+ * <p>An include element is normally contained within a scoping structure such as a
+ * fileset or directory set. The include element contains the single attribute name
+ * which is used to refer to the file or directory (depending on the containing
+ * context.</p>
+ * <pre>
+ * <font color="gray"><fileset dir="lib"></font>
+ * <include name="<font color="darkred">avalon-framework.jar</font>" />
+ * <font color="gray"></fileset></font>
+ * </pre>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
@@ -25,7 +35,7 @@
/**
* Create a FilesetDescriptor instance.
*
- * @param filesets the set of filesets to include in the classpath
+ * @param file the filename
*/
public IncludeDescriptor( final String file )
{
1.3 +89 -6
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/KernelDescriptor.java
Index: KernelDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/KernelDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- KernelDescriptor.java 12 Jul 2002 19:09:27 -0000 1.2
+++ KernelDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -8,12 +8,91 @@
package org.apache.excalibur.merlin.model;
/**
- * Kernel creation profile.
+ * Kernel creation directive that includes a root container, an extensions
directive,
+ * common application level classpath directive and logigng category descriptors.
+ *
+ * <p><b>XML</b></p>
+ * A kernel element may contain a logging defintion, extensions element, and
classpath
+ * element. A kernel element must contain a single root container element.</p>
+ * <pre>
+ * <font color="gray"><i><!--
+ * Definition of a kernel.
+ * --></i></font>
+ *
+ * <kernel>
+ *
+ * <font color="gray"><i><!--
+ * Logging catagory creation directive.
+ * --></i></font>
+ *
+ * <logging priority="<font color="darkred">INFO</font>" target="<font
color="darkred">kernel</font>">
+ * <target name="<font color="darkred">kernel</font>">
+ * <file location="<font color="darkred">kernel.log</font>" />
+ * </target>
+ * <loggers priority="<font color="darkred">WARN</font>">
+ * <category name="<font color="darkred">logging</font>"/>
+ * <category name="<font color="darkred">loader</font>"/>
+ * <category name="<font color="darkred">installer</font>"/>
+ * </loggers>
+ * </logging>
+ *
+ * <font color="gray"><i><!--
+ * Declaration of the extensions directories.
+ * --></i></font>
+ *
+ * <extensions>
+ * <dirset dir="<font color="darkred">.</font>">
+ * <include name="<font color="darkred">extensions</font>"/>
+ * <include name="<font color="darkred">lib</font>"/>
+ * </dirset>
+ * </extensions>
+ *
+ * <font color="gray"><i><!--
+ * Common application classpath declaration.
+ * --></i></font>
+ *
+ * <classpath>
+ * <fileset dir="<font color="darkred">dist</font>">
+ * <include name="<font
color="darkred">new-application-1.0.jar</font>"/>
+ * </fileset>
+ * </classpath>
+ *
+ * <font color="gray"><i><!--
+ * Single root container declaration.
+ * --></i></font>
+ *
+ * <container name="<font color="darkred">child</font>">
+ * <classpath>
+ * <fileset dir="<font color="darkred">dist</font>">
+ * <include name="<font color="darkred">demo.jar</font>"/>
+ * </fileset>
+ * </classpath>
+ * <component name="<font color="darkred">demo-component</font>"
class="<font color="darkred">org.apache.excalibur.playground.BasicComponent</font>">
+ * <loggers priority="<font color="darkred">WARN</font>">
+ * <category name="<font color="darkred">cache</font>"/>
+ * <category name="<font color="darkred">store</font>"/>
+ * </loggers>
+ * <context>
+ * <entry name="<font color="darkred">location</font>" value="<font
color="darkred">Paris</font>"/>
+ * </context>
+ * </component>
+ * <container>
+ * <font color="gray"><i><!-- Etc., etc. --></i></font>
+ * </container>
+ * </container>
+ *
+ * </kernel>
+ * </pre>
+ *
+ * @see ClasspathDescriptor
+ * @see ExtensionsDescriptor
+ * @see LoggingDescriptor
+ * @see ContainerDescriptor
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
-public class KernelDescriptor extends AbstractContainer
+public class KernelDescriptor extends Parent
{
/**
@@ -39,6 +118,10 @@
/**
* Create a KernelDescriptor instance.
*
+ * @param name the kernel name
+ * @param logging the logging defaults and top level categories
+ * @param extensions the declaration of the extensions directories
+ * @param container the root container
*/
public KernelDescriptor( final String name,
final LoggingDescriptor logging,
@@ -71,9 +154,9 @@
}
/**
- * Return the classpath descriptor.
+ * Return the extensions descriptor.
*
- * @return the {@link ClasspathDescriptor} for the container.
+ * @return the {@link ExtensionsDescriptor} for the kernel.
*/
public ExtensionsDescriptor getExtensionsDescriptor()
{
@@ -83,7 +166,7 @@
/**
* Return the classpath descriptor.
*
- * @return the {@link ClasspathDescriptor} for the container.
+ * @return the {@link ClasspathDescriptor} for the kernel.
*/
public ClasspathDescriptor getClasspathDescriptor()
{
1.3 +41 -1
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/LoggingDescriptor.java
Index: LoggingDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/LoggingDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- LoggingDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ LoggingDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -12,6 +12,41 @@
/**
* Description of a top level logging environment.
*
+ * <p><b>XML</b></p>
+ * <p>A logging element declares the top level defaults for priority and target
name, a set of
+ * targets to which logging events shall be directoed, and the root set of logging
categories.
+ * The logging element declares the application wide default logging priority.
+ * A target element enables defintion of a logging file to which log entries will
+ * be directed. The target name attribute is the name referenced by category
elements
+ * defined within the loggers element. Child category declarations must include a
name
+ * (the logging catagory), and may optionally include a target and a priority
attribute.
+ * The target defaults of "default" which corresponds to a internal default logging
+ * target that issue messages to System.out (unless overriden by a target named
default).
+ * If the target is declared inside a catagory element, it must refer to a named
target
+ * element. The priority attribute may container one of the values
<code>DEBUG</code>
+ * <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code> or <code>ERROR</code>.
+ * The target must contain a single file element with the attribute
<code>location</code>
+ * the corresponds to the name of the logging file.</p>
+ *
+ * <pre>
+ * <font color="gray"><i><!--
+ * Definition of a logging system.
+ * --></i></font>
+ *
+ * <logging priority="<font color="darkred">INFO</font>" target="<font
color="darkred">kernel</font>">
+ * <target name="<font color="darkred">kernel</font>">
+ * <file location="<font color="darkred">kernel.log</font>" />
+ * </target>
+ * <loggers priority="<font color="darkred">WARN</font>">
+ * <category name="<font color="darkred">logging</font>"/>
+ * <category name="<font color="darkred">loader</font>"/>
+ * <category name="<font color="darkred">installer</font>"/>
+ * </loggers>
+ * </logging>
+ * </pre>
+ *
+ * @see CategoryDescriptor
+ * @see TargetDescriptor
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
@@ -39,6 +74,11 @@
/**
* Create a LoggingDescriptor instance.
+ *
+ * @param priority the system wide default logging priority
+ * @param target the system wide default logging target
+ * @param targets the set of logging targets
+ * @param category the root logging category descriptor
*/
public LoggingDescriptor( final String priority,
final String target,
1.5 +101 -32
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Profile.java
Index: Profile.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Profile.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Profile.java 13 Jul 2002 15:35:25 -0000 1.4
+++ Profile.java 14 Jul 2002 00:55:12 -0000 1.5
@@ -17,7 +17,68 @@
import org.apache.excalibur.configuration.ConfigurationUtil;
/**
- * Abstract defintion of a compoent profile.
+ * Defintion of the criteria for an explicit component profile. A profile, when
+ * included withi the scope of a container declaration will be instantiated in
+ * the model as an EXPLICT component profile resulting in the intiation of
+ * dependecy resolution relative to the component as the target deployment
+ * objective. Multiple supplimentary profiles may be packaged in a .xprofiles
+ * resources and will be assigned to the container automatically. In the absence
+ * of explicit or packaged profile directives, an implicit profile will be created
+ * for any component types declared under a jar manifest.
+ *
+ * <p><b>XML</b></p>
+ * <p>A component element declares the profile to be applied during the
instantiation
+ * of a component type. In includes a name and class declaration, logging
directives
+ * (resolved relative to the components's container), context creation criteria,
+ * together with configuration or parameters information.</p>
+ *
+ * <pre>
+ <font color="gray"><i><!--
+ Declaration of the services hosted by this container. Service container here
+ will be managed relative to other provider components at the same level and
+ may be serviced by components declared in parent container.
+ --></i></font>
+
+ <component name="<font color="darkred">complex</font>" class="<font
color="darkred">org.apache.excalibur.playground.ComplexComponent</font>">
+
+ <loggers priority="<font color="darkred">DEBUG</font>">
+ <category name="<font color="darkred">init</font>" priority="<font
color="darkred">DEBUG</font>" />
+ </loggers>
+
+ <font color="gray"><i><!--
+ Include the following context value in the context supplied a component
using this
+ profile. Context entries are normally only required in the case where the
component
+ type declares a required context type and entry values. Generally speaking,
a component
+ will normally qualify it's instantiation criteria through a configuration
declaration.
+ Any context values defined at this level will override context values
supplied by the
+ container.
+ --></i></font>
+
+ <context>
+ <entry name="<font color="darkred">location</font>" value="<font
color="darkred">Paris</font>"/>
+ </context>
+
+ <font color="gray"><i><!--
+ Apply the following configuration when instantiating the component. This
configuration
+ will be applied as the primary configuration in a cascading configuration
chain. A
+ type may declare a default configuration under a "classname".xconfig file
that will be
+ used to dereference any configuration requests not resolvable by the
configuration
+ supplied here.
+ --></i></font>
+
+ <configuration>
+ <message value="<font color="darkred">Hello</font>"/>
+ </configuration>
+
+ <font color="gray"><i><!--
+ The parameterization criteria from this instance of the component type.
+ --></i></font>
+
+ <parameters/>
+
+ </component>
+ * </pre>
+ *
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
@@ -42,7 +103,7 @@
public static final int EXPLICIT = 2;
/**
- * The name of the component metadata instance. This is an
+ * The name of the component profile. This is an
* abstract name used during assembly.
*/
private final String m_name;
@@ -92,8 +153,12 @@
* Create a Profile instance.
*
* @param name the abstract name of component meta data instance
- * @param dependencies the meta data for any dependencies
- * @param type the component type
+ * @param parameters the parameters instance to use during type instantiation
+ * @param configuration the configuration instance to use during type
instantiation
+ * @param context the context instance to use during type instantiation
+ * @param type the type of component that this profile qualifies
+ * @param enabled the enabled state of the component profile
+ * @param mode the creation mode (either IMPLICIT, PACKAGED, or EXPLICIT)
*/
public Profile( final String name,
final Parameters parameters,
@@ -132,7 +197,7 @@
* assembly directive, or implicity disabled as a result of an assembly failure.
*
* @return TRUE if the profile is enabled.
- * @see #isAvailable()
+ * @see #setEnabled( boolean )
*/
public boolean isEnabled()
{
@@ -179,9 +244,10 @@
}
/**
- * Return the Context for component (if any).
+ * Return the Context for profile. This operation may be changed to a
+ * ContextDirective in the near future.
*
- * @return the Context for component (if any).
+ * @return the Context for component.
*/
public Context getContext()
{
@@ -189,7 +255,7 @@
}
/**
- * Return the Parameters for Component (if any).
+ * Return the Parameters for the profile.
*
* @return the Parameters for Component (if any).
*/
@@ -199,9 +265,9 @@
}
/**
- * Return the Configuration for Component (if any).
+ * Return the Configuration for the profile.
*
- * @return the Configuration for Component (if any).
+ * @return the Configuration for profile.
*/
public Configuration getConfiguration()
{
@@ -219,7 +285,7 @@
}
/**
- * Return the dependency metadata for component type with specified role.
+ * Return the dependency associations for component type with specified role.
*
* @return the dependency metadata for component with specified role.
*/
@@ -249,6 +315,10 @@
return association;
}
+ /**
+ * Returns a string representation of the profile.
+ * @return a string representation
+ */
public String toString()
{
return "Profile name: " + getName()
@@ -256,26 +326,6 @@
+ ", mode: " + modeToString( getMode() );
}
- private String modeToString( int mode )
- {
- if( mode == IMPLICIT )
- {
- return "IMPLICIT";
- }
- else if( mode == PACKAGED )
- {
- return "PACKAGED";
- }
- else if( mode == EXPLICIT )
- {
- return "EXPLICIT";
- }
- else
- {
- return "?";
- }
- }
-
/**
* Provide a textual report on the profile.
* @return the formatted profile report
@@ -318,4 +368,23 @@
return buffer.toString();
}
+ private String modeToString( int mode )
+ {
+ if( mode == IMPLICIT )
+ {
+ return "IMPLICIT";
+ }
+ else if( mode == PACKAGED )
+ {
+ return "PACKAGED";
+ }
+ else if( mode == EXPLICIT )
+ {
+ return "EXPLICIT";
+ }
+ else
+ {
+ return "?";
+ }
+ }
}
1.3 +12 -4
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetDescriptor.java
Index: TargetDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TargetDescriptor.java 13 Jul 2002 00:09:45 -0000 1.2
+++ TargetDescriptor.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -12,6 +12,15 @@
/**
* A logging target descriptor.
*
+ * <p><b>XML</b></p>
+ * A logging target declares target name and a mechanism.</p>
+ *
+ * <pre>
+ * <target name="<font color="darkred">kernel</font>">
+ * <file location="<font color="darkred">kernel.log</font>" />
+ * </target>
+ * </pre>
+ *
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
*/
@@ -30,9 +39,8 @@
/**
* Create a LoggingDescriptor instance.
*
- * @param name the abstract name of component meta data instance
- * @param dependencies the meta data for any dependencies
- * @param type the component type
+ * @param name the target name
+ * @param provider the target provider description
*/
public TargetDescriptor( final String name,
final TargetProvider provider )
1.3 +3 -2
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetProvider.java
Index: TargetProvider.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/TargetProvider.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TargetProvider.java 13 Jul 2002 00:09:45 -0000 1.2
+++ TargetProvider.java 14 Jul 2002 00:55:12 -0000 1.3
@@ -10,7 +10,8 @@
import java.io.Serializable;
/**
- * Abstract logging target provider type.
+ * Abstract logging target provider type. This is an emty abstract class from
+ * all logging providers must inherit.
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Stephen McConnell</a>
* @version $Revision$ $Date$
1.3 +27 -18
jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/doc-files/uml.gif
<<Binary file>>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
