samples/databinding-echo/README

DataBinding Echo Sample
=======================

This sample demonstrates how databindings are used to convert data formats as 
the data flows between components. 

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;..\binding-echo-extension\target\sample-binding-echo-extension.jar;target\sample-databinding-echo.jar dbecho.EchoDataBindingClient

and on *nix do

java -cp ../../lib/tuscany-sca-manifest.jar:../binding-echo-extension/target/sample-binding-echo-extension.jar:target/sample-databinding-echo.jar dbecho.EchoDataBindingClient


Sample Overview
---------------
If reference and service interfaces are the same in all but the formats of 
data being passed to and returned from the operations of the interfaces,
then SCA will try to apply appropriate transformations to the data formats
to allow messages to pass. 

This sample shows this happening. ComponentA implements Interface1 which
defines;

 String call(String msg)
 String call1(String msg) 
 
ComponentA defines a reference to ComponentB with Interface1. ComponentB 
however implements Interface2 which defines;

 Node call(Node msg);
 XMLStreamReader call1(XMLStreamReader msg);
 
You can see from the test output below that SCA converts the call() msg from a 
String to a DOM object (org.apache.xerces.dom.DeferredDocumentImpl). It
converts the call1() msg from a String to a XML stream reader 
(com.ctc.wstx.sr.ValidatingStreamReader).

databinding-echo/
  src/
    main/
      java/
        dbecho/
          ComponentAImpl.java                           - component implementation 
          ComponentBImpl.java                           - component implementation
          Echo.java                                     - service interface with data binding
          EchoDataBindingClient.java                    - sample client code
          Interface1.java                               - service interface with data binding
          Interface2.java                               - service interface with data bindings
      resources/
        META-INF/
          services/
            org.apache.tuscany.sca.core.ModuleActivator - specifies the module activation class to call
        EchoDataBinding.composite                       - composite definition
        wsdl/
          echo.wsdl                                     - WSDL deinitions
    test/
      java/ 
        dbecho/
          EchoDataBindingTestCase.java - junit test case
  databinding-echo.png - pictorial representation of the sample .composite file
  build.xml            - the Ant build file
  pom.xml              - the Maven build file
  
TODO - Needs more description of what else is going on in this test
       properties, wsdl?

  
Building And Running The Sample Using Ant
-----------------------------------------
With the binary distribution the sample can be built and run using Ant as 
follows.

cd databinding-echo
ant compile
ant run

You should see the following output from the run target.

run:
     [java] [Property] prefix: ABC
     [java] [Property] prefix1: ABC
     [java] [Property] bar: BAR
     [java] ComponentA --> Received message: <message><foo>123</foo></message> [java.lang.String]
     [java] ComponentB --> Received message: [#document: null] [org.apache.xerces.dom.DeferredDocumentImpl]
     [java] ComponentB --> Returned message: [#document: null] [org.apache.xerces.dom.DeferredDocumentImpl]
     [java] ComponentA --> Returned message: <?xml version="1.0" encoding="UTF-8"?><message><foo>123</foo></message> [java.lang.String]
     [java] [Property] prefix: ABC
     [java] [Property] prefix1: ABC
     [java] [Property] bar: BAR
     [java] ComponentA --> Received message: <message><foo>123</foo></message> [java.lang.String]
     [java] ComponentB --> Received message: com.ctc.wstx.sr.ValidatingStreamReader@4c444c44 [com.ctc.wstx.sr.ValidatingStreamReader]
     [java] ComponentB --> Returned message: com.ctc.wstx.sr.ValidatingStreamReader@4c444c44 [com.ctc.wstx.sr.ValidatingStreamReader]
     [java] ComponentA --> Returned message: <?xml version='1.0' encoding='UTF-8'?><message><foo>123</foo></message> [java.lang.String]
     [java] call  response = <?xml version="1.0" encoding="UTF-8"?><message><foo>123</foo></message>
     [java] call1 response = <?xml version='1.0' encoding='UTF-8'?><message><foo>123</foo></message>


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. 

cd databinding-echo
mvn

You should see the following output from the test phase.

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running dbecho.EchoDataBindingTestCase
[Property] prefix: ABC
[Property] prefix1: ABC
[Property] bar: BAR
ComponentA --> Received message: <message><foo>123</foo></message> [java.lang.String]
ComponentB --> Received message: [#document: null] [org.apache.xerces.dom.DeferredDocumentImpl]
ComponentB --> Returned message: [#document: null] [org.apache.xerces.dom.DeferredDocumentImpl]
ComponentA --> Returned message: <?xml version="1.0" encoding="UTF-8"?><message><foo>123</foo></message> [java.lang.String]
[Property] prefix: ABC
[Property] prefix1: ABC
[Property] bar: BAR
ComponentA --> Received message: <message><foo>123</foo></message> [java.lang.String]
ComponentB --> Received message: com.ctc.wstx.sr.ValidatingStreamReader@74e274e2 [com.ctc.wstx.sr.ValidatingStreamReader]
ComponentB --> Returned message: com.ctc.wstx.sr.ValidatingStreamReader@74e274e2 [com.ctc.wstx.sr.ValidatingStreamReader]
ComponentA --> Returned message: <?xml version='1.0' encoding='UTF-8'?><message><foo>123</foo></message> [java.lang.String]
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.653 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

This shows that the Junit test cases have run successfully.