Copyright (C) Bull, 2001-2002


Example description
-------------------

The object of this example is to show how Message driven beans may
be involved in global transactions as well as Entity beans

In this sample appli:

	- StockBean is an entity bean CMP that handles a stock table 
	  a Stock item is composed with a Stockid (String) which is the primary key
	  and a Quantity (int)
	  the method decreaseQuantity(int qty) decrease the quantity for the
	  corresponding stockid but may throw a RemoteException "Negative stock"

	- StockHandlerBean is a Message Driven Bean that receives Map messages:
		"CustomerId", String
		"ProductId", String
		"Quantity", int

	  the onMessage method will run in the scope of a transaction started
	  by the the container in the receipt of a message on the
	  topic (StockHandlerTopic)
          it will send a Text message on a Queue (OrdersQueue) and decrease
	  the stock quantity for the Stock element identified by the "ProductId".
          If it catch a RemoteException on the decreaseQuantity method it will call 
	  the setRollbackOnly method of the MessageDrivenContext linked to the
	  instance in this case the container transaction will be rolled back.

	- OrderBean is another Message Driven Bean listening on the OrdersQueue Queue
	  on receipt of a Text message on this queue it will write the corresponding
          String as a new line in a file (order.txt)

        - EnvBean is a stateless session bean used for creating the stock table
	  in the database and for deleting this table

	- SampleAppliClient is a java application that sends n messages to the
	  topic StockHandlerTopic for decreasing several Stock items these
	  n messages doesn't cause the raise of Remote Exception negative stock
          and sends one message on the Stock id "00000" that must cause
	  a rollback of the transaction.
	  At the end it verifies the number of messages received by the
	  Order message driven bean by counting the nb of lines in the
	  order.txt file (it must be equal to n) and verifies that the 
	  stock quantity for "00000" has not changed and all the other must
          be equal to 1.


Compiling the example:
---------------------

On $JONAS_ROOT/examples/src/mdb/sampleappli, run the compile script,
 - compile.sh on Unix or
 - compile.bat on Windows.

If the gnu make is installed on your machine you can also build this example
by using the Makefile as it is defined in the $JONAS_ROOT/example/README.

If the Ant 1.4 build tool is installed on your machine you can also build this
example by using the build.xml as it is defined in the $JONAS_ROOT/example/README.


Running this example:
---------------------

1) You should have in your classpath, access to the JOnAS classes and
prerequired classes for JOnAS:
	. $JONAS_ROOT/bin/unix/config_env	# set CLASSPATH for JOnAS

You may use the run.sh on Unix or run.bat on Windows scripts to execute the
whole example or step by step:


2) Run the JmsServer:
	JmsServer&

3) Run the EJB Server :
	EJBServer&

4) Run the EJB client:
	# Be careful to run this client in the same directory than EJBServer,
	# because they both access the same file "order.txt"!
	java sampleappli.SampleAppliClient

5) Stops the server
	JonasAdmin -s


You may want to execute this example with the MOM JMS that is running in the JOnAS JVM
 - you must set the property jonas.service.jms.collocated to true in
   the jonas.properties file
 - then
   step 1 as before
 - then you skip the step 2, and do step 3 to step 5 as before


