commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-commons-sandbox/workflow/src/java/org/apache/commons/workflow/util ContextSupport.java MapEntry.java ScopeSupport.java
Date Sun, 25 Nov 2001 06:20:59 GMT
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>
     &lt;base:activity id="Demonstration Activity"
  -    xmlns:base="http://jakarta.apache.org/commons/workflow/base"
       xmlns:core="http://jakarta.apache.org/commons/workflow/core"
     &gt;
   
  @@ -67,9 +66,10 @@
   <code>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt; elements are always evaluated.</p>
  +the nested <code>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt;</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>&lt;core:get&gt;</strong>
  +    &lt;core:descriptor xpath="address/street1"/&gt;
  +    &lt;core:descriptor xpath="address/city"/&gt;
  +    &lt;core:descriptor xpath="address/state"/&gt;
  +    &lt;core:descriptor xpath="address/zipCode"/&gt;
  +  <strong>&lt;/core:get&gt;</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>
  +  &lt;core:string value="Home"/&gt;
  +  <strong>&lt;core:invoke method="addAddress"&gt;</strong>
  +    &lt;core:bean xpath="customer"/&gt;
  +    &lt;core:descriptor/&gt;    &lt;-- The String we just pushed --&gt;
  +    &lt;core:descriptor xpath="address"/&gt;
  +  <strong>&lt;/core:invoke&gt;</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>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt; elements are always evaluated.</p>
  +the nested <code>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt; elements are always evaluated.</p>
  +the nested <code>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt; elements are always evaluated.</p>
  +the nested <code>&lt;core:descriptor&gt;</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>&lt;core:descriptor&gt;</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>&lt;core:put&gt;</strong>
  +    &lt;core:descriptor xpath="address/zipCode"/&gt;
  +    &lt;core:descriptor xpath="address/state"/&gt;
  +    &lt;core:descriptor xpath="address/city"/&gt;
  +    &lt;core:descriptor xpath="address/street1"/&gt;
  +  <strong>&lt;/core:put&gt;</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>&lt;core:remove&gt;</strong>
  +    &lt;core:descriptor xpath="address"/&gt;
  +    &lt;core:descriptor xpath="customer"/&gt;
  +  <strong>&lt;/core:remove&gt;</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>
  +  &lt;base:activity id="Demonstration Activity"
  +    xmlns:core="http://jakarta.apache.org/commons/workflow/core"
  +    xmlns:io="http://jakarta.apache.org/commons/workflow/io"
  +  &gt;
  +
  +    &lt;io:write file="topitem.txt"/&gt;
  +
  +  &lt;/base:activity&gt;
  +</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>&lt;io:descriptor&gt;</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>&lt;io:display &gt;</strong>
  +    &lt;io:descriptor xpath="address"/&gt;
  +    &lt;io:descriptor xpath="customer"/&gt;
  +  <strong>&lt;/io:display&gt;</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>&lt;io:get url="http://localhost:8080/index.html"/&gt;</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>
  +  &lt;core:duplicate/&gt;
  +  &lt;io:display&gt;
  +    &lt;io:descriptor/&gt;
  +  &lt;/io:display&gt;
  +</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>&lt;io:read file="data.txt"/&gt;</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>&lt;io:write file="data.txt"/&gt;</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:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message