You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2008/07/09 14:19:38 UTC
svn commit: r675142 [2/2] - in /myfaces/orchestra/trunk/flow: ./ src/
src/main/ src/main/java/ src/main/java/org/ src/main/java/org/apache/
src/main/java/org/apache/myfaces/ src/main/java/org/apache/myfaces/orchestra/
src/main/java/org/apache/myfaces/o...
Added: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamAccept.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamAccept.java?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamAccept.java (added)
+++ myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamAccept.java Wed Jul 9 05:19:37 2008
@@ -0,0 +1,114 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.orchestra.flow.config;
+
+import org.apache.myfaces.orchestra.lib.OrchestraException;
+
+/**
+ * Defines how a parameter value provided by a flow caller is imported
+ * into the called flow's environment.
+ */
+public class FlowParamAccept
+{
+ String name;
+ String dst;
+ String dflt;
+
+ /** Constructor. */
+ public FlowParamAccept()
+ {
+ }
+
+ /**
+ * Check that all the properties of this object have valid values, ie
+ * whether the configuration specified by the user is valid.
+ */
+ public void validate()
+ {
+ if (name == null)
+ {
+ throw new OrchestraException("name is null");
+ }
+
+ if (dst == null)
+ {
+ throw new OrchestraException("dst is null");
+ }
+
+ // dflt is optional
+ }
+
+ /**
+ * Define the name of this parameter.
+ * <p>
+ * The caller is expected to define a parameter with a matching name;
+ * it is an error for the caller to not provide a matching value -
+ * unless this object has a non-null dflt property.
+ * <p>
+ * Null is never returned.
+ */
+ public String getName()
+ {
+ return name;
+ }
+
+ /** For use only during object initialization. */
+ public void setName(String name)
+ {
+ this.name = name;
+ }
+
+ /**
+ * An EL expression which defines where the actual value passed by the caller
+ * should be stored within the called flow's environment.
+ * <p>
+ * Null is never returned.
+ */
+ public String getDst()
+ {
+ return dst;
+ }
+
+ /** For use only during object initialization. */
+ public void setDst(String expr)
+ {
+ this.dst = expr;
+ }
+
+ /**
+ * An EL expression which defines a default value to use when the caller
+ * does not specify a value for this input parameter.
+ * <p>
+ * Optional; if this is not defined then an error is reported if a
+ * caller does not provide an actual value for this named parameter.
+ * <p>
+ * Note that this EL expression is evaluated within the environment of the
+ * called flow, not the caller.
+ */
+ public String getDflt()
+ {
+ return dflt;
+ }
+
+ /** For use only during object initialization. */
+ public void setDflt(String dflt)
+ {
+ this.dflt = dflt;
+ }
+}
Propchange: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamAccept.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamSend.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamSend.java?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamSend.java (added)
+++ myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamSend.java Wed Jul 9 05:19:37 2008
@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.orchestra.flow.config;
+
+import org.apache.myfaces.orchestra.lib.OrchestraException;
+
+/**
+ * Defines an "exported" parameter, from the point of view of the
+ * flow caller.
+ */
+public class FlowParamSend
+{
+ String name;
+ String src;
+
+ /** Constructor. */
+ public FlowParamSend()
+ {
+ }
+
+ /**
+ * Check that all the properties of this object have valid values, ie
+ * whether the configuration specified by the user is valid.
+ */
+ public void validate()
+ {
+ if (name == null)
+ {
+ throw new OrchestraException("name is null");
+ }
+
+ if (src == null)
+ {
+ throw new OrchestraException("src is null");
+ }
+ }
+
+ /**
+ * Define the name of this parameter.
+ * <p>
+ * The called flow is expected to define a parameter with a matching name;
+ * <p>
+ * Null is never returned.
+ */
+ public String getName()
+ {
+ return name;
+ }
+
+ /** For use only during object initialization. */
+ public void setName(String name)
+ {
+ this.name = name;
+ }
+
+ /**
+ * An EL expression which defines where the actual value passed by the caller
+ * should be fetched from when the call occurs.
+ * <p>
+ * Null is never returned.
+ */
+ public String getSrc()
+ {
+ return src;
+ }
+
+ /** For use only during object initialization. */
+ public void setSrc(String expr)
+ {
+ this.src = expr;
+ }
+}
Propchange: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowParamSend.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnAccept.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnAccept.java?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnAccept.java (added)
+++ myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnAccept.java Wed Jul 9 05:19:37 2008
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.orchestra.flow.config;
+
+import org.apache.myfaces.orchestra.lib.OrchestraException;
+
+/**
+ * Defines how a return value from a flow is imported into the caller's environment.
+ */
+public class FlowReturnAccept
+{
+ String name;
+ String dst;
+
+ /** Constructor. */
+ public FlowReturnAccept()
+ {
+ }
+
+ /**
+ * Check that all the properties of this object have valid values, ie
+ * whether the configuration specified by the user is valid.
+ */
+ public void validate()
+ {
+ if (name == null)
+ {
+ throw new OrchestraException("name is null");
+ }
+
+ if (dst == null)
+ {
+ throw new OrchestraException("dst is null");
+ }
+ }
+
+ /**
+ * Define the name of this parameter.
+ * <p>
+ * The called flow is expected to define a return parameter with a matching name.
+ * <p>
+ * Null is never returned.
+ */
+ public String getName()
+ {
+ return name;
+ }
+
+ /** For use only during object initialization. */
+ public void setName(String name)
+ {
+ this.name = name;
+ }
+
+ /**
+ * An EL expression which defines where the actual value passed back from the called
+ * flow should be stored within the caller's environment.
+ * <p>
+ * Null is never returned.
+ */
+ public String getDst()
+ {
+ return dst;
+ }
+
+ /** For use only during object initialization. */
+ public void setDst(String expr)
+ {
+ this.dst = expr;
+ }
+}
Propchange: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnAccept.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnSend.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnSend.java?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnSend.java (added)
+++ myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnSend.java Wed Jul 9 05:19:37 2008
@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.orchestra.flow.config;
+
+import org.apache.myfaces.orchestra.lib.OrchestraException;
+
+/**
+ * Defines an "exported" return value, from the point of view of the
+ * called flow.
+ */
+public class FlowReturnSend
+{
+ String name;
+ String src;
+
+ /** Constructor. */
+ public FlowReturnSend()
+ {
+ }
+
+ /**
+ * Check that all the properties of this object have valid values, ie
+ * whether the configuration specified by the user is valid.
+ */
+ public void validate()
+ {
+ if (name == null)
+ {
+ throw new OrchestraException("name is null");
+ }
+
+ if (src == null)
+ {
+ throw new OrchestraException("src is null");
+ }
+ }
+
+ /**
+ * Define the name of this parameter.
+ * <p>
+ * The caller is expected to define a return parameter with a matching name.
+ * <p>
+ * Null is never returned.
+ */
+ public String getName()
+ {
+ return name;
+ }
+
+ /** For use only during object initialization. */
+ public void setName(String name)
+ {
+ this.name = name;
+ }
+
+ /**
+ * An EL expression which defines where the actual value begin returned to the
+ * caller should be fetched from when the call occurs.
+ * <p>
+ * Null is never returned.
+ */
+ public String getSrc()
+ {
+ return src;
+ }
+
+ /** For use only during object initialization. */
+ public void setSrc(String expr)
+ {
+ this.src = expr;
+ }
+}
Propchange: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/config/FlowReturnSend.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/digest/FlowDigester.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/digest/FlowDigester.java?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/digest/FlowDigester.java (added)
+++ myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/digest/FlowDigester.java Wed Jul 9 05:19:37 2008
@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.orchestra.flow.digest;
+
+import java.io.IOException;
+
+import org.apache.commons.digester.Digester;
+import org.apache.myfaces.orchestra.flow.config.FlowAccept;
+import org.apache.myfaces.orchestra.flow.config.FlowCall;
+import org.apache.myfaces.orchestra.flow.config.FlowConfig;
+import org.apache.myfaces.orchestra.flow.config.FlowParamAccept;
+import org.apache.myfaces.orchestra.flow.config.FlowParamSend;
+import org.apache.myfaces.orchestra.flow.config.FlowReturnAccept;
+import org.apache.myfaces.orchestra.flow.config.FlowReturnSend;
+import org.apache.myfaces.orchestra.lib.OrchestraException;
+import org.xml.sax.InputSource;
+import org.xml.sax.SAXException;
+
+
+/**
+ * A class to parse a "flow.xml" file and return a FlowConfig object.
+ */
+public class FlowDigester
+{
+ /**
+ * Parse data from the specified InputSource object.
+ * <p>
+ * The source's input stream should have an open input stream, and the
+ * systemId should be set to an appropriate value for showing in error
+ * messages.
+ * <p>
+ * The input stream should be an xml file with a "flowConfig" element
+ * as the root node.
+ */
+ public static FlowConfig digest(InputSource source)
+ {
+ Digester d = new Digester();
+
+ d.addObjectCreate("flowConfig", FlowConfig.class);
+
+ d.addObjectCreate("flowConfig/flowCall", FlowCall.class);
+ d.addSetProperties("flowConfig/flowCall");
+ d.addSetNext("flowConfig/flowCall", "addFlowCall");
+
+ d.addObjectCreate("flowConfig/flowCall/param", FlowParamSend.class);
+ d.addSetProperties("flowConfig/flowCall/param");
+ d.addSetNext("flowConfig/flowCall/param", "addParam");
+
+ d.addObjectCreate("flowConfig/flowCall/return", FlowReturnAccept.class);
+ d.addSetProperties("flowConfig/flowCall/return");
+ d.addSetNext("flowConfig/flowCall/return", "addReturn");
+
+ d.addObjectCreate("flowConfig/flowAccept", FlowAccept.class);
+ d.addSetProperties("flowConfig/flowAccept");
+ d.addSetNext("flowConfig/flowAccept", "setFlowAccept");
+
+ d.addObjectCreate("flowConfig/flowAccept/param", FlowParamAccept.class);
+ d.addSetProperties("flowConfig/flowAccept/param");
+ d.addSetNext("flowConfig/flowAccept/param", "addParam");
+
+ d.addObjectCreate("flowConfig/flowAccept/return", FlowReturnSend.class);
+ d.addSetProperties("flowConfig/flowAccept/return");
+ d.addSetNext("flowConfig/flowAccept/return", "addReturn");
+
+ d.addCallMethod("flowConfig/flowAccept/commitWhen", "setCommitWhen", 0);
+ d.addCallMethod("flowConfig/flowAccept/cancelWhen", "setCancelWhen", 0);
+ d.addCallMethod("flowConfig/flowAccept/restartWhen", "setRestartWhen", 0);
+
+ try
+ {
+ d.parse(source);
+ }
+ catch(IOException e)
+ {
+ throw new OrchestraException("Cannot parse flow config file " + source.getSystemId(), e);
+ }
+ catch(SAXException e)
+ {
+ throw new OrchestraException("Cannot parse flow config file " + source.getSystemId(), e);
+ }
+
+ FlowConfig flowConfig = (FlowConfig) d.getRoot();
+ flowConfig.validate();
+ return flowConfig;
+ }
+}
Propchange: myfaces/orchestra/trunk/flow/src/main/java/org/apache/myfaces/orchestra/flow/digest/FlowDigester.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/main/resources/META-INF/faces-config.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/main/resources/META-INF/faces-config.xml?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/main/resources/META-INF/faces-config.xml (added)
+++ myfaces/orchestra/trunk/flow/src/main/resources/META-INF/faces-config.xml Wed Jul 9 05:19:37 2008
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<!DOCTYPE faces-config PUBLIC
+ "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
+ "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
+
+<!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+-->
+
+<faces-config>
+ <application>
+ <view-handler>org.apache.myfaces.orchestra.flow.FlowViewHandler</view-handler>
+ <navigation-handler>org.apache.myfaces.orchestra.flow.FlowNavigationHandler</navigation-handler>
+ </application>
+</faces-config>
Propchange: myfaces/orchestra/trunk/flow/src/main/resources/META-INF/faces-config.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/site/apt/faqs.apt
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/site/apt/faqs.apt?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/site/apt/faqs.apt (added)
+++ myfaces/orchestra/trunk/flow/src/site/apt/faqs.apt Wed Jul 9 05:19:37 2008
@@ -0,0 +1,53 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ ------
+ Apache MyFaces Orchestra Flow - FAQ
+ ------
+
+Are there alternatives to flow.xml files?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Flow.xml files can be used to declare calling and callable flow configuration.
+
+ In theory, it is also possible to provide this information in other ways. The
+ design documentation for Orchestra Flow already describes a way to do this using
+ tags embedded in pages rather than out-of-line xml files. This isn't currently
+ implemented, but is planned and should not be very difficult.
+
+ Other approaches may also be possible. For example, if you would like to define
+ the flow caller and callable configuration in a database indexed by viewId, then
+ there is no obvious reason why this could not be done. Please contact the development
+ list if you are interested in developing a new approach.
+
+Can flow calls be checked at startup?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Theoretically when using flow.xml files to declare flow calls, it should be
+ possible to scan a webapp on startup and determine whether all flow calls are
+ valid, ie whether for each flowCall there exists somewhere a valid flowAccept
+ that has the right type and parameters. This has not yet been implemented, but
+ patches are very welcome.
+
+ If flow calls are defined via tags in facelets files, then it might also be
+ possible to scan the xhtml files and extract this information (although facelets
+ templating might make this complex).
+
+ For flow calls defined via tags embedded in jsp files this is probably too
+ complicated; a complete jsp parser would be needed to extract the information.
+
+
Propchange: myfaces/orchestra/trunk/flow/src/site/apt/faqs.apt
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/site/apt/index.apt?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/site/apt/index.apt (added)
+++ myfaces/orchestra/trunk/flow/src/site/apt/index.apt Wed Jul 9 05:19:37 2008
@@ -0,0 +1,58 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ ------
+ Apache MyFaces Orchestra Flow
+ ------
+
+Status
+~~~~~~
+
+ This library is currently in SANDBOX status only.
+
+ This means that it is not yet an approved Apache MyFaces project. If not approved, then
+ the code may be moved to a "failed projects" location and no longer maintained. APIs
+ may also change at any time without notice. Using this code in a production system is
+ therefore risky and not advised unless you are willing and capable to maintain your
+ own version of this code if the project does not continue.
+
+ However we (the flow developers) obviously believe that there is a fairly good chance
+ that this project will be approved. You are invited to join in, and help that happen!
+
+Flow Overview
+~~~~~~~~~~~~~
+
+ The Apache MyFaces Orchestra Flow module provides the ability to "call" a sequence of
+ pages (called a "flow"). The called flow can "return" to the caller without complicated
+ navigation rules. The called pages also have an entirely separate variable namespace,
+ so that they cannot accidentally overwrite any other data, and so that all objects
+ created during the flow are automatically discarded when the flow returns.
+
+ Data is passed in to a flow from the caller in a manner similar to a java method call,
+ and data can be returned from the flow to the caller in an equally convenient manner
+
+ This functionality is similar to Spring WebFlow, or Trinidad PageFlow.
+
+ As with other Orchestra functionality, this is built <on> the principles of
+ JSF rather than reinventing it, and tries to be as unintrusive as possible. Normal
+ JSF navigation rules are used for inter-page navigation for example, and flows can
+ be used with zero modification to JSF pages or backing beans. Orchestra Flow functionality
+ can be incrementally added to existing JSF applications where needed, while leaving the
+ rest of the application unchanged.
+
+ Orchestra Flow requires the Orchestra Core library. It is compatible with JSF1.1
+ and later, and requires only java 1.4.
Propchange: myfaces/orchestra/trunk/flow/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/site/apt/usage.apt
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/site/apt/usage.apt?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/site/apt/usage.apt (added)
+++ myfaces/orchestra/trunk/flow/src/site/apt/usage.apt Wed Jul 9 05:19:37 2008
@@ -0,0 +1,239 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ ------
+ Apache MyFaces Orchestra Flow - Usage
+ ------
+
+Installation
+~~~~~~~~~~~~
+
+ To install, just put the orchestra flow jar in your classpath. The necessary
+ custom ViewHandler and NavigationHandler objects will be installed automatically.
+
+
+Design Philosophy
+~~~~~~~~~~~~~~~~~
+
+ The process of "calling" a flow from some page has been made as much like a java
+ method call as possible. Actually, the approach is like looking up an abstract
+ service interface, then invoking that interface, rather like this bit of java code:
+
+---------
+
+ MyAbstractService service = (MyAbstractService) serviceLocator.find(serviceName);
+ Results results = service.run(arg1, arg2, arg3);
+
+---------
+
+ The analogy between this code and what Orchestra Flows provides isn't 100% exact, but
+ it's a good starting point for understanding how things work.
+
+ As with the above, an abstract service name maps to the actual implementation. In
+ a flow, the serviceName is a navigation outcome, and the concrete implementation is
+ whatever viewId the JSF navigation rules map that outcome to.
+
+ The discovered Java service object is expected to implement a particular interface,
+ and it is a runtime error (ClassCastException) if it does not. Similarly, the caller
+ of a flow declares what "service" it expects the flow to provide. If the nagivation rules
+ map to a viewId that is not a callable flow, or has a "service" value that does not
+ match then that is also a runtime error (OrchestraException). Note that unlike a
+ java service interface, a flow can provides only one "method" to call.
+
+ A java service interface declares a fixed set of parameters that can be passed to it.
+ Similarly, a callable flow "declares" what parameters it accepts. It is a runtime
+ exception if a call is made to a flow but an incorrect number of parameters are
+ passed. Actually, for flows parameters are matched by name rather than just index
+ (as some programming languages support, but not java). So order of parameters is
+ not important, but for each param declared by the called flow the caller must provide
+ a value. NB: it is theoretically possible for mismatched param errors to be reported
+ at startup rather than runtime (ie make it a "compile time" error like java), but this
+ is not yet implemented.
+
+ Note, however, that the way in which the values to pass as input parameters is rather
+ unlike java. Each parameter is specified as an EL expression that simply pulls a value
+ from the current environment at the time the call is made.
+
+ A flow also returns values. Unlike java, a flow can return multiple values. And also
+ unlike java, return values are specified as EL expressions that state where each return
+ value should be stored.
+
+Defining a Callable Flow
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+ All pages related to a flow need to be placed in their own directory (ie no pages that
+ are not part of the flow should be in the same directory). Subdirectories are permitted,
+ so that large and complicated flows can still be properly structured.
+
+ One page of the flow must be designated as the "entry page". Create an xml file
+ whose name is the same as the entry page, but replace the page suffix with "-flow.xml".
+ For example, if the entry page is "searchCustomer.jsp" then create a file named
+ "searchCustomer-flow.xml". Or for entry page "selectDestination.xhtml", create file
+ "selectDestination-flow.xml".
+
+ The flow.xml file must contain a flowAccept section that defines:
+
+ * What logical service this flow provides
+
+ * What parameters the caller is required to pass to this flow, and where those
+ parameters get stored when the flow starts (ie which properties of which backing
+ beans they should be assigned to).
+
+ * What parameters the flow will pass back to the caller when the flow is committed
+ (ends successfully), and where that data can be found.
+
+ * What navigation outcome will trigger a return back to the calling page.
+
+ Here is an example of a flow.xml file containing a flowAccept section:
+
+--------------
+
+<flowConfig>
+ <!--
+ - This service prompts the user to define either a postal or pobox address,
+ - and returns an Address object.
+ -->
+ <flowAccept service="com.acme.services.CreateAddress">
+ <param name="type" dst="#{addressCreator.addressType}"/>
+ <return name="address" src="#{addressCreator.address}"/>
+
+ <commitWhen outcome="commit"/>
+ <cancelWhen outcome="cancel"/>
+ </flowAccept>
+</flowConfig>
+
+--------------
+
+ As for any java service, good documentation is important; the flowConfig clause is
+ a good place to document what the flow does and what the parameters mean.
+
+ The "service" property is similar to a java interface name, and states what logical
+ operation the flow performs. This is a free-format string, but it is recommended that
+ it contain something that resembles a fully-qualified java class name. Its main purpose
+ is to ensure that the caller has correctly found the right kind of called flow, and to
+ report a clear error immediately when things go wrong, rather than getting some weird
+ behaviour later. It is also excellent documenation.
+
+ One or more input parameters are required. The name attribute must match the name
+ specified for a parameter passed by the caller. The dst attribute is an EL expression
+ that states where the input parameter passed by the caller should be stored when
+ the flow starts.
+
+ One or more return parameters are required. The name attribute must match the name
+ specified for a return parameter of the caller. The src attribute is an EL expression
+ that states where the return value should be fetched from when the flow returns with
+ a "commit" operation.
+
+ The commitWhen element specifies what navigation outcome should cause the flow to
+ perform a "commit". When "committed", a flow copies all its return parameters back
+ to the caller, discards all flow-related objects then navigates back to the calling
+ page. The outcome value here applies only while the flow is active. This element
+ is optional; the string "commit" is the default value so this element is needed
+ only if a value other than the default is desired.
+
+ The cancelWhen element specifies what navigation outcome should cause the flow to
+ perform a "cancel". When "cancelled", a flow discards all flow-related objects then
+ navigate back to the calling page. No return values are pushed to the caller.
+ This element is optional; the string "commit" is the default value so this element
+ is needed only if a value other than the default is desired.
+
+ Note that for both commitWhen and cancelWhen, there does not need to be any JSF
+ navigation case defined for the outcome; the "to-view-id" is always the viewId of
+ the calling flow and any navigation case defined will be ignored.
+
+Defining a Flow Caller
+~~~~~~~~~~~~~~~~~~~~~~
+
+ Where a page should trigger a call to a flow, create an xml file whose name is the
+ same as the page file, but replace the page suffix with "-flow.xml". For example,
+ if page "manageUser.jsp" should call the "createAddress" flow, then create a file
+ named "manageUser-flow.xml".
+
+ The flow.xml file must contain a flowCall section that defines:
+
+ * what navigation outcome triggers the call
+
+ * What logical service the called flow is expected to provide
+
+ * What parameters the caller is passing to the flow, and where that data can
+ be found.
+
+ * What return values are expected from the flow, and where that data should be
+ stored after the flow returns it.
+
+ Here is an example of a flow.xml file containing a flowCall section:
+
+--------------
+
+<flowConfig>
+ <flowCall outcome="newAddress" service="com.acme.services.CreateAddress">
+ <param name="type" src="#{userManager.addressType}"/>
+ <return name="address" dst="#{user.address}"/>
+ </flowCall>
+</flowConfig>
+
+--------------
+
+ The "outcome" property defines what navigation outcome from the associated page
+ triggers a call to the flow. The matching JSF navigation rule must of course
+ point to a viewId which has a flow.xml file with a corresponding flowAccept clause.
+ Defining a navigation rule that goes to the entry point of a flow without having
+ a corresponding flowCall clause causes an error to be reported; the target flow
+ cannot sensibly run without any input parameters or anywhere to put its return
+ values!
+
+ The "service" property defines what is expected of the called flow. If the called flow
+ does not declare exactly the same service type, then an error is reported.
+
+ One or more input parameters are required. The name attribute must match the name
+ specified for a parameter expected by the called flow. The src attribute is an EL
+ expression that states where the value to pass can be found.
+
+ One or more return parameters are required. The name attribute must match the name
+ specified for a return parameter of the called flow. The dst attribute is an EL
+ expression that states where the named value returned by the flow should be stored.
+
+ Note that a page can trigger calls to as many different flows as it wants; multiple
+ flowCall entries can exist in a single flow.xml file. This is unlike flowAccept, where
+ a maximum of one entry is valid.
+
+Making Flow Calls From Within Flows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Pages within flows can call other flows if they wish. The calls nest just as would
+ be expected. Note that when the entry page for a flow itself can call other flows,
+ then the flow.xml file will have both flowAccept and flowCall clauses in it.
+
+ Occasionally, a flow will want to call itself. One example might be "display user details",
+ where a user might have links to other users. This is simply done by adding a flowCall
+ element to the flow.xml file just like a normal call to a flow. No special handling is
+ required.
+
+Cancelling Flows
+~~~~~~~~~~~~~~~~
+
+ When a page that is part of a flow returns a navigation outcome that matches the
+ cancelWhen setting for the called flow ("cancel" by default) then the flow discards
+ all data and navigates back to the calling page.
+
+ However it is also possible for pages to contain links that lead outside the current
+ flow (eg navigation menus at the top of a page) or for a user to simply enter a new
+ url directly into their browser. Orchestra Flow automatically detect when this happens,
+ and simply discards the current flow. This avoids any memory leaks for data associated
+ with a flow.
+
+
\ No newline at end of file
Propchange: myfaces/orchestra/trunk/flow/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/site/site.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/site/site.xml?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/site/site.xml (added)
+++ myfaces/orchestra/trunk/flow/src/site/site.xml Wed Jul 9 05:19:37 2008
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+<project name="MyFaces Orchestra Flow">
+ <bannerLeft>
+ <name>MyFaces Orchestra</name>
+ <src>img/banners/MyFaces_logo.jpg</src>
+ <href>http://myfaces.apache.org/</href>
+ </bannerLeft>
+
+ <bannerRight>
+ <name>Apache Banner</name>
+ <src>img/banners/apache_banner.png</src>
+ <href>http://myfaces.apache.org/</href>
+ </bannerRight>
+
+ <publishDate format="dd MMM yyyy" />
+
+ <skin>
+ <groupId>org.apache.myfaces.maven</groupId>
+ <artifactId>myfaces-site-skin</artifactId>
+ <version>1-SNAPSHOT</version>
+ </skin>
+
+ <body>
+ <menu name="Flow Documentation">
+ <item name="Welcome" href="index.html"/>
+ <item name="Usage" href="usage.html"/>
+ <item name="FAQs" href="faqs.html"/>
+ </menu>
+
+ <menu ref="reports"/>
+
+ </body>
+</project>
Propchange: myfaces/orchestra/trunk/flow/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: myfaces/orchestra/trunk/flow/src/test/resources/log4j.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/flow/src/test/resources/log4j.xml?rev=675142&view=auto
==============================================================================
--- myfaces/orchestra/trunk/flow/src/test/resources/log4j.xml (added)
+++ myfaces/orchestra/trunk/flow/src/test/resources/log4j.xml Wed Jul 9 05:19:37 2008
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+ <appender name="console" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.Err"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <!--
+ d date
+ p prioirty
+ X MDC Value
+ t threadname
+ c category-name
+ m message
+ -->
+ <param name="ConversionPattern" value="%-5p [%t] %c - %m\n"/>
+ </layout>
+ </appender>
+
+ <category name="org.apache.commons.beanutils">
+ <priority value="info"/>
+ </category>
+ <category name="org.apache.commons.digester">
+ <priority value="info"/>
+ </category>
+
+ <root>
+ <priority value="debug"/>
+
+ <appender-ref ref="console"/>
+ </root>
+
+</log4j:configuration>
Propchange: myfaces/orchestra/trunk/flow/src/test/resources/log4j.xml
------------------------------------------------------------------------------
svn:eol-style = native