You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/22 17:16:05 UTC
svn commit: r1222320 [12/13] - in /synapse/branches/2.1/src: ./ site/
site/resources/ site/resources/css/ site/resources/images/ site/xdoc/
site/xdoc/userguide/ site/xdoc/userguide/samples/
site/xdoc/userguide/samples/setup/
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample652.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample652.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample652.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample652.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,136 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Sample 652</title>
+ </properties>
+ <body>
+ <section name="Sample 652: Distributed transaction management">
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+<sequence name="myFaultHandler">
+ <log level="custom">
+ <property name="text" value="** Rollback Transaction**"/>
+ </log>
+ <transaction action="rollback"/>
+ <send/>
+</sequence>
+
+<sequence name="main" onError="myFaultHandler">
+ <in>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ </in>
+
+ <out>
+ <transaction action="new"/>
+
+ <log level="custom">
+ <property name="text" value="** Reporting to the Database esbdb**"/>
+ </log>
+ <dbreport useTransaction="true" xmlns="http://ws.apache.org/ns/synapse">
+ <connection>
+ <pool>
+ <dsName>java:jdbc/XADerbyDS</dsName>
+ <icClass>org.jnp.interfaces.NamingContextFactory</icClass>
+ <url>localhost:1099</url>
+ <user>synapse</user>
+ <password>synapse</password>
+ </pool>
+ </connection>
+ <statement>
+ <sql>delete from company where name =?</sql>
+ <parameter expression="//m0:return/m1:symbol/child::text()"
+ xmlns:m0="http://services.samples" xmlns:m1="http://services.samples/xsd"
+ type="VARCHAR"/>
+ </statement>
+ </dbreport>
+
+ <log level="custom">
+ <property name="text" value="** Reporting to the Database esbdb1**"/>
+ </log>
+ <dbreport useTransaction="true" xmlns="http://ws.apache.org/ns/synapse">
+ <connection>
+ <pool>
+ <dsName>java:jdbc/XADerbyDS1</dsName>
+ <icClass>org.jnp.interfaces.NamingContextFactory</icClass>
+ <url>localhost:1099</url>
+ <user>synapse</user>
+ <password>synapse</password>
+ </pool>
+ </connection>
+ <statement>
+ <sql> INSERT into company values ('IBM','c4',12.0)</sql>
+ </statement>
+ </dbreport>
+ <transaction action="commit"/>
+ <send/>
+ </out>
+</sequence>
+</definitions></div>
+ <subsection name="Objective">
+ <p>
+ Demonstrate the use of the transaction mediator in a distributed transaction
+ </p>
+ </subsection>
+ <subsection name="Pre-requisites">
+ <p>
+ <ul>
+ <li>
+ Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
+ <p>To run this sample it is required to deploy synpase on JBoss application server(This is only tested with JBoss application sever), you
+ can use the war distribution to deploy synapse on JBoss application server. Use the synpase_sample_652.xml as the synapse confiuration
+ file and start JBoss with that synpase configuration file. Also you need to define two XA datasources for above two datasources.
+ You'll need to refer JBoss documentation to see how to do this.</p>
+ <p>
+ It also required to have two database instances, this will be used by the two XA datasources.
+ Refer the <a href="setup/db.html#derby">Sample Setup Guide </a> to see how you can set up the derby database server.
+ </p>
+ <p>
+ In this sample a record is delete from one database and it is added into the second database.
+ If either of the operations(deleting from the 1st database and adding into the second database)
+ fails everything will be roll backed. The records will be untoched.
+ </p>
+ </li>
+ <li>
+ Start Synapse using the configuration numbered 652 (repository/conf/sample/synapse_sample_652.xml)
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 652<br/>
+ Windows: synapse.bat -sample 652
+ </div>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Executing the Client">
+ <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</div>
+
+ <div class="consoleOutput">Sat Nov 18 21:01:23 IST 2006 SimpleStockQuoteService :: Generating quote for : IBM</div>
+
+ <div class="consoleOutput">Standard :: Stock price = $95.26454380258552</div>
+ </subsection>
+ </section>
+ <p><a href="../samples.html">Back to Catalog</a></p>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample7.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample7.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample7.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample7.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,116 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Sample 7</title>
+ </properties>
+ <body>
+ <section name="Sample 7: Introduction to Local Registry Entries and Using Schema Validation">
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="main">
+ <in>
+ <validate>
+ <schema key="validate_schema"/>
+ <on-fail>
+ <!-- if the request does not validate againt schema throw a fault -->
+ <makefault response="true">
+ <code xmlns:tns="http://www.w3.org/2003/05/soap-envelope" value="tns:Receiver"/>
+ <reason value="Invalid custom quote request"/>
+ </makefault>
+ </on-fail>
+ </validate>
+ </in>
+ <send/>
+ </sequence>
+
+ <localEntry key="validate_schema">
+ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://services.samples" elementFormDefault="qualified"
+ attributeFormDefault="unqualified" targetNamespace="http://services.samples">
+ <xs:element name="getQuote">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="request">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="stocksymbol" type="xs:string"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:schema>
+ </localEntry>
+
+</definitions></div>
+ <subsection name="Objective">
+ <p>
+ Demonstrating the usage of the validate mediator for XML schema validation
+ and using local registry (local entries) for storing configuration metadata.
+ </p>
+ </subsection>
+ <subsection name="Pre-requisites">
+ <p>
+ <ul>
+ <li>
+ Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
+ </li>
+ <li>
+ Start Synapse using the configuration numbered 7 (repository/conf/sample/synapse_sample_7.xml)
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 7<br/>
+ Windows: synapse.bat -sample 7
+ </div>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Executing the Client">
+ <p>
+ This example shows how a static XML fragment could be stored in the the
+ Synapse local registry. Resources defined in the local registry are static
+ (i.e. never changes over the lifetime of the configuration) and may be
+ specified as a source URL, in-line text or in-line xml. In this example the
+ schema is made available under the key 'validate_schema'.
+ </p>
+ <p>
+ The validate mediator by default operates on the first child element of the
+ SOAP body. You may specify an XPath expression using the 'source' attribute
+ to override this behaviour. The validate mediator in this sample uses the 'validate_schema'
+ resource to validate the incoming message, and if the message validation fails
+ it invokes the 'on-fail' sequence of mediators.
+ </p>
+ <p>
+ If you send a stockquote request using the 'ant stockquote ...' command as follows
+ you will get a fault back with the message 'Invalid custom quote request' as
+ the schema validation fails. This is because the schema used in the example
+ expects a slightly different message than what is created by the stock quote
+ client. (i.e. expects a 'stocksymbol' element instead of 'symbol' to specify
+ the stock symbol)
+ </p>
+ <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</div>
+ </subsection>
+ </section>
+ <p><a href="../samples.html">Back to Catalog</a></p>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample700.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample700.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample700.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample700.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,102 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Sample 700</title>
+ </properties>
+ <body>
+ <section name="Sample 700: Introduction to Synapse Message Store">
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!--Simple in Memory Message Store with name foo -->
+ <messageStore name="foo" sequence="bar">
+ <redelivery>
+ <!--retry interval 1 sec -->
+ <interval>1</interval>
+ <!--Message will be stored after 2 redeliveries -->
+ <maximumRedeliveries>2</maximumRedeliveries>
+ <exponentialBackoff>true</exponentialBackoff>
+ <backoffMutiplier>2</backoffMutiplier>
+ </redelivery>
+ </messageStore>
+
+ <!-- filtering of messages with XPath and regex matches -->
+ <filter source="get-property('To')" regex=".*/StockQuote.*">
+ <send>
+ <endpoint key="SampleEndpoint"/>
+ </send>
+ <drop/>
+ </filter>
+ <send/>
+ <!-- Endpoint named SampleEndpoint-->
+ <endpoint name="SampleEndpoint" onFault="foo">
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService">
+ <suspendDurationOnFailure>2</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+
+ <sequence name="bar">
+ <log level="full"/>
+ </sequence>
+</definitions></div>
+ <subsection name="Objective">
+ <p>
+ Demonstrate the usage of Synapse message stores and how to use a message store
+ to implement the popular 'Dead Letter Channel' integration pattern
+ </p>
+ </subsection>
+ <subsection name="Pre-requisites">
+ <p>
+ <ul>
+ <li>
+ Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
+ </li>
+ <li>
+ Start Synapse using the configuration numbered 700 (repository/conf/sample/synapse_sample_700.xml)
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 700<br/>
+ Windows: synapse.bat -sample 700
+ </div>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Executing the Client">
+ <p>
+ First execute the sample client as follows.
+ </p>
+ <div class="command">ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuote</div>
+ <p>
+ Since you have the sample Axis2 server running, you will get a stock quote response
+ at the client side. Axis2 server will also print a log confirming the generation
+ of a new quote value. Now shut the Axis2 server down and invoke the sample client
+ again. Now Synapse will attempt twice to deliever the message and faling that, the
+ message will be stored in the specified in-memory message store (dead letter channel)
+ for later delivery.
+ </p>
+ <p>
+ Now you can use the JMX view of the Synapse message store to see the message
+ stored in the dead letter channel and manually retry on them.
+ </p>
+ </subsection>
+ </section>
+ <p><a href="../samples.html">Back to Catalog</a></p>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample8.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample8.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample8.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample8.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,149 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Sample 8</title>
+ </properties>
+ <body>
+ <section name="Sample 8: Introduction to Static and Dynamic Registry Resources, and Using XSLT Transformations">
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:repository/conf/sample/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <!-- define the request processing XSLT resource as a static URL source -->
+ <localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/>
+
+ <sequence name="main">
+ <in>
+ <!-- transform the custom quote request into a standard quote requst expected by the service -->
+ <xslt key="xslt-key-req"/>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <!-- the key is looked up in the remote registry and loaded as a 'dynamic' registry resource -->
+ <xslt key="transform/transform_back.xslt"/>
+ </out>
+ <send/>
+ </sequence>
+
+</definitions></div>
+ <subsection name="Objective">
+ <p>
+ Demonstrating the usage of the XSLT mediator for transforming message content
+ and using local registry and remote registry for storing configuration
+ metadata.
+ </p>
+ </subsection>
+ <subsection name="Pre-requisites">
+ <p>
+ <ul>
+ <li>
+ Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
+ </li>
+ <li>
+ Start Synapse using the configuration numbered 8 (repository/conf/sample/synapse_sample_8.xml)
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 8<br/>
+ Windows: synapse.bat -sample 8
+ </div>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Executing the Client">
+ <p>
+ This example uses the XSLT mediator to perform transformations, and the xslt
+ transformations are specified as registry resources. The first resource
+ 'xslt-key-req' is specified as a 'local' registry entry. Local entries do not
+ place the resource on the registry, but simply make it available to the local
+ configuration. If a local entry is defined with a key that already exists in
+ the remote registry, the local entry will get higher precedence over the remote
+ resource.
+ </p>
+ <p>
+ In this example you will notice the new 'registry' definition. Synapse comes
+ with a simple URL based registry implementation (SimpleURLRegistry). During
+ initialization of the registry, the SimpleURLRegistry expects to find a property
+ named 'root', which specifies a prefix for the registry keys used later.
+ When the SimpleURLRegistry is used, this root is prefixed to the entry keys to
+ form the complete URL of the resource being looked up. The registry caches a
+ resource once requested, and stores it internally for a specified duration.
+ Once this period expires, it will reload the meta information about the resource
+ and reloads its cached copy if necessary, the next time the resource is requested.
+ </p>
+ <p>
+ Hence the second XSLT resource key 'transform/transform_back.xslt' concatenated
+ with the 'root' of the SimpleURLRegistry 'file:repository/conf/sample/resources/'
+ forms the complete URL of the resource as
+ 'file:repository/conf/sample/resources/transform/transform_back.xslt' and caches
+ its value for a period of 15000 ms.
+ </p>
+ <p>
+ Execute the custom quote client as follows and analyze the the Synapse debug
+ log output.
+ </p>
+ <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote</div>
+ <p>
+ The incoming message is transformed into a standard stock quote request by the
+ XSLT mediator. The XSLT mediator uses Xalan-J to perform the transformations.
+ It is possible to configure the underlying transformation engine using properties
+ when necessary. The response from the SimpleStockQuoteService is converted back
+ into the custom format as expected by the client during the out message processing.
+ </p>
+ <p>
+ During the response processing you could see the SimpleURLRegistry fetching the
+ resource as shown by the log message below.
+ </p>
+ <div class="consoleOutput">[HttpClientWorker-1] DEBUG SimpleURLRegistry ==> Repository fetch of resource with key : transform/transform_back.xslt</div>
+ <p>
+ If you run the client again immediately (i.e within 15 seconds of the first
+ request) you will not see the resource being reloaded by the registry as the
+ cached value would be still valid.
+ </p>
+ <p>
+ However if you leave the system idle for 15 seconds or more and then retry the
+ same request, you will now notice that the registry notices the cached resource
+ has expired and will reload the meta information about the resource to check if
+ the resource has changed and will require a fresh fetch from the source URL.
+ If the meta data / version number indicates that a reload of the cached resource
+ is not necessary (i.e. unless the resource itself actually changed) the updated
+ meta information is used and the cache lease extended as appropriate.
+ </p>
+ <div class="consoleOutput">[HttpClientWorker-1] DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
+[HttpClientWorker-1] DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
+[HttpClientWorker-1] DEBUG AbstractRegistry - Expired version number is same as current version in registry
+[HttpClientWorker-1] DEBUG AbstractRegistry - Renew cache lease for another 15s</div>
+ <p>
+ Thus the SimpleURLRegistry allows resource to be cached, and updates are detected
+ so that the configuration changes could be reloaded without restarting the
+ Synapse instance.
+ </p>
+ </subsection>
+ </section>
+ <p><a href="../samples.html">Back to Catalog</a></p>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample800.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,120 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Sample 800</title>
+ </properties>
+ <body>
+ <section name="Sample 800: Introduction to REST API">
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- You can add any flat sequences, endpoints, etc.. to this synapse.xml file if you do
+ *not* want to keep the artifacts in several files -->
+<api name="StockQuoteAPI" context="/stockquote">
+ <resource uri-template="/view/{symbol}" methods="GET">
+ <inSequence>
+ <payloadFactory>
+ <format>
+ <m0:getQuote xmlns:m0="http://services.samples">
+ <m0:request>
+ <m0:symbol>$1</m0:symbol>
+ </m0:request>
+ </m0:getQuote>
+ </format>
+ <args>
+ <arg expression="get-property('uri.var.symbol')"/>
+ </args>
+ </payloadFactory>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
+ </endpoint>
+ </send>
+ </inSequence>
+ <outSequence>
+ <send/>
+ </outSequence>
+ </resource>
+ <resource url-pattern="/order/*" methods="POST">
+ <inSequence>
+ <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/>
+ <property name="OUT_ONLY" value="true"/>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
+ </endpoint>
+ </send>
+ </inSequence>
+ </resource>
+</api>
+</definitions></div>
+ <subsection name="Objective">
+ <p>
+ Objective: Introduction to REST API
+ </p>
+ </subsection>
+ <subsection name="Pre-requisites">
+ <p>
+ <ul>
+ <li>
+ Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2 Server
+ </li>
+ <li>
+ Start Synapse using the configuration numbered 800 (repository/conf/sample/synapse_sample_800.xml)
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 800<br/>
+ Windows: synapse.bat -sample 800
+ </div>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Executing the REST Client">
+ <p>
+ You might need a REST client like curl to test this
+ </p>
+ <div class="command">curl -v http://127.0.0.1:8280/stockquote/view/IBM</div>
+ <div class="command">curl -v http://127.0.0.1:8280/stockquote/view/MSFT</div>
+
+ <p>
+ The above GET calls will be handled by the first resource in the StockQuoteAPI.
+ These REST calls will get converted into SOAP calls and will be sent to the Axis2
+ server. Response will be sent to the client in POX format.
+ </p>
+ <p>
+ The following command POSTs a simple XML to the ESB. Save following sample place
+ order request as "placeorder.xml" file in your local file system and execute the
+ command. That is used to invoke a SOAP service. ESB returns the 202 response back to the client.
+ </p>
+ <div class="command">curl -v -d @placeorder.xml -H "Content-type: application/xml" http://127.0.0.1:8280/stockquote/order/</div>
+
+ <div class="xmlConf"><placeOrder xmlns="http://services.samples">
+ <order>
+ <price>50</price>
+ <quantity>10</quantity>
+ <symbol>IBM</symbol>
+ </order>
+</placeOrder></div>
+ </subsection>
+ </section>
+ <p><a href="../samples.html">Back to Catalog</a></p>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/sample9.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/sample9.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/sample9.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/sample9.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,110 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Sample 9</title>
+ </properties>
+ <body>
+ <section name="Sample 9: Introduction to Dynamic Sequences with Registry">
+ <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <sequence name="main">
+ <sequence key="sequence/dynamic_seq_1.xml"/>
+ </sequence>
+
+</definitions></div>
+ <subsection name="Objective">
+ <p>
+ Demonstrating the ability to load sequence definitions dynamically from the
+ remote registry.
+ </p>
+ </subsection>
+ <subsection name="Pre-requisites">
+ <p>
+ <ul>
+ <li>
+ Deploy the SimpleStockQuoteService in the sample Axis2 server and start Axis2
+ </li>
+ <li>
+ Start Synapse using the configuration numbered 9 (repository/conf/sample/synapse_sample_9.xml)
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 9<br/>
+ Windows: synapse.bat -sample 9
+ </div>
+ </li>
+ </ul>
+ </p>
+ </subsection>
+ <subsection name="Executing the Client">
+ <p>
+ This example demonstrates the dynamic behaviour of Synapse through the use of a
+ registry. Synapse supports dynamic definitions for sequences and endpoints, and
+ as seen before, for configuration resources (eg: schema files, XSLT files etc).
+ In this example we define a Synapse configuration which references a sequence
+ definition specified as a registry key. The registry key resolves to the actual
+ content of the sequence which would be loaded dynamically by Synapse at runtime,
+ and cached appropriately as per its definition in the registry. Once the cache
+ expires, Synapse would re-check the meta information for the definition and
+ re-load the sequence definition if necessary and re-cache it again.
+ </p>
+ <p>
+ Execute the client as follows.
+ </p>
+ <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</div>
+ <p>
+ Go through the mediation debug logs to see how Synapse has dynamically loaded
+ the sequence configurations from the registry.
+ </p>
+ <div class="consoleOutput">[HttpServerWorker-1] DEBUG SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
+...
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <dynamic_sequence> :: mediate()
+...
+[HttpServerWorker-1] INFO LogMediator - message = *** Test Message 1 ***</div>
+ <p>
+ Now if you execute the client immediately (i.e. within 15 seconds of the last
+ execution) you will notice that the sequence is not reloaded. If you edit the
+ sequence definition in repository/conf/sample/resources/sequence/dynamic_seq_1.xml
+ (i.e. edit the log message to read as '*** Test Message 2 ***') and execute the
+ client again, you will notice that the new message is not yet visible (i.e. if
+ you execute this within 15 seconds of loading the resource for the first time).
+ However, after 15 seconds elapsed since the original caching of the sequence,
+ you will notice that the new sequence is loaded and executed by Synapse from the
+ following log messages.
+ </p>
+ <div class="consoleOutput">[HttpServerWorker-1] DEBUG SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
+...
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <dynamic_sequence> :: mediate()
+...
+[HttpServerWorker-1] INFO LogMediator - message = *** Test Message 2 ***</div>
+ <p>
+ The cache timeout could be tuned appropriately by configuring the URL registry
+ to suit the environment and the needs.
+ </p>
+ </subsection>
+ </section>
+ <p><a href="../samples.html">Back to Catalog</a></p>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/db.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/db.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/db.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/db.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,193 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Database Setup Guide</title>
+ </properties>
+ <body>
+ <section name="Contents">
+ <ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#derby">Setting Up Apache Derby</a></li>
+ <li><a href="#mysql">Setting Up MySQL</a></li>
+ <li><a href="#other">Using Other Database Engines</a></li>
+ <li><a href="#ds">Setting Up Data Sources</a></li>
+ </ul>
+ </section>
+ <section name="Introduction" id="intro">
+ <p>
+ Apache Synapse has the ability to lookup and update relational databases through
+ JDBC. Any database engine that provides JDBC drivers can be integrated with
+ Synapse using the dblookup and dbreport mediators. Synapse ships with a collection
+ of samples which demonstrates various aspects of dblookup, dbreport mediators and
+ database integration. This article describes how to setup the databases, sample
+ tables and reusable data sources required to try these examples out.
+ </p>
+ <p>
+ Most samples assume Apache Derby is used as the database engine. And therefore this
+ article also focuses mainly on setting up Apache Derby. Byt in reality
+ any database engine can be used to run these samples. The database schema and SQL
+ queries described here will work with any database engine. However in such cases
+ some minor changes should be made to the Synapse configuration files.
+ </p>
+ <p>
+ Some samples involve invoking database stored procedures from Synapse. For these
+ samples MySQL database engine is assumed. Therefore this article provides some
+ basic information on setting up MySQL for the example scenarios.
+ </p>
+ </section>
+ <section name="Setting Up Apache Derby" id="derby">
+ <p>
+ To start with, download the latest binary distribution of <a href="http://db.apache.org/derby/">Apache Derby</a>.
+ Extract the downloaded archive to a suitable location in the local disk and switch
+ to the 'bin' directory of the installation. Start the Derby network server by
+ executing the 'startNetworkServer' startup script. An output similar to the following
+ will be displayed as the database engine starts up.
+ </p>
+ <div class="consoleOutput">Sun Jan 02 10:53:28 IST 2011 : Security manager installed using the Basic server security policy.
+Sun Jan 02 10:53:30 IST 2011 : Apache Derby Network Server - 10.7.1.1 - (1040133) started and ready to accept connections on port 1527</div>
+ <p>
+ Now launch the Derby client tool by executing the 'ij' script. This will give a command
+ prompt where you can execute various command and SQL queries. Execute the following
+ connect statement to create a fresh database named 'synapsedb' and obtain a connection
+ to it.
+ </p>
+ <div class="command">CONNECT 'jdbc:derby://localhost:1527/synapsedb;user=synapse;password=synapse;create=true';</div>
+ <p>
+ Now execute the following SQL query to create a new table.
+ </p>
+ <div class="command">CREATE table company(name varchar(10), id varchar(10), price double);</div>
+ <p>
+ Insert some sample data to the table by executing following statements.
+ </p>
+ <div class="command">INSERT into company values ('IBM','c1',0.0);
+INSERT into company values ('SUN','c2',0.0);
+INSERT into company values ('MSFT','c3',0.0);</div>
+ <p>
+ Now we have finished setting up the Derby server for the samples. As the final step
+ we should copy the Derby JDBC drivers to Synapse 'lib' directory. Locate the following
+ jar files in Derby installation and copy them into Synapse.
+ </p>
+ <ul>
+ <li>derby.jar</li>
+ <li>derbyclient.jar</li>
+ <li>derbynet.jar</li>
+ </ul>
+ </section>
+ <section name="Setting Up MySQL" id="mysql">
+ <p>
+ This section assumes that you already have a MySQL server instance up and running.
+ For details on installing MySQL, please refer the relevant
+ <a href="http://dev.mysql.com/doc/refman/5.1/en/installing.html">MySQL documentation</a>.
+ </p>
+ <p>
+ Create a new database named 'synapsedb' in MySQL. Then execute the SQL queries
+ given in the previous section to create a table named 'company' and insert some
+ sample data into it. Then execute the following two commands in MySQL client to
+ create two stored procedures.
+ </p>
+ <div class="command">CREATE PROCEDURE getCompany(compName VARCHAR(10)) SELECT name, id, price FROM company WHERE name = compName;
+CREATE PROCEDURE updateCompany(compPrice DOUBLE,compName VARCHAR(10)) UPDATE company SET price = compPrice WHERE name = compName;</div>
+ <p>
+ Then you should download the <a href="http://www.mysql.com/products/connector/">MySQL JDBC driver</a>
+ and deploy it into the 'lib' directory of Synapse.
+ </p>
+ </section>
+ <section name="Using Other Database Engines" id="other">
+ <p>
+ You can run the given samples using any RDBMS engine you prefer. In that case please
+ make sure you do the following.
+ </p>
+ <ul>
+ <li>Deploy the JDBC drivers for your database engine into Synapse</li>
+ <li>
+ Update the sample configuration files and change the driver class name and JDBC
+ connection string correctly
+ </li>
+ </ul>
+ </section>
+ <section name="Setting Up Data Sources">
+ <p>
+ Synapse is capable of connecting to databases through predefined data sources.
+ This enables database connection pooling and connection reuse. Different instances
+ of the database mediators (dblookup/dbreport) can either use different data sources
+ or share the same data source.
+ </p>
+ <p>
+ Data sources are configured in the synapse.properties file which can be found in the
+ 'lib' directory of the Synapse installation. Currently Synapse supports following
+ types of data sources.
+ </p>
+ <ul>
+ <li>BasicDataSource</li>
+ <li>PerUserPoolDataSource</li>
+ </ul>
+ <p>
+ Both these types of data sources are based on <a href="http://commons.apache.org/dbcp">Apache DBCP</a>.
+ </p>
+ <p>
+ Following section describes how to setup two data sources as required by some of the
+ database integration samples of Synapse. First, it is required to setup two
+ Derby databases. So launch 'ij' client tool for Derby and create two databases
+ named 'lookupdb' and 'reportdb'. Specify the username and password to be 'synapse'
+ for both databases. Create the 'company' table in each database and add some sample
+ data as described under <a href="#derby">Setting Up Apache Derby</a> section.
+ </p>
+ <p>
+ Now you can define two data sources for these databases by adding the following
+ entries to the synapse.properties file.
+ </p>
+ <div class="consoleOutput">synapse.datasources=lookupds,reportds
+synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory
+synapse.datasources.providerUrl=rmi://localhost:2199
+synapse.datasources.providerPort=2199
+
+synapse.datasources.lookupds.type=BasicDataSource
+synapse.datasources.lookupds.driverClassName=org.apache.derby.jdbc.ClientDriver
+synapse.datasources.lookupds.url=jdbc:derby://localhost:1527/lookupdb;create=false
+synapse.datasources.lookupds.username=synapse
+synapse.datasources.lookupds.password=synapse
+synapse.datasources.lookupds.dsName=lookupdb
+synapse.datasources.lookupds.maxActive=100
+synapse.datasources.lookupds.maxIdle=20
+synapse.datasources.lookupds.maxWait=10000
+
+synapse.datasources.reportds.type=PerUserPoolDataSource
+synapse.datasources.reportds.cpdsadapter.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
+synapse.datasources.reportds.cpdsadapter.className=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
+synapse.datasources.reportds.cpdsadapter.name=cpds
+synapse.datasources.reportds.dsName=reportdb
+synapse.datasources.reportds.driverClassName=org.apache.derby.jdbc.ClientDriver
+synapse.datasources.reportds.url=jdbc:derby://localhost:1527/reportdb;create=false
+synapse.datasources.reportds.username=synapse
+synapse.datasources.reportds.password=synapse
+synapse.datasources.reportds.maxActive=100
+synapse.datasources.reportds.maxIdle=20
+synapse.datasources.reportds.maxWait=10000</div>
+ <p>
+ Here we are defining two data sources named 'lookupds' and 'reportds'. The first
+ data source is defined as a BasicDataSource and the other one is defined as a
+ PerUserPoolDataSource. Note the various parameters we have specified for each
+ data source thereby further customizing the behavior of each data source.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/fix.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/fix.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/fix.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/fix.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,217 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - FIX Setup Guide</title>
+ </properties>
+ <body>
+ <section name="Contents">
+ <ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#pre">Prerequisites</a></li>
+ <li><a href="#synapse">Enabling FIX Transport in Synapse</a></li>
+ <li><a href="#services">Configuring Services for FIX Transport</a></li>
+ <li>
+ <a href="#samples">Setting Up the Sample FIX Applications</a>
+ <ul>
+ <li><a href="#exec">Configuring the Executor</a></li>
+ <li><a href="#banzai">Configuring Banzai</a></li>
+ </ul>
+ </li>
+
+ </ul>
+ </section>
+ <section name="Introduction" id="intro">
+ <p>
+ <a href="http://www.fixprotocol.org">FIX (Financial Information eXchange)</a>
+ is a domain specific communication protocol widely used in the finance sector for
+ securities transactions. The protocol specification spans across the application layer
+ and the session layer of the OSI reference model of networking. Apache Synapse comes
+ with a FIX transport adapter which enables the Synapse ESB to communicate with FIX
+ acceptors and initiators. This allows users to seamlessly integrate FIX applications
+ together and even link FIX applications with other systems that use different protocols.
+ </p>
+ <p>
+ This article describes how to enable and configure the FIX transport listener and
+ sender for Apache Synapse. It also describes how to setup various sample FIX applications
+ required to try out the FIX protocol related examples.
+ </p>
+ </section>
+ <section name="Prerequisites" id="pre">
+ <p>
+ The FIX transport adapter of Synapse is built on top of the <a href="http://www.quickfixj.org">Quickfix/J</a>
+ open source FIX engine. Therefore the users must deploy the Quickfix/J libraries
+ into Synapse before using the FIX transport. Also in order to try out the FIX
+ samples described in this documentation, it is required to have the 2 sample FIX
+ applications (Banzai and Executor) that come bundled with Quickfix/J. Therefore as
+ the first step <a href="http://www.quickfixj.org/downloads/">download</a> the latest
+ binary distribution of Quickfix/J and extract the downloaded archive to a suitable
+ location on the local disk (let's refer to this location as QFJ_HOME).
+ </p>
+ <p>
+ All the necessary Quickfix/J libraries are available in the Quickfix/J binary
+ distribution. You have to copy the following jar files from Quickfix/J installation
+ to the 'lib' directory of Synapse.
+ </p>
+ <ul>
+ <li>quickfixj-core.jar</li>
+ <li>quickfixj-msg-fix40.jar</li>
+ <li>quickfixj-msg-fix41.jar</li>
+ <li>quickfixj-msg-fix42.jar</li>
+ <li>quickfixj-msg-fix43.jar</li>
+ <li>quickfixj-msg-fix44.jar</li>
+ <li>mina-core.jar</li>
+ <li>slf4j-api.jar</li>
+ </ul>
+ <p>
+ The last 2 jar files can be found in the QFJ_HOME/bin directory and all other
+ files should be available in the QFJ_HOME itself.
+ </p>
+ </section>
+ <section name="Enabling FIX Transport in Synapse" id="synapse">
+ <p>
+ FIX transport listener and the FIX transport sender of Synapse can be enabled by
+ uncommenting the following sections in the repository/conf/axis2.xml file.
+ </p>
+ <div class="xmlConf"><transportReceiver name="fix" class="org.apache.synapse.transport.fix.FIXTransportListener"/></div>
+ <div class="xmlConf"><transportSender name="fix" class="org.apache.synapse.transport.fix.FIXTransportSender"/></div>
+ <p>
+ This will initialize the FIX transport adapter and have it up and running to be
+ used by the proxy services. However some additional setting should be applied at
+ the service level before a service can make use of the FIX transport.
+ </p>
+ </section>
+ <section name="Configuring Services for FIX Transport" id="services">
+ <p>
+ When a service needs to be exposed over the FIX transport, we should add the
+ following parameter to the service configuration.
+ </p>
+ <div class="xmlConf"><parameter name="transport.fix.AcceptorConfigURL">url</parameter></div>
+ <p>
+ The value of this parameter must be a valid URL which points to a Quickfix/J session
+ configuration file. All the FIX sample configurations are already equipped with this
+ parameter and they are pointing to the sample Quickfix/J configuration files that
+ comes with Synapse. These files can be found in the repository/sample/resources/fix
+ directory. One such configuration file (fix-synapse.cfg) is shown below.
+ </p>
+ <div class="consoleOutput">[default]
+FileStorePath=repository/fix/store/acceptor
+ConnectionType=acceptor
+StartTime=00:00:00
+EndTime=00:00:00
+HeartBtInt=30
+ValidOrderTypes=1,2,F
+SenderCompID=EXEC
+TargetCompID=SYNAPSE
+UseDataDictionary=Y
+DefaultMarketPrice=12.30
+
+[session]
+BeginString=FIX.4.0
+SocketAcceptPort=9876</div>
+ <p>
+ One of the most important parameters in this configuration is the SocketAcceptPort
+ setting. This defines the port used by the Synapse proxy service to receive
+ incoming FIX messages.
+ </p>
+ <p>
+ As far as the FIX samples are considered you don't have to make any changes to
+ these Quickfix/J configuration files or the Synapse sample configurations. Default
+ settings should work out of the box without any issues. However some samples may
+ require you to make minor changes to these files.
+ </p>
+ </section>
+ <section name="Setting Up the Sample FIX Applications" id="samples">
+ <p>
+ Two sample FIX applications are available in the Quickfix/J binray distribution
+ which can be used to send and receive FIX messages. By default these applications
+ are configured to directly communicate with each other. So we should make a few
+ modifications to the configuration to get them to communicate with Synapse. The
+ binaries of these sample programs are available in the quickfixj-examples.jar file
+ in QFJ_HOME. Startup scripts needed to run them can be found in the QFJ_HOME/bin
+ directory.
+ </p>
+ <subsection name="Configuring the Executor" id="exec">
+ <p>
+ Executor is the sample acceptor program. To configure this application to
+ receive messages from Synapse, put the following entries to a file named
+ 'executor.cfg'.
+ </p>
+ <div class="consoleOutput">[default]
+FileStorePath=examples/target/data/executor
+ConnectionType=acceptor
+StartTime=00:00:00
+EndTime=00:00:00
+HeartBtInt=30
+ValidOrderTypes=1,2,F
+SenderCompID=EXEC
+TargetCompID=SYNAPSE
+UseDataDictionary=Y
+DefaultMarketPrice=12.30
+
+[session]
+BeginString=FIX.4.0
+SocketAcceptPort=19876</div>
+ <p>
+ Note that TargetCompID parameter has been set to 'SYNAPSE' and the port number
+ has been set to 9876. You can launch the Executor using the above configuration
+ as follows.
+ </p>
+ <div class="command">Unix/Linux: sh executor.sh <path to executor.cfg><br/>
+Windows: executor.bat <path to executor.cfg></div>
+ <p>
+ For some samples you will have to make some minor modifications to this
+ configuration file.
+ </p>
+ </subsection>
+ <subsection name="Configuring Banzai" id="banzai">
+ <p>
+ Banzai is a sample FIX initiator that comes with Quickfix/J. This can be
+ used to send FIX messages to a defined FIX acceptor. In case of samples,
+ Synapse will act as the acceptor. In order to send messages to Synapse, we
+ should start Banzai using the following configuration.
+ </p>
+ <div class="consoleOutput">[default]
+FileStorePath=examples/target/data/banzai
+ConnectionType=initiator
+SenderCompID=BANZAI
+TargetCompID=SYNAPSE
+SocketConnectHost=localhost
+StartTime=00:00:00
+EndTime=00:00:00
+HeartBtInt=30
+ReconnectInterval=5
+
+[session]
+BeginString=FIX.4.0
+SocketConnectPort=9876</div>
+ <p>
+ Note that TargetCompID has been set to 'SYNAPSE' and the socket connect port
+ is specified to be 9876, which is the port used by Synapse. To start Banzai
+ with this configuration, save the above in a file named 'banzai.cfg' and
+ launch the sample application as follows.
+ </p>
+ <div class="command">Unix/Linux: sh banzai.sh <path to banzai.cfg><br/>
+Windows: banzai.bat <path to banzai.cfg></div>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/index.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/index.xml?rev=1222320&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/index.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/userguide/samples/setup/index.xml Thu Dec 22 16:16:02 2011
@@ -0,0 +1,388 @@
+<?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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache Synapse - Samples Setup Guide</title>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <p>
+ Apache Synapse comes with a collection of working examples that demonstrates the
+ basic features of the Synapse ESB. In addition to the sample configurations, a set
+ of sample client applications and services are provided which can be used to try out
+ each of the examples. Most examples are self contained and can be run without any third
+ party applications or libraries. A set of Ant build files and scripts are provided
+ to make setting up the examples easier. A few examples however require deploying
+ certain external libraries and using third party client applications.
+ </p>
+ <p>
+ The main objectives of this article are:
+ <ul>
+ <li>Introduce the concept of Synapse samples</li>
+ <li>Describe how to setup the environment for running samples</li>
+ <li>Describe how to run the sample client applications and services</li>
+ <li>Describe how to deploy third party libraries when required</li>
+ </ul>
+ </p>
+ </section>
+ <section name="Prerequisites">
+ <p>
+ Following applications are required to run any sample that comes with Synapse.
+ Please make sure you have them properly installed and configured in your system.
+ </p>
+ <ul>
+ <li>Java Development Kit version 1.5 or higher (1.6 recommended)</li>
+ <li><a href="http://ant.apache.org">Apache Ant</a> version 1.6.5 or higher</li>
+ <li>
+ A command line interface such as 'Command Prompt' on Windows and the Bash shell
+ on Unix/Linux systems
+ </li>
+ </ul>
+ <p>
+ When installing Java, make sure you setup the 'JAVA_HOME' environment variable
+ properly. Also adding the JAVA_HOME/bin directory to the system path will make
+ running the samples much easier.
+ </p>
+ <p>
+ In addition to the applications listed above, some samples require setting up few
+ other external resources such as JMS brokers and database engines. You can find the
+ relevant documentation under the '<a href="#Setting_Up_Additional_Resources">Setting Up Additional Features</a>'
+ section.
+ </p>
+ <p>
+ It is also advisable to run Synapse in the debug mode when trying out the example
+ configurations. This will give you important runtime status information that can be
+ used to better understand the functionality of Synapse. To enable the debug mode,
+ open up the lib/log4j.properties file and specify 'DEBUG' logging mode for the
+ 'org.apache.synapse' package.
+ </p>
+ <div class="consoleOutput">log4j.category.org.apache.synapse=DEBUG</div>
+ </section>
+ <section name="Understanding the Samples">
+ <p>
+ A Synapse sample scenario is generally comprised of three elements.
+ </p>
+ <ul>
+ <li>
+ Sample Synapse configuration (an XML configuration file given as the input
+ of Synapse)
+ </li>
+ <li>
+ Sample service (an Axis2 based Web Service to which Synapse will send messages)
+ </li>
+ <li>
+ Sample client (an Axis2 based service client which is used to send requests to
+ Synapse)
+ </li>
+ </ul>
+ <subsection name="Sample Synapse Configurations">
+ <p>
+ All the sample Synapse configurations are housed under the repository/conf/sample
+ directory. These configuration files are named in the following format.
+ </p>
+ <div class="consoleOutput">synapse_sample_n.xml</div>
+ <p>
+ Here 'n' is a number which uniquely identifies the sample. This number can be passed
+ as an argument to the Synapse startup script in order to start Synapse with a particular
+ sample configuration. For an example to start Synapse with the configuration numbered
+ 100 (ie synapse_sample_100.xml) run one of the following commands in the command line
+ interface.
+ </p>
+ <div class="command">
+ Unix/Linux: sh synapse.sh -sample 100<br/>
+ Windows: synapse.bat -sample 100
+ </div>
+ </subsection>
+ <subsection name="Sample Services">
+ <p>
+ All the source of example services can be found in the samples/axis2Server/src directory.
+ You will find the source code for following services in this directory.
+ </p>
+ <table>
+ <tr>
+ <th>Service</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>SimpleStockQuoteService</td>
+ <td>
+ This service has four operations; getQuote (in-out), getFullQuote(in-out),
+ getMarketActivity(in-out) and placeOrder (in-only). The getQuote operation
+ will generate a sample stock quote for a given symbol. The getFullQuote
+ operation will generate a history of stock quotes for the symbol for a
+ number of days, and the getMarketActivity operation returns stock quotes
+ for a list of given symbols. The placeOrder operation will accept a one
+ way message for an order.
+ </td>
+ </tr>
+ <tr>
+ <td>SecureStockQuoteService</td>
+ <td>
+ This service is a clone of the SimpleStockQuoteService, but has
+ WS-Security enabled and an attached security policy for signing and
+ encryption of messages.
+ </td>
+ </tr>
+ <tr>
+ <td>ReliableStockQuoteService</td>
+ <td>
+ This service is a clone of the SimpleStockQuoteService, but has
+ WS-ReliableMessaging enabled.
+ </td>
+ </tr>
+ <tr>
+ <td>MTOMSwASampleService</td>
+ <td>
+ This service has three operations uploadFileUsingMTOM(in-out),
+ uploadFileUsingSwA(in-out) and oneWayUploadUsingMTOM(in-only) and
+ demonstrates the use of MTOM and SwA. The uploadFileUsingMTOM and
+ uploadFileUsingSwA operations accept a binary image from the SOAP request
+ as MTOM and SwA, and returns this image back again as the response, while
+ the oneWayUploadUsingMTOM saves the request message to disk.
+ </td>
+ </tr>
+ <tr>
+ <td>LoadbalanceFailoverService</td>
+ <td>
+ A simple web service that can be used to test state less as well as
+ session aware load balancing scenarios.
+ </td>
+ </tr>
+ </table>
+ <p>
+ You can compile and deploy any of these services into the provided sample Axis2
+ server by switching to the corresponding directory and invoking 'ant'. For an
+ example to setup the SimpleStockQuoteService, switch to the
+ samples/axis2Server/src/SimpleStockQuoteService directory and run the 'ant'
+ command. You will get an output similar to the following.
+ </p>
+ <div class="consoleOutput">user@host:/tmp/synapse-1.1/samples/axis2Server/src/SimpleStockQuoteService$ ant
+Buildfile: build.xml
+...
+build-service:
+ ....
+ [jar] Building jar: /tmp/synapse-1.1/samples/axis2Server/repository/services/SimpleStockQuoteService.aar
+
+BUILD SUCCESSFUL
+Total time: 3 seconds</div>
+ <p>
+ To start the Axis2 server, go to the samples/axis2Server directory and execute
+ the axis2server.sh or axis2server.bat script. This starts the Axis2 server with
+ the HTTP transport listener on port 9000 and HTTPS on port 9002 respectively.
+ For some samples it is required to enable additional transport listeners for the
+ sample Axis2 server. The resources listed under '<a href="#Setting_Up_Additional_Resources">Setting Up Additional Features'</a>
+ section provides more information on this.
+ </p>
+ </subsection>
+ <subsection name="Sample Client Applications">
+ <p>
+ The client applications that come with Synapse are able to send SOAP, REST or
+ POX messages over transports like HTTP/S and JMS. They also support WS-Addressing,
+ WS-Security and WS-ReliableMessaging. Some sample clients can be used to send
+ pure binary or plain text messages. They are also capable of sending optimized
+ binary content using MTOM or SwA. Most sample scenarios involve invoking one
+ of these clients to send messages to Synapse. Synapse will then mediate those
+ requests and forward them to the sample services deployed on Axis2.
+ </p>
+ <p>
+ The sample clients can be executed from the samples/axis2Client directory
+ using the provided ant script. Simply executing 'ant' displays the available
+ clients and some of the options used to configure them. The sample clients
+ available are further described in the next section.
+ </p>
+ </subsection>
+ </section>
+ <section name="Sample Axis2 Clients">
+ <subsection name="Stock Quote Client">
+ <p>
+ This is a simple SOAP client that can send stock quote requests, receive
+ generated quotes and display the last sale price for a stock symbol.
+ </p>
+ <div class="command">ant stockquote [-Dsymbol=IBM|MSFT|SUN|..]
+ [-Dmode=quote | customquote | fullquote | placeorder | marketactivity]
+ [-Dsoapver=soap11 | soap12]
+ [-Daddurl=http://localhost:9000/services/SimpleStockQuoteService]
+ [-Dtrpurl=http://localhost:8280] [-Dprxurl=http://localhost:8280]
+ [-Dpolicy=../../repository/conf/sample/resources/policy/policy_1.xml]</div>
+ <p>
+ The client is able to operate in the following modes, and send the payloads
+ listed below as SOAP messages.
+ </p>
+ <table>
+ <tr>
+ <th>Mode</th>
+ <th>Payload</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>quote</td>
+ <td>
+ <div class="xmlConf"><m:getQuote xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getQuote></div>
+ </td>
+ <td>
+ Sends a quote request for a single stock symbol. The response
+ contains the last sales price for the stock which will be displayed on
+ console.
+ </td>
+ </tr>
+ <tr>
+ <td>customquote</td>
+ <td>
+ <div class="xmlConf"><m0:checkPriceRequest xmlns:m0="http://www.apache-synapse.org/test">
+ <m0:Code>symbol</m0:Code>
+</m0:checkPriceRequest></div>
+ </td>
+ <td>
+ Sends a quote request in a custom format. Synapse will transform this
+ custom request to the standard stock quote request format and send it to
+ the Axis2 service. Upon receipt of the response, it will be transformed
+ again to a custom response format and returned to the client, which will
+ then display the last sales price.
+ </td>
+ </tr>
+ <tr>
+ <td>fullquote</td>
+ <td>
+ <div class="xmlConf"><m:getFullQuote xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ </m:request>
+</m:getFullQuote></div>
+ </td>
+ <td>
+ Gets quote reports for a stock symbol over a number of days (i.e. last 100
+ days of the year).
+ </td>
+ </tr>
+ <tr>
+ <td>placeorder</td>
+ <td><div class="xmlConf"><m:placeOrder xmlns:m="http://services.samples">
+ <m:order>
+ <m:price>3.141593E0</m:price>
+ <m:quantity>4</m:quantity>
+ <m:symbol>IBM</m:symbol>
+ </m:order>
+</m:placeOrder></div></td>
+ <td>
+ Places an order for stocks using a one way request.
+ </td>
+ </tr>
+ <tr>
+ <td>marketactivity</td>
+ <td><div class="xmlConf"><m:getMarketActivity xmlns:m="http://services.samples">
+ <m:request>
+ <m:symbol>IBM</m:symbol>
+ ...
+ <m:symbol>MSFT</m:symbol>
+ </m:request>
+</m:getMarketActivity></div></td>
+ <td>
+ Gets a market activity report for the day (i.e. quotes for multiple
+ symbols)
+ </td>
+ </tr>
+ </table>
+ <p>
+ To run the stock quote client in a particular mode, pass the name of the mode
+ as a system property as follows.
+ </p>
+ <div class="command">ant stockquote -Dmode=placeorder</div>
+ <p>
+ Behavior of the sample Axis2 client can be further customized by using the 'addurl',
+ 'trpurl' and 'prxurl' parameters. These parameters enable the following modes of
+ operation.
+ </p>
+ <h5>Smart Client Mode</h5>
+ <p>
+ The 'addurl' property sets the WS-Addressing EPR, and the 'trpurl' sets a
+ transport URL for a message. Thus by specifying both of these properties,
+ the client can operate in the 'smart client' mode, where the addressing EPR can
+ specify the ultimate receiver, while the transport URL set to Synapse will ensure
+ that any necessary mediation takes place before the message is delivered to the
+ ultimate receiver.
+ </p>
+ <div class="command">ant stockquote -Daddurl=<addressingEPR> -Dtrpurl=<synapse></div>
+ <h5>Gateway/Dumb Client Mode</h5>
+ <p>
+ By specifying only a transport URL, the client operates in the 'dumb client'
+ mode, where it sends the message to Synapse and depends on the rules configured
+ in Synapse for proper mediation and routing of the message to the ultimate
+ destination.
+ </p>
+ <div class="command">ant stockquote -Dtrpurl=<synapse></div>
+ <h5>Proxy Client Mode</h5>
+ <p>
+ In this mode, the client uses the 'prxurl' as a HTTP proxy to send the request.
+ Thus by setting the 'prxurl' to Synapse, the client can ensure that the message
+ will reach Synapse for mediation. The client can optionally set a WS-Addressing
+ EPR if required.
+ </p>
+ <div class="command">ant stockquote -Dprxurl=<synapse> [-Daddurl=<addressingEPR>]</div>
+ </subsection>
+ <subsection name="Generic JMS Client">
+ <p>
+ The JMS client is able to send plain text, plain binary content or POX content
+ by directly publishing a JMS message to the specified destination. The JMS
+ destination name should be specified with the 'jms_dest' property. The 'jms_type'
+ property can specify 'text', 'binary' or 'pox' to specify the type of message
+ payload.
+ </p>
+ <p>
+ The plain text payload for a 'text' message can be specified through the 'payload'
+ property. For binary messages, the 'payload' property will contain the path to
+ the binary file. For POX messages, the 'payload' property will hold a stock
+ symbol name to be used within the POX request for stock order placement requests.
+ </p>
+ <div class="command">ant jmsclient -Djms_type=text -Djms_dest=dynamicQueues/JMSTextProxy -Djms_payload="24.34 100 IBM"
+ant jmsclient -Djms_type=pox -Djms_dest=dynamicQueues/JMSPoxProxy -Djms_payload=MSFT
+ant jmsclient -Djms_type=binary -Djms_dest=dynamicQueues/JMSFileUploadProxy
+ -Djms_payload=./../../repository/conf/sample/resources/mtom/asf-logo.gif</div>
+ <p>
+ The JMS client assumes the existence of a default ActiveMQ (v4.1.0 or above)
+ installation on the local machine. Refer JMS setup guide for more details.
+ </p>
+ </subsection>
+ <subsection name="MTOM/SwA Client">
+ <p>
+ The MTOM / SwA client is able to send a binary image file as a MTOM or SwA
+ optimized message, and receive the same file again through the response and save
+ it as a temporary file. The 'opt_mode' can specify 'mtom' or 'swa' respectively
+ for the above mentioned optimizations. Optionally the path to a custom file can
+ be specified through the 'opt_file' property, and the destination address can be
+ changed through the 'opt_url' property if required.
+ </p>
+ <div class="command">ant optimizeclient -Dopt_mode=[mtom | swa]</div>
+ </subsection>
+ </section>
+ <section name="Setting Up Additional Features">
+ <ul>
+ <li><a href="jms.html">JMS Setup Guide</a></li>
+ <li><a href="fix.html">FIX Setup Guide</a></li>
+ <li><a href="tcp_udp.html">TCP/UDP Setup Guide</a></li>
+ <li><a href="db.html">Database Setup Guide</a></li>
+ </ul>
+ </section>
+ </body>
+</document>