You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by cr...@apache.org on 2001/11/25 07:20:59 UTC
cvs commit: jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util ContextSupport.java MapEntry.java ScopeSupport.java
craigmcc 01/11/24 22:20:59
Modified: workflow/src/java/org/apache/commons/workflow/core
package.html
workflow/src/java/org/apache/commons/workflow/io
package.html
workflow/src/java/org/apache/commons/workflow/util
ContextSupport.java MapEntry.java ScopeSupport.java
Log:
Finish documenting the Step implementations in the "core" and "io" packages.
Clean up a few JavaDoc warnings.
Revision Changes Path
1.5 +225 -29 jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/core/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/core/package.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- package.html 2001/11/19 06:40:17 1.4
+++ package.html 2001/11/25 06:20:58 1.5
@@ -19,7 +19,6 @@
as in the following example:</p>
<pre>
<base:activity id="Demonstration Activity"
- xmlns:base="http://jakarta.apache.org/commons/workflow/base"
xmlns:core="http://jakarta.apache.org/commons/workflow/core"
>
@@ -67,9 +66,10 @@
<code><core:descriptor></code> elements, and transfers control to the
specified step if ALL of them are <code>true</code> (if boolean) or not null
(if Object). To avoid non-deterministic evaluation stack behavior, all of
-the nested <code><core:descriptor> elements are always evaluated.</p>
+the nested <code><core:descriptor></code> elements are always
+evaluated.</p>
-<p>The <em>core:and</em> element recognizes the following attributes:
+<p>The <em>core:and</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -107,7 +107,7 @@
Activity executes an <a href="#core:exit">core:exit</a> Step, or the last
defined Step in the Activity has been executed.</p>
-<p>The <em>core:call</em> element recognizes the following attributes:
+<p>The <em>core:call</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -134,7 +134,7 @@
argument(s) to the constructor, are defined by the nested
<a href="core:descriptor">core:descriptor</a> elements.</p>
-<p>The <em>core:construct</em> element recognizes the following attributes:
+<p>The <em>core:construct</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -159,6 +159,9 @@
<p><strong>FIXME</strong> - Currently, this Step does not correctly recognize
constructors that accept primitive argument types.</p>
+<p><strong>FIXME</strong> - We need a better way to deal with exceptions
+(either checked or unchecked) thrown by calling the constructor.</p>
+
<p>In the example below, it is assumed that the top item on the evaluation
stack is an instance of <code>java.lang.Class</code>, produced by some
unspecified previous processing. This class has a constructor that takes
@@ -182,7 +185,7 @@
scenarios where you execute Steps that consume items from the stack, but you
wish to maintain a reference to the top object.</p>
-<p>The <em>core:duplicate</em> element recognizes the following attributes:
+<p>The <em>core:duplicate</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -208,7 +211,7 @@
Otherwise, the <code>Context.execute()</code> call from the application will
return control to the calling application.</p>
-<p>The <em>core:exit</em> element recognizes the following attributes:
+<p>The <em>core:exit</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -219,15 +222,110 @@
<a name="core:get"></a>
<h3>core:get</h3>
+<p>The <em>core:get</em> Step makes a copy of the properties specified
+by all nested <code><core:descriptor></code> elements, and pushes them
+on to the evaluation stack, in the order that the descriptors are listed.</p>
+<p>The <em>core:get</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+<p>You may nest any number of <a href="#core:descriptor">core:descriptor</a>
+elements within a <em>core:get</em> element. All of them will be evaluated
+in the order listed, and the corresponding property values will be pushed on to
+the evaluation stack.</p>
+
+<p>In the following example, the four specified properties of the
+<code>address</code> bean will be extracted and pushed on to the
+evaluation stack.</p>
+<pre>
+ <strong><core:get></strong>
+ <core:descriptor xpath="address/street1"/>
+ <core:descriptor xpath="address/city"/>
+ <core:descriptor xpath="address/state"/>
+ <core:descriptor xpath="address/zipCode"/>
+ <strong></core:get></strong>
+</pre>
+
+
<a name="core:goto"></a>
<h3>core:goto</h3>
+<p>The <em>core:goto</em> Step unconditionally transfers control to the
+Step specified by the <code>step</code> attribute. This value must match
+the <code>id</code> attribute of some other Step in the current Activity,
+which can occur either before or after the current Step.
+
+<p>The <em>core:goto</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+<li><strong>step</strong> - Identifier of the Step to which control
+ should be unconditionally transferred.</li>
+</ul>
+
<a name="core:invoke"></a>
<h3>core:invoke</h3>
+<p>The <em>core:invoke</em> Step calls a specified method on a specified
+bean instance, passing the specified values, and pushes the return value
+(if any) on to the evaluation tack. The specified bean instance, and the
+arguments to be passed, are defined by the nested
+<a href="core:descriptor">core:descriptor</a> elements.</p>
+
+<p>The <em>core:invoke</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+<li><strong>method</strong> - Name of the method to be called on the
+ bean instance specified by the first nested descriptor.</li>
+</ul>
+
+<p>At least one nested <em>core:descriptor</em> element is required, although
+more than one are allowed. They are interpreted as follows:</p>
+<ul>
+<li>The <strong>first</strong> descriptor must identify an non-null instance
+ of any Java class.
+ For script readability, you can use <code>core:bean</code> as an
+ alias for <code>core:descriptor</code> in the first nested descriptor,
+ but it is interpreted identically.</li>
+<li>Any subsequent descriptors represent arguments to the method, in the
+ order they are defined on the constructor itself. The
+ workflow engine will attempt to find a matching method on the
+ specified class (throwing an exception if none can be found), and will
+ then use that method to perform the call.
+</ul>
+
+<p><strong>FIXME</strong> - Currently, this Step does not correctly recognize
+constructors that accept primitive argument types.</p>
+<p><strong>FIXME</strong> - We need a better way to deal with exceptions
+(either checked or unchecked) thrown by calling the method.</p>
+
+<p>In the example below, it is assumed that the Customer bean specified
+by the first descriptor includes a public <code>addAddress</code> method
+that takes a String argument (the address type), and an address object
+(ours is in the "address" bean).</p>
+<pre>
+ <core:string value="Home"/>
+ <strong><core:invoke method="addAddress"></strong>
+ <core:bean xpath="customer"/>
+ <core:descriptor/> <-- The String we just pushed -->
+ <core:descriptor xpath="address"/>
+ <strong></core:invoke></strong>
+</pre>
+
+<p>In this case, the <code>addAddress()</code> method is of type
+<code>void</code>, so it returns no value. If a value had been returned,
+it would have been pushed on to the evaluation stack.</p>
+
+
<a name="core:load"></a>
<h3>core:load</h3>
@@ -237,7 +335,7 @@
The name of the class to be loaded can be specified either statically
or dynamically.</p>
-<p>The <em>core:load</em> element recognizes the following attributes:
+<p>The <em>core:load</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -271,12 +369,13 @@
nested <code><core:descriptor></code> elements, and transfers control
to the specified step if ALL of them are <code>false</code> (if boolean) or
null (if Object). To avoid non-deterministic evaluation stack behavior, all of
-the nested <code><core:descriptor> elements are always evaluated.</p>
+the nested <code><core:descriptor></code> elements are
+always evaluated.</p>
<p><em>NOTE:</em> - This is the exact opposite of
<a href="#and">and</a>.</p>
-<p>The <em>core:notAnd</em> element recognizes the following attributes:
+<p>The <em>core:notAnd</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -313,12 +412,13 @@
nested <code><core:descriptor></code> elements, and transfers control
to the specified step if ANY of them are <code>false</code> (if boolean) or
null (if Object). To avoid non-deterministic evaluation stack behavior, all of
-the nested <code><core:descriptor> elements are always evaluated.</p>
+the nested <code><core:descriptor></code> elements are
+always evaluated.</p>
<p><em>NOTE:</em> - This is the exact opposite of
<a href="#or">or</a>.</p>
-<p>The <em>core:notOr</em> element recognizes the following attributes:
+<p>The <em>core:notOr</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -355,9 +455,10 @@
<code><core:descriptor></code> elements, and transfers control to the
specified step if ANY of them are <code>true</code> (if boolean) or not null
(if Object). To avoid non-deterministic evaluation stack behavior, all of
-the nested <code><core:descriptor> elements are always evaluated.</p>
+the nested <code><core:descriptor></code> elements are
+always evaluated.</p>
-<p>The <em>core:or</em> element recognizes the following attributes:
+<p>The <em>core:or</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -390,14 +491,75 @@
<a name="core:pop"></a>
<h3>core:pop</h3>
+<p>The <em>core:pop</em> Step unconditionally pops the top object off of
+the evaluation stack, and throws it away.</p>
+<p>The <em>core:pop</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+
<a name="core:put"></a>
<h3>core:put</h3>
+<p>The <em>core:put</em> Step pops a value off of the evaluation stack
+for each nested <code><core:descriptor></code> element, and sets the
+property specified by the descriptor, in the order that the descriptors
+are listed.</p>
+
+<p>The <em>core:put</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+<p>You may nest any number of <a href="#core:descriptor">core:descriptor</a>
+elements within a <em>core:put</em> element. All of them will be evaluated
+in the order listed, and the corresponding property values will be set from values
+popped from the evaluation stack.</p>
+
+<p>In the following example, the four specified properties of the
+<code>address</code> bean will be set from values popped off of the
+evaluation stack (presumably put there by processing like that of the
+<code>core:get</code> example).</p>
+<pre>
+ <strong><core:put></strong>
+ <core:descriptor xpath="address/zipCode"/>
+ <core:descriptor xpath="address/state"/>
+ <core:descriptor xpath="address/city"/>
+ <core:descriptor xpath="address/street1"/>
+ <strong></core:put></strong>
+</pre>
+
+
<a name="core:remove"></a>
<h3>core:remove</h3>
+<p>The <em>core:remove</em> Step evaluates the nested descriptors, and
+removes the corresponding objects from the appropriate Scope in our Context,
+in the order that the nested descriptors are specified. After objects are removed,
+they are no longer accessible via Steps like <a href="#core:get">core:get</a>.</p>
+
+<p>The <em>core:remove</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+<p>In the example below, the "address" and "customer" beans are removed
+from our local Context, presumably because they are no longer needed:</p>
+<pre>
+ <strong><core:remove></strong>
+ <core:descriptor xpath="address"/>
+ <core:descriptor xpath="customer"/>
+ <strong></core:remove></strong>
+</pre>
+
<a name="core:string"></a>
<h3>core:string</h3>
@@ -405,7 +567,7 @@
<p>The <em>core:string</em> Step pushes the specified literal String value
onto the top of the evaluation stack.</p>
-<p>The <em>core:string</em> element recognizes the following attributes:
+<p>The <em>core:string</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -436,7 +598,7 @@
on the next call to <code>Context.execute()</code>, without the calling
application needing to be aware of the nesting.</p>
-<p>The <em>core:suspend</em> element recognizes the following attributes:
+<p>The <em>core:suspend</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -468,7 +630,7 @@
stack. This can be useful when previous processing has generated items on the
stack that are not in the desired order for future processing.</p>
-<p>The <em>core:swap</em> element recognizes the following attributes:
+<p>The <em>core:swap</em> element recognizes the following attributes:</p>
<ul>
<li><strong>id</strong> - Optional identifier of this Step, which can be used
as the destination for control transfers. If specified, must be unique
@@ -483,10 +645,50 @@
<a name="core:descriptor"></a>
<h3>core:descriptor</h3>
-<p>A <em>descriptor</em> is a description of the mechanism by which an
-arbitrary Java object (typically a JavaBean) in some Scope is referenced.
-The following reference methods are supported, and are processed in the
-order specified here:</p>
+<p>A <em>core:descriptor</em> element is a description of the mechanism
+by which an arbitrary Java object (typically a JavaBean) in some Scope, is
+referenced. This element recognizes the following attributes:</p>
+<ul>
+<li><strong>name</strong> - The name under which this bean is stored,
+ optionally located in the Scope specified by the <code>scope</code>
+ attribute.</li>
+<li><strong>scope</strong> - The name of the Scope within which to
+ search for the bean named by the <code>name</code> attribute. If
+ not specified, the corresponding bean will be searched for in all Scopes,
+ in ascending numeric order.</li>
+<li><strong>type</strong> - Fully qualified Java class name that is expected
+ (or set) via this descriptor. If not specified, the actual Java class of the
+ corresponding bean will be used. This is useful, for example, when
+ specifying the arguments to a <a href="#core:invoke">core:invoke</a>
+ Step, and the invoked method expects a Java interface that is implemented
+ by the actual object being passed as a parameter.</li>
+<li><strong>xpath</strong> - An alternative method (to the <code>name</code>
+ and <code>scope</code> attributes) for specifying the bean instance to be
+ accessed by this descriptor.</li>
+</ul>
+
+<p>The syntax for XPath expressions is a sequence of one or more
+identifier strings, separated by forward slash ("/") characters. The expression
+is evaluated as follows:</p>
+<ul>
+<li>If no slashes are present, the expression is assumed to be the name
+ of an object that is stored in the "local" scope.</li>
+<li>If one slash is present, the value before the slash is assumed to be the
+ name of the scope in which to locate the bean, while the value after the
+ slash is the name under which the bean is stored in that scope. For
+ example, the WebContext implementation of Context (commonly used
+ when implementing Workflow in a servlet based environment), the scope
+ names "request", "session", and "application" correspond to the
+ request attributes, session attributes, and servlet context attributes
+ provided by the underlying servlet container.</li>
+<li>If more than one slash is present, the value before the first slash
+ is interpreted as a scope name, as above. The remainder of the
+ expression accessed nested properties of beans, according to the
+ syntax specified by the Commons JXPath package.</li>
+</ul>
+
+<p>When deciding what bean a particular descriptor applies to, the following
+rules are applied, in this priority order:</p>
<ul>
<li>If the <em>xpath</em> attribute is set, it is used as an
XPath expression identifying the requested object.</li>
@@ -497,14 +699,8 @@
evaluation stack of our current <code>Context</code> is popped off the
stack and consumed.</li>
</ul>
-
-<p>Besides the attributes listed above, you can also specify an optional
-<em>type</em> attribute containing the fully qualified class name of the
-Java class that the referenced object is expected to be assignment-compatible
-with (i.e. this is either a class name of the class itself, a class name of a
-superclass, or an interface implemented by this object's class). This value
-is used only by particular Step implementations, as defined in the
-descriptions for those Steps.</p>
+<p><strong>FIXME</strong> - Support the <code>property</code> attribute
+for access to bean properties via the Commons Beanutils package.</p>
</body>
1.2 +230 -9 jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/io/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/io/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 2001/08/13 21:18:26 1.1
+++ package.html 2001/11/25 06:20:58 1.2
@@ -1,15 +1,236 @@
<body>
-<p>Implementations of <code>Steps</code> in the <code>io</code>
-namespace.</p>
+<p>Implementations of <code>Steps</code> in the <em>io</em> library.</p>
-<p>This package contains the following sets of classes:</p>
+<div align="center">
+<h2>I/O Step Library - Overview</h2>
+</div>
+
+<p>This package contains
+<a href="../Step.html">org.apache.commons.workflow.Step</a> implementations
+for the <em>io</em> library. This library includes Steps for importing
+information from (or exporting information to) external locations.</p>
+
+<p>The sections below define each of the Step definitions included in this
+library, utilizing the XML syntax that is recognized by the Digester used to
+process your Activity definition files. Although you can use any namespace
+prefix, the convention is to declare <code>io</code> as the namespace prefix,
+as in the following example:</p>
+<pre>
+ <base:activity id="Demonstration Activity"
+ xmlns:core="http://jakarta.apache.org/commons/workflow/core"
+ xmlns:io="http://jakarta.apache.org/commons/workflow/io"
+ >
+
+ <io:write file="topitem.txt"/>
+
+ </base:activity>
+</pre>
+
+<p><em>NOTE</em> - It is <strong>not</strong> required that you use the XML
+syntax, processed with a Digester, to initialize the Steps associated with
+each Activity. However, this usage is very convenient, and is likely to be
+the most common case, so the Steps are documented from that perspective. To
+use the underlying implementation classes directly, see the Javadocs for each
+Step implementation class, just as you would for any other Java class.</p>
+
+<div align="center">
+[<a href="#io:display">io:display</a>]
+[<a href="#io:get">io:get</a>]
+[<a href="#io:peek">io:peek</a>]
+[<a href="#io:read">io:read</a>]
+[<a href="#io:write">io:write</a>]
+</div>
+
+<div align="center">
+<h2>I/O Step Library - Step Definitions</h2>
+</div>
+
+<a name="io:display"></a>
+<h3>io:display</h3>
+
+<p>The <em>io:display</em> Step evaluates the properties specified by
+all nested <code><io:descriptor></code> elements, converts them to
+String (if necessary), and prints them to Java's standard output.</p>
+
+<p>The <em>io:display</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+<p>You may nest any number of <a href="#io:descriptor">io:descriptor</a>
+elements within a <em>io:display</em> element. All of them will be evaluated
+and displayed in order specified.</p>
+
+<p>In the following example, the "address" and "customer" beans will
+be converted to Strings (by calling their <code>toString()</code> methods)
+and the results displayed to standard output.</p>
+<pre>
+ <strong><io:display ></strong>
+ <io:descriptor xpath="address"/>
+ <io:descriptor xpath="customer"/>
+ <strong></io:display></strong>
+</pre>
+
+
+<a name="io:get"></a>
+<h3>io:get</h3>
+
+<p>The <em>io:get</em> Step connects to a specified URL, retrieves the
+corresponding value as a String, and pushes the result on to the evaluation
+stack.</p>
+
+<p>The <em>io:get</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+<li><strong>url</strong> - URL of the resource to be retrieved.</li>
+</ul>
+
+<p>In the following example, the home page of a local web server is
+retrieved and pushed on to the evaluation stack as a String:</p>
+<pre>
+ <strong><io:get url="http://localhost:8080/index.html"/></strong>
+</pre>
+
+
+<a name="io:peek"></a>
+<h3>io:peek</h3>
+
+<p>The <em>io:peek</em> Step makes a copy of the top item on the
+evaluation stack, converts it to a String (if necesary), and prints it to
+standard output. This is useful for debugging, and is shorthand for
+the following:</p>
+<pre>
+ <core:duplicate/>
+ <io:display>
+ <io:descriptor/>
+ </io:display>
+</pre>
+
+<p>The <em>io:peek</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+
+<a name="io:read"></a>
+<h3>io:read</h3>
+
+<p>The <em>io:read</em> Step reads the characters of the specified file,
+converts them to a String, and pushes this String on to the evaluation stack.
+</p>
+
+<p>The <em>io:read</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>encoding</strong> - Character encoding to use when reading
+ this file. If not specified, the platform default encoding will be used.</li>
+<li><strong>file</strong> - Relative or absolute pathname of the file to
+ be read by this Step.</li>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+<p>In the example below, the contents of the specified file are read,
+converted to a String, and pushed on to the evaluation stack:</p>
+<pre>
+ <strong><io:read file="data.txt"/></strong>
+</pre>
+
+
+<a name="io:write"></a>
+<h3>io:write</h3>
+
+<p>The <em>io:write</em> Step pops the top item from the evaluation
+stack, converts it to a String (if necessary), and writes the characters
+to the specified file.</p>
+
+<p>The <em>io:write</em> element recognizes the following attributes:</p>
+<ul>
+<li><strong>encoding</strong> - Character encoding to use when writing
+ this file. If not specified, the platform default encoding will be used.</li>
+<li><strong>file</strong> - Relative or absolute pathname of the file to
+ be written by this Step.</li>
+<li><strong>id</strong> - Optional identifier of this Step, which can be used
+ as the destination for control transfers. If specified, must be unique
+ within the current Activity.</li>
+</ul>
+
+<p>In the example below, the contents of the specified file are written
+based on the contents of the popped evaluation stack element:</p>
+<pre>
+ <strong><io:write file="data.txt"/></strong>
+</pre>
+
+
+<div align="center">
+<h2>I/O Step Library - Nested Elements</h2>
+</div>
+
+<a name="io:descriptor"></a>
+<h3>io:descriptor</h3>
+
+<p>An <em>io:descriptor</em> element is a description of the mechanism
+by which an arbitrary Java object (typically a JavaBean) in some Scope, is
+referenced. This element recognizes the following attributes:</p>
<ul>
-<li><strong>XxxxxStep</strong> - Implementations of <code>Step</code>
- for tasks that involve input from and output to external files
- and resources. These <code>Steps</code> rely only on the standard
- APIs of JDK 1.2 (or later) or JRE 1.2 (or later).</li>
+<li><strong>name</strong> - The name under which this bean is stored,
+ optionally located in the Scope specified by the <code>scope</code>
+ attribute.</li>
+<li><strong>scope</strong> - The name of the Scope within which to
+ search for the bean named by the <code>name</code> attribute. If
+ not specified, the corresponding bean will be searched for in all Scopes,
+ in ascending numeric order.</li>
+<li><strong>type</strong> - Fully qualified Java class name that is expected
+ (or set) via this descriptor. If not specified, the actual Java class of the
+ corresponding bean will be used. This is useful, for example, when
+ specifying the arguments to a <a href="#io:invoke">io:invoke</a>
+ Step, and the invoked method expects a Java interface that is implemented
+ by the actual object being passed as a parameter.</li>
+<li><strong>xpath</strong> - An alternative method (to the <code>name</code>
+ and <code>scope</code> attributes) for specifying the bean instance to be
+ accessed by this descriptor.</li>
</ul>
+
+<p>The syntax for XPath expressions is a sequence of one or more
+identifier strings, separated by forward slash ("/") characters. The expression
+is evaluated as follows:</p>
+<ul>
+<li>If no slashes are present, the expression is assumed to be the name
+ of an object that is stored in the "local" scope.</li>
+<li>If one slash is present, the value before the slash is assumed to be the
+ name of the scope in which to locate the bean, while the value after the
+ slash is the name under which the bean is stored in that scope. For
+ example, the WebContext implementation of Context (commonly used
+ when implementing Workflow in a servlet based environment), the scope
+ names "request", "session", and "application" correspond to the
+ request attributes, session attributes, and servlet context attributes
+ provided by the underlying servlet container.</li>
+<li>If more than one slash is present, the value before the first slash
+ is interpreted as a scope name, as above. The remainder of the
+ expression accessed nested properties of beans, according to the
+ syntax specified by the Commons JXPath package.</li>
+</ul>
+
+<p>When deciding what bean a particular descriptor applies to, the following
+rules are applied, in this priority order:</p>
+<ul>
+<li>If the <em>xpath</em> attribute is set, it is used as an
+ XPath expression identifying the requested object.</li>
+<li>If the <em>name</em> (and optional <em>scope</em>) attributes are
+ specified, they are used to select a particular named bean,
+ optionally found in a particular named scope.</li>
+<li>If none of the conditions above are satisfied, the top object on the
+ evaluation stack of our current <code>Context</code> is popped off the
+ stack and consumed.</li>
+</ul>
+
+<p><strong>FIXME</strong> - Support the <code>property</code> attribute
+for access to bean properties via the Commons Beanutils package.</p>
-<p>By convention, the <code>Steps</code> in this package are exposed as part
-of the <code>io</code> namespace in configuration files.</p>
</body>
1.2 +10 -10 jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ContextSupport.java
Index: ContextSupport.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ContextSupport.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ContextSupport.java 2001/08/18 21:06:50 1.1
+++ ContextSupport.java 2001/11/25 06:20:59 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ContextSupport.java,v 1.1 2001/08/18 21:06:50 craigmcc Exp $
- * $Revision: 1.1 $
- * $Date: 2001/08/18 21:06:50 $
+ * $Header: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ContextSupport.java,v 1.2 2001/11/25 06:20:59 craigmcc Exp $
+ * $Revision: 1.2 $
+ * $Date: 2001/11/25 06:20:59 $
*
* ====================================================================
- *
+ *
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -15,7 +15,7 @@
* are met:
*
* 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
+ * notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
@@ -23,15 +23,15 @@
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowlegement:
- * "This product includes software developed by the
+ * any, must include the following acknowlegement:
+ * "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
- * from this software without prior written permission. For written
+ * from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
@@ -57,7 +57,7 @@
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
- */
+ */
package org.apache.commons.workflow.util;
@@ -75,7 +75,7 @@
* firing of <code>ContextEvents</code> to registered
* <code>ContextListeners</code>.
*
- * @revision $Revision: 1.1 $ $Date: 2001/08/18 21:06:50 $
+ * @version $Revision: 1.2 $ $Date: 2001/11/25 06:20:59 $
* @author Craig R. McClanahan
*/
1.2 +11 -11 jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/MapEntry.java
Index: MapEntry.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/MapEntry.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- MapEntry.java 2001/08/13 21:17:40 1.1
+++ MapEntry.java 2001/11/25 06:20:59 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/MapEntry.java,v 1.1 2001/08/13 21:17:40 craigmcc Exp $
- * $Revision: 1.1 $
- * $Date: 2001/08/13 21:17:40 $
+ * $Header: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/MapEntry.java,v 1.2 2001/11/25 06:20:59 craigmcc Exp $
+ * $Revision: 1.2 $
+ * $Date: 2001/11/25 06:20:59 $
*
* ====================================================================
- *
+ *
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -15,7 +15,7 @@
* are met:
*
* 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
+ * notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
@@ -23,15 +23,15 @@
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowlegement:
- * "This product includes software developed by the
+ * any, must include the following acknowlegement:
+ * "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
- * from this software without prior written permission. For written
+ * from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
@@ -57,7 +57,7 @@
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
- */
+ */
package org.apache.commons.workflow.util;
@@ -70,7 +70,7 @@
* interface for use in returning results from <code>entrySet()</code>
* methods on <code>Map</code> implementations.
*
- * @revision $Revision: 1.1 $ $Date: 2001/08/13 21:17:40 $
+ * @version $Revision: 1.2 $ $Date: 2001/11/25 06:20:59 $
* @author Craig R. McClanahan
*/
1.2 +11 -11 jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ScopeSupport.java
Index: ScopeSupport.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ScopeSupport.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ScopeSupport.java 2001/08/13 21:17:40 1.1
+++ ScopeSupport.java 2001/11/25 06:20:59 1.2
@@ -1,13 +1,13 @@
/*
- * $Header: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ScopeSupport.java,v 1.1 2001/08/13 21:17:40 craigmcc Exp $
- * $Revision: 1.1 $
- * $Date: 2001/08/13 21:17:40 $
+ * $Header: /home/cvs/jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util/ScopeSupport.java,v 1.2 2001/11/25 06:20:59 craigmcc Exp $
+ * $Revision: 1.2 $
+ * $Date: 2001/11/25 06:20:59 $
*
* ====================================================================
- *
+ *
* The Apache Software License, Version 1.1
*
- * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
+ * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -15,7 +15,7 @@
* are met:
*
* 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
+ * notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
@@ -23,15 +23,15 @@
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowlegement:
- * "This product includes software developed by the
+ * any, must include the following acknowlegement:
+ * "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
- * from this software without prior written permission. For written
+ * from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
@@ -57,7 +57,7 @@
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
- */
+ */
package org.apache.commons.workflow.util;
@@ -73,7 +73,7 @@
* firing of <code>ScopeEvents</code> to registered
* <code>ScopeListeners</code>.
*
- * @revision $Revision: 1.1 $ $Date: 2001/08/13 21:17:40 $
+ * @version $Revision: 1.2 $ $Date: 2001/11/25 06:20:59 $
* @author Craig R. McClanahan
*/
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>