samples/holder-ws-service/README

Holder Pattern Service Sample
======================================
This sample demonstrates an SCA service that uses a web service binding. The
web service binding has been generated from a given WSDL file:
   src/main/resources/wsdl/orderservice.wsdl
The generated binding has been placed in src/main/java/org/examle/orderservice
and was generated via the JDK tool wsimport and the command:
    wsimport -d orderservice -keep orderservice.wsdl

The interesting feature of this sample is that the generated service interface,
OrderService, contains a method with the signature:
    public void reviewOrder(
        @WebParam(name = "myData", targetNamespace = "", mode = WebParam.Mode.INOUT)
        javax.xml.ws.Holder<Order> orderData);
The orderData parameter is an input/output parameter that is provided by the caller,
updated by the service, and returned to the caller. The business object is updated
in place, a common pattern in web services, and not returned as a response. Tuscany
can handle limited instances of this pattern.

The README in the samples directory (the directory above this) provides 
general instructions about building and running samples. Take a look there 
first. 

If you just want to run it to see what happens open a command prompt, navigate
to this sample directory and do:

ant run

OR if you don't have ant, on Windows do

java -cp ..\..\lib\tuscany-sca-manifest.jar;target\sample-holder-ws-service.jar org.example.orderservice.OrderServiceTestCase

and on *nix do

java -cp ../../lib/tuscany-sca-manifest.jar:target/sample-holder-ws-service.jar org.example.orderservice.OrderServiceTestCase

Sample Overview
---------------
The sample provides a single component that is wired to a service with a 
web service binding.

holder-ws-service/
  src/
    main/
      java/
        org/
           example/
              orderservice
                 *.java                   - Web service binding generated from 
                                            HelloWorldServiceComponent
      resources/
        wsdl/
          orderservice.wsdl               - the service description that describes
                                            the exposed service
        orderws.composite                 - the SCA assembly that uses this service
    test/
      java/
        helloworld/
          org/
             example/
                orderservice/
                   OrderServiceTestCase.java - JUnit test case 
  build.xml                               - the Ant build file
  pom.xml                                 - the Maven build file        

Building And Running The Sample Using Ant
-----------------------------------------
With the binary distribution the sample can be built and run using Ant using the 
following commands

cd holder-ws-service
ant compile
ant run

You should see the following output from the run target.

run:
     [java] 14-Jan-2008 14:18:47 org.apache.tuscany.sca.http.jetty.JettyServer a
ddServletMapping
     [java] INFO: Added Servlet mapping: http://L3AW203:8085/HelloWorldService
     [java] HelloWorld server started (press enter to shutdown)
     
As this point the SCA service is exposed as a web service by a web server 
started automatically by the SCA runtime. To stop the server just press 
enter.

To exercise the service run up the helloworld-ws-reference sample. Take a look at 
the README in that sample and you will see you need the following commands

cd holder-ws-reference
ant run

Building And Running The Sample Using Maven 
-------------------------------------------
With either the binary or source distributions the sample can be built and run 
using Maven as follows. When using Maven you don't need to run the helloworld-
ws-reference sample as Maven includes a simple ping test to make sure that the
service is available

cd holder-ws-service
mvn

You should see the following output from the test phase.
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.example.orderservice.OrderServiceTestCase
Jan 21, 2009 9:31:11 AM org.apache.tuscany.sca.node.impl.NodeImpl <init>
INFO: Creating node: META-INF/sca-deployables/orderws.composite
Jan 21, 2009 9:31:13 AM org.apache.tuscany.sca.node.impl.NodeImpl configureNode
INFO: Loading contribution: file:/E:/t/branches/sca-java-1.x/samples/holder-ws-webservice/target/classes/
Jan 21, 2009 9:31:14 AM org.apache.tuscany.sca.node.impl.NodeImpl configureNode
INFO: Loading composite: file:/E:/t/branches/sca-java-1.x/samples/holder-ws-webservice/target/classes/META-INF/sca-deployables/orderws.composite
Jan 21, 2009 9:31:14 AM org.apache.tuscany.sca.node.impl.NodeImpl start
INFO: Starting node: META-INF/sca-deployables/orderws.composite
- No JMS connection factories are defined.Will not listen for any JMS messages
Jan 21, 2009 9:31:15 AM org.apache.catalina.core.StandardEngine start
INFO: Starting Servlet Engine: Apache Tomcat/6.0.14
Jan 21, 2009 9:31:15 AM org.apache.catalina.startup.ContextConfig defaultWebConfig
INFO: No default web.xml
Jan 21, 2009 9:31:15 AM org.apache.coyote.http11.Http11Protocol init
INFO: Initializing Coyote HTTP/1.1 on http-8085
Jan 21, 2009 9:31:15 AM org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8085
- No JMS connection factories are defined.Will not listen for any JMS messages
Jan 21, 2009 9:31:15 AM org.apache.tuscany.sca.http.tomcat.TomcatServer addServletMapping
INFO: Added Servlet mapping: http://T602010:8085/OrderService
>>> Order submitted=Order[customerId=cust1234,orderId=0,total=50.0,status=Created]
>>> OrderService.reviewOrder return=Order[customerId=cust1234,orderId=0,total=50.0,status=Approved]
>>> Order returned=Order[customerId=cust1234,orderId=0,total=50.0,status=Approved]
Jan 21, 2009 9:31:16 AM org.apache.tuscany.sca.node.impl.NodeImpl stop
INFO: Stopping node: META-INF/sca-deployables/orderws.composite
Jan 21, 2009 9:31:17 AM org.apache.tuscany.sca.http.tomcat.TomcatServer removeServletMapping
INFO: Removed Servlet mapping: http://T602010:8085/OrderService
Jan 21, 2009 9:31:17 AM org.apache.coyote.http11.Http11Protocol destroy
INFO: Stopping Coyote HTTP/1.1 on http-8085

Note the console output with ">>>" prefix. This shows that an order was submitted in
the "Created" state, handled by the OrderService reviewOrder method, and returned in
the "Approved" state. This shows that the Junit test cases have run successfully.