Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Message-ID: <FDCEAB9D7DE70246A419ECF68553D10456B81A@POSTMAN.flagship.ru>
From: Konstantin Piroumian <KPiroumian@protek.com>
To: "'Ulrich Mayring'" <ulim@denic.de>
Cc: "'cocoon-dev@xml.apache.org'" <cocoon-dev@xml.apache.org>
Subject: [FLOWMAP] Flow script
Date: Tue, 9 Apr 2002 13:29:40 +0400 
MIME-Version: 1.0
Content-Type: multipart/mixed;
	boundary="----_=_NextPart_000_01C1DFA9.13543F80"

------_=_NextPart_000_01C1DFA9.13543F80
Content-Type: text/plain;
	charset="koi8-r"

Hi, Uli!

Glad to see you back to Cocoon. 

So, here goes our approach to flow control.

1. The approach is quite simple: we have a component (Screen Flow
Controller) that is called through a set of actions from the sitemap.
Possible actions are the following (this is not the complete list): 

	- start a flow
	- process input for the current state
	- cancel flow

and some others that are related to the possibility to run multiple flows
for a single user (get list of flows, set active flow, etc.).

2. Interaction with ScreenFlowController is performed through a simple
interface method:

	handleEvent(Event event): State;

Event object contains the event name (type: START, INPUT, CANCEL, etc.) and
according data, that is gathered from the request (we perform mapping from
request parameters to value objects - JavaBeans).

State object contains current form id (we map it to real file name),
response data (value objects that contain the model data for the current
form) and some other information related to the state (in-process, finished,
etc.). We place value objects into request attributes then use them to
display the form with Struts' taglib (it's possible with Cocoon as well).

3. Typical usage scenario is the following:
	- on Start Flow request a flow controller is created then placed
into the user session
	- start event is sent (called handleEvent(event)) to controller with
script ID (assigned externally: from user request or sitemap/struts-config)
	-  when event handling returned the new state then control is
forwarded to the according handler (e.g.: <map:read src="{form}.jsp" />)

When user submit some data then InputAction is called and performed the
following:
	- current state is refreshed
	- an event is created
	- input parameters are mapped to value objects
	- event is sent to controller
	- new state is returned
	- control is forwarded to the according handler

4. So, as you see it's quite simple in usage. The most complex part is input
data mapping to JavaBeans, but it's now can be easily solved using Ivelin's
approach with Castor (or any other mapping tool). Another advantage of XML
usage in this case is that it will be quite easy to implement a visual tool
for flow editing, especially when direct EJB calls will be supported (this
will allow to reduce the number of custom actions used in the flow script).

5. In the attached customer_reg_new.xml file you'll find my working draft of
Customer Registration flow script. The real script is a little more complex
and differ in some tag names, but I hope you'll get the idea. I've also
attached a sample sitemap to show how it look like in Cocoon.

6. As a side note, I'd add that we had two implementations of
ScreenFlowController: a local class that is placed in session and called
like any other Cocoon components and the other is an EJB (a session bean)
that acts on the EJB container side. It is also planned to implement flow
script includes and forwards.

I am open for critics and comments.

--
Konstantin
_________________________________________
Konstantin Piroumian
Lead Developer
ICQ#: 2297575
* Work Tel#:  +7 095 795 0520 * 1288
* More ways to contact me <http://web.icq.com/wwp?Uin=2297575> 
i See more about me <http://kot-p.hotbox.ru/> 
_________________________________________


------_=_NextPart_000_01C1DFA9.13543F80
Content-Type: application/octet-stream;
	name="customer_reg_new.xml"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
	filename="customer_reg_new.xml"

<?xml version=3D"1.0" encoding=3D"UTF-8"?>=0A=
<!-- =0A=
	REVISIT (KP): We can have a script Id here to be able to identify the =
script externaly. Not sure.=0A=
-->=0A=
<script version=3D"1.0" id=3D"customer.registration">=0A=
	<!--=0A=
		REVISIT (KP): Add a 'note' element to script - can be used in =
proposed =0A=
		script builder.=0A=
	-->=0A=
	<note>=0A=
		This script defines the process of customer account registration=0A=
	</note>=0A=
	<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Variables declarations =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->=0A=
	<variables>=0A=
		<!-- =0A=
		REVISIT (KP):=0A=
		We can have 'usage' attribute with values (input | output | both | =
internal), so =0A=
		illegal usage can be prevented during interpretation. =0A=
		By default it's value can be 'both' - input and output.=0A=
		=0A=
		Add initialization with default values. Can be done for simple =
types:=0A=
		String, Integer, Long, Boolean and maybe Date.		=0A=
		-->=0A=
		<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Internal variables =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->=0A=
		<variable name=3D"customerId" type=3D"java.lang.String" =
usage=3D"internal"/>=0A=
		<variable name=3D"posCode" type=3D"java.lang.String" =
usage=3D"internal">SC</variable>=0A=
		<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Value holders =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->=0A=
		<variable name=3D"customer" =
type=3D"com.protek.bccs.bc.customer.PartyCustomerProfile"/>=0A=
		<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Processing variables =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->=0A=
		<variable name=3D"errors" type=3D"screenflow.helper.ErrorList"/>=0A=
	</variables>=0A=
	<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Operations =
declarations =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->=0A=
	<external-operations>=0A=
		<!-- =0A=
			REVISIT (KP): =0A=
			Remove parameter 'value' attribute from declaration or use it as =
default.=0A=
			Remove 'result' from operation declaration.=0A=
			=0A=
			Parameter values and result should be assigned on usage.=0A=
		-->=0A=
		<!-- No argument operation -->=0A=
		<external-operation id=3D"createCustomer" =
src=3D"com.protek.bccs.screenflow.operations.CreateCustomerEntity"/>=0A=
		<!-- One argument operation -->=0A=
		<external-operation id=3D"validatePersonalInfo" =
src=3D"com.protek.bccs.screenflow.operations.ValidatePersonalInfo">=0A=
			<parameter name=3D"customer" =
type=3D"com.protek.bccs.bc.customer.PartyCustomerProfile"/>=0A=
		</external-operation>=0A=
	</external-operations>=0A=
	<!-- =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Screenflow definition =
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -->=0A=
	<!-- =0A=
		REVISIT (KP): State definition=0A=
			- make 'note' an element.=0A=
			- change element name to 'state'=0A=
			- redesign structure =0A=
			- make 'form' attribute not required=0A=
	-->=0A=
	<start-state id=3D"customer.registration.start">=0A=
		<note>=0A=
			Creation and initialization of customer entity value bean=0A=
		</note>=0A=
		<!--=0A=
			This part must be executed just after the control moved to this =
state=0A=
			<on-enter>=0A=
				{operations | conditions | transitions}=0A=
			</on-enter>=0A=
		-->=0A=
		<on-enter>=0A=
			<exec operation=3D"createCustomer">=0A=
				<!-- Set result to the 'customer' variable -->=0A=
				<result variable=3D"$customer"/>=0A=
			</exec>=0A=
			<!-- Do not send any response to user - just switch to a new state =
-->=0A=
			<goto state=3D"customer.personal.edit"/>=0A=
		</on-enter>=0A=
		<!--=0A=
		<on-event name=3D"event-name1">=0A=
			{operations | conditions | transitions}=0A=
		</on-event>=0A=
			...=0A=
		<on-event name=3D"event-nameN">=0A=
			{operations | conditions | transitions}=0A=
		</on-event>=0A=
		-->=0A=
		<!--=0A=
		REVISIT (KP): This part should be performed just before leaving this =
state.=0A=
		Can we have a transition here?=0A=
		-->=0A=
		<!--=0A=
		<on-exit>=0A=
			{operations | conditions}=0A=
		</on-exit>=0A=
		-->=0A=
	</start-state>=0A=
	<state id=3D"customer.personal.edit" =
form=3D"customer.personal.edit">=0A=
		<note>=0A=
			This state performs customer personal details editing =0A=
		</note>=0A=
		<on-event name=3D"next">=0A=
			<exec operation=3D"validatePersonalInfo">=0A=
				<result variable=3D"$errors"/>=0A=
			</exec>=0A=
			<!-- Removed 'then' element-->=0A=
			<if test=3D"$errors">=0A=
				<!-- REVISIT (KP):=0A=
					A set of internal variables is needed: _self, _parent, _initiator, =
etc. =0A=
				-->=0A=
				<goto state=3D"_self"/>=0A=
				<!-- REVISIT (KP):=0A=
					We should have a possibility to specify when send response to the =
user=0A=
					and with what data in parameters.=0A=
				-->=0A=
			</if>=0A=
			<goto state=3D"customer.registration.save"/>=0A=
		</on-event>=0A=
		<on-event name=3D"cancel">=0A=
			<goto state=3D"customer.registration.final"/>=0A=
		</on-event>=0A=
	</state>=0A=
	<state id=3D"customer.registration.save">=0A=
		<note>=0A=
			Save customer registration info=0A=
		</note>=0A=
		<on-enter>=0A=
			<exec operation=3D"registerCustomer">=0A=
				<!-- Set result to the 'customer' variable -->=0A=
				<result variable=3D"$errors"/>=0A=
			</exec>=0A=
			<if test=3D"$errors">=0A=
				<goto state=3D"customer.registration.error"/>=0A=
			</if>=0A=
			<!-- Do not send any response to user - just switch to a new state =
-->=0A=
			<goto state=3D"customer.personal.edit"/>=0A=
		</on-enter>=0A=
	</state>=0A=
	<!--=0A=
		REVISIT (KP): Can we have many final-states? =0A=
		Example: registration success or error states=0A=
	-->=0A=
	<final-state id=3D"customer.registration.error" =
form=3D"customer.registration.error"/>=0A=
	<final-state id=3D"customer.registration.final" =
form=3D"customer.registration.final">=0A=
		<!-- REVISIT (KP): Switch to the previous active script or show =
default screen -->=0A=
	</final-state>=0A=
</script>=0A=

------_=_NextPart_000_01C1DFA9.13543F80
Content-Type: application/octet-stream;
	name="sitemap.xmap"
Content-Disposition: attachment;
	filename="sitemap.xmap"

<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
	<!-- =========================== Components ================================ -->
	<map:components>
		<map:generators default="file"/>
		<map:transformers default="xslt"/>
		<map:readers default="resource"/>
		<map:serializers default="html"/>
		<map:selectors default="browser"/>
		<map:matchers default="wildcard">
			<map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcherFactory"/>
		</map:matchers>
		<map:actions>
			<map:action name="start-process" src="regtest.StartProcessAction"/>
			<map:action name="input-process" src="regtest.InputAction"/>			
		</map:actions>
	</map:components>
	<!-- =========================== Pipelines ================================= -->
	<map:pipelines>
		<map:pipeline>
			<map:match pattern="process/start">
				<map:act type="start-process">
					<map:read src="jsp/{start-page}.jsp" mime-type="text/html"/>
				</map:act>
				<map:read src="html/welcome.htm"/>
			</map:match>
			
			<map:match pattern="process/input">
				<map:act type="input-process">
					<map:read src="jsp/{current-page}.jsp" mime-type="text/html"/>
				</map:act>
				<map:read src="html/welcome.htm"/>
			</map:match>			
		
			<map:match pattern="*.htm">
				<map:read src="html/{1}.htm"/>
			</map:match>

			<map:match pattern="**/*.css">
				<map:read src="css/{2}.css" mime-type="text/css"/>
			</map:match>

			<map:match pattern="*.css">
				<map:read src="css/{1}.css" mime-type="text/css"/>
			</map:match>
			<map:match pattern="**/*.gif">
				<map:read src="images/{2}.gif" mime-type="image/gif"/>
			</map:match>
		</map:pipeline>
	</map:pipelines>
</map:sitemap>
<!-- end of file -->


------_=_NextPart_000_01C1DFA9.13543F80
Content-Type: text/plain; charset=us-ascii

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
------_=_NextPart_000_01C1DFA9.13543F80--