sagara's Blog

Timeout and Circuit Breaker Pattern in WSO2 Way

2015-05-02T14:34:00.000+05:30

When we develop enterprise scale software systems it's hard to avoid mistakes, sometimes these mistakes teach us very important lessons to avoid same mistake over again and also to craft softwares in much better way. Sometimes experienced developers recognize these repetitive solutions and fromalize them as Design Patterns. Sometimes without knowing we may practise these patterns, in this post I try to describe two design patterns called 'Timeout' and 'Circuit Breaker' and how are they used in WSO2 stack specially within WSO2 ESB.

Timeout Design Pattern

Timeout pattern is not something new, it has been used widely from early days of computing and networking. The basic idea here is when one system communicate with another, systems should not wait infinity to receive messages instead after waiting for a pre-defined interval systems should release their resources and should assume that other party can't communicate at this time.

- Timeout improves fault isolation, this is very important factor to avoid failures of one system propagate into another.

- Timeout also helps to manage and use system resources properly, since caller will not wait infinity it's possible to release expensive resources such as DB transactions, network connections etc.

- Timeout is one way to achieve another important design principle called "Fail Fast", this means if a transaction/activity can't complete it should notify or throw a suitable error as early as possible.

Now let's look at how Timeout design pattern is implemented in WSO2 ESB. In WSO2 ESB external systems are represented as "Endpoints", these Endpoints encapsulate access URIs, QoS policies and availability of external systems.

In ESB configuration language <timeout> element is used to configure timeout settings. Most important properties are given below.

duration - This specify the time duration for timeout.
responseAction - This specify what ESB should do to the current message once the timeout is exceeded. There are 2 possible values

discard - simply discard current message.
fault - redirect current message to immediate fault sequence.

As an example during the fault sequence one can persist those messages temporally and try to deliver them once the remote system is alive, WSO2 ESB supports out of the box concept called store-and-forward for this.

Example Timeout Configuration

 <endpoint name="TimeoutEP">  
   <address uri="http://localhost:9764/CalculatorService-war_1.0.0/services/calculator_service/call">  
    <timeout>  
      <duration>200</duration>  
      <responseAction>fault</responseAction>  
    </timeout>  
   </address>  
 </endpoint>

In this sample, we try to call RESTful endpoint available on http://localhost:9764/CalculatorService-war_1.0.0/services/calculator_service/call URL and timeout value is set to 200 ms once the above limit exceed messages will re-route to error handling sequence.

Here I have given a ESB REST API which calls above endpoint. In this sample once the timeout exceeded client will notify with a error message.

 <api name="CalAPI" context="/cal">  
   <resource methods="GET">  
    <inSequence>  
      <send>  
       <endpoint key="TimeoutEP"/>  
      </send>  
    </inSequence>  
    <outSequence>  
      <send/>  
    </outSequence>  
    <faultSequence>  
      <header name="To" action="remove"></header>  
      <property name="RESPONSE" value="true"></property>  
      <property name="NO_ENTITY_BODY" scope="axis2" action="remove"></property>  
      <log level="full"></log>  
      <payloadFactory media-type="xml">  
       <format>  
         <ns:MyResponse xmlns:ns="http://services.samples">  
          <ns:Error>We can't response you at this time, we will reponse through E-mail soon</ns:Error>  
         </ns:MyResponse>  
       </format>  
      </payloadFactory>  
      <send/>  
    </faultSequence>  
   </resource>  
 </api>

Circuit Breaker Pattern

In his book Michael T. Nygard formalized and nicely presented Circuit Breaker pattern. I would recommend to read another excellent writing of Martin Fowler about this pattern.

This is how Fowler introduce Circuit Breaker pattern.

"The basic idea behind the circuit breaker is very simple. You wrap a protected function call in a circuit breaker object, which monitors for failures. Once the failures reach a certain threshold, the circuit breaker trips, and all further calls to the circuit breaker return with an error, without the protected call being made at all. Usually you'll also want some kind of monitor alert if the circuit breaker trips."

[Source - http://martinfowler.com/bliki/CircuitBreaker.html ]

Circuit Breaker pattern define three states.

Closed - Circuit is closed and communication with remote party is possible without any communication issues.
Open - After N times of failures Circuit goes to open state.

For certain time interval system does not try to send messages to remote system further.
Client receive an error message.

Half-Open - After certain time interval system try to send limited number of messages to remote system, if the communication is successful Circuit is reset to Closed state.

Here is a simple state change diagram according to the Circuit Breaker pattern.

WSO2 ESB Endpoint includes feature-rich error handling mechanism that can be used to implement Circuit Breaker pattern. One difference is WSO2 ESB endpoints status names are different from Circuit Breaker paten status names.

Now let's look at an example Endpoint definition, which in fact an improved version of above TimeoutEP.

 <endpoint name="CircuitBreakerEP">  
   <address uri="http://localhost:9764/CalculatorService-war_1.0.0/services/calculator_service/call">  
    <suspendOnFailure>  
      <initialDuration>40000</initialDuration>  
    </suspendOnFailure>  
    <markForSuspension>  
      <errorCodes>101507,101508,101505,101506,101509,101500,101510,101001,101000,101503,101504,101501</errorCodes>  
      <retriesBeforeSuspension>3</retriesBeforeSuspension>  
      <retryDelay>400</retryDelay>  
    </markForSuspension>  
    <timeout>  
      <duration>200</duration>  
      <responseAction>fault</responseAction>  
    </timeout>  
   </address>  
 </endpoint>

Following are the important configuration details of above example.

initialDuration - Once the endpoint reach to 'suspended' state ( 'open' state in Circuit Breaker pattern), it waits for 400 ms to perform next retry.
retriesBeforeSuspension - This is the failure count to move endpoint into 'Suspended' ( 'open' state in Circuit Breaker pattern) state.
retryDelay - This is the delay in between failure calls.

You can use above "CalAPI" to test this endpoint as well.

 <api name="CalAPI" context="/cal">  
   <resource methods="GET">  
    <inSequence>  
      <send>  
       <endpoint key="CircuitBreakerEP"/>  
      </send>  
    </inSequence>  
    <outSequence>  
      <send/>  
    </outSequence>  
    <faultSequence>  
      <header name="To" action="remove"></header>  
      <property name="RESPONSE" value="true"></property>  
      <property name="NO_ENTITY_BODY" scope="axis2" action="remove"></property>  
      <log level="full"></log>  
      <payloadFactory media-type="xml">  
       <format>  
         <ns:MyResponse xmlns:ns="http://services.samples">  
          <ns:Error>We can't response you at this time, we will reponse through E-mail soon</ns:Error>  
         </ns:MyResponse>  
       </format>  
      </payloadFactory>  
      <send/>  
    </faultSequence>  
   </resource>  
 </api>

Internal Implementation

I have included following details to clarify pattern implementation in terms of WSO2 ESB concepts, you may skip this section if you are not interested about internal implementation details.

Following two diagrams illustrate state flow of original Circuit Breaker pattern and WSO2 ESB implementation. Basically WSO2 ESB Endpoint "Active" state is identical to "Closed" state of the pattern and "Open" state is identical to ESB Endpoint "Suspended" state. One main difference is, in WSO2 ESB there is no separate state as "Half-Open", "Suspend" state encapsulates logics belong to both "Open" and "Half-Open" states.

Another difference is, in WSO2 ESB after 1st failure, Endpoint is moved into "Timeout" state and successive attempts will be executed from "Timeout" state.

Circuit Breaker pattern flow.

WSO2 ESB internal flow

Following are some advanced configurations that can be used to achieve more flexible and more complex implementations of Circuit Breaker pattern.

errorCodes - You can define what the failure code that Circuit Breaker should act on. Complete list of supported status codes can be found here.
progressionFactor, maximumDuration - By combining with "retriesBeforeSuspension" property you can form more complex and dynamic retry behaviours, for more details refer here.

NOTE : - In WSO2 API Manger, API-Gateway is a lightweight ESB node hence above discussed "Timeout" and "Circuit Breaker" pattern implementations can be seamlessly used in WSO2 API Manger as well.

JavaEE WebProfile support in WSO2 AS

2014-08-04T10:23:00.003+05:30

Some of the regular questions we receive from WSO2 Application Server users are abut JavaEE WebProfile support. Does WSO2 AS support for WebProfile ? If so what is the possible time line ? Any plans to support EJB ? are some of the very common queries.

Instead of answering to above questions again and again we thought to explain our strategy on both JavaEE and JavaEE-WebProfile, implementation details and expected time line through a detailed white paper. Recently we have finished this paper and already published on our website, here is the link. In summery WSO2 AS will support for JavaEE WebProfile with it's 6.0 version.

Following diagram provides you an idea about JavaEE specifications supported in WSO2 AS 5.2.1 which is the latest released version. Though WSO2 AS 5.2.1version is not fully supported for WebProfile it support for number of specifications defined under both WebProfile and Full profile.

( Here all dark coloured specifications are supported in AS 5.2.1 version and light coloured specifications are not supported in AS 5.2.1)

Link to the white paper

Additionally WSO2 AS use number of certified and proved open source frameworks to support JavaEE WebProfile, most of them from Apache.

Secure Java WebSocket endpoints

2014-08-03T20:43:00.001+05:30

During one of my previous post I have explained few security patterns that can be used with Java WebSocket applications and how to call them from client side applications including browser based and rich agent based clients. In this post I explain how to secure server side WebSocket endpoints easily, in fact if you are already familiar with security model defined by the Java Servlet specification there is nothing new, you could use same security model for WebSocket server endpoints as well. Let's take an example and discuss, consider following use case.

Endpoint URL to secure - /securewebsocket
Transport level security - HTTPS
Allow roles - admin
Authentication metod - Basic

Here in this use case we want to secure a WebSocket endpoint deployed on "/securewebsocket" URL. Users with only "admin" role can establish WebSocket connection and they should use SSL for transport level security, additionally server will use HTTP BasicAuth to authenticate users during the handshake.

We can fulfil above security requirement easily by adding following entries into web.xml file.

   <security-constraint>  
       <display-name>Secure WebSocket Endpoint</display-name>  
       <web-resource-collection>  
          <web-resource-name>Secure WebSocket Endpoint</web-resource-name>  
          <url-pattern>/securewebsocket</url-pattern>  
          <http-method>GET</http-method>  
       </web-resource-collection>  
       <auth-constraint>  
         <role-name>admin</role-name>  
       </auth-constraint>  
       <user-data-constraint>  
          <transport-guarantee>CONFIDENTIAL</transport-guarantee>  
       </user-data-constraint>  
   </security-constraint>                        
   <login-config>  
     <auth-method>BASIC</auth-method>  
     <realm-name>basic</realm-name>  
   </login-config>

Now let's let's look at what are the various we could use for authentication and authorization.

Authentication options

1. BASIC

This is the basic authentication schema where client sends set of user name and password as a encoded string along with a HTTP header. In case of browser based clients browser pop-up a dialog to enter user name and password.

2. FORM

In form based authentication application developers create a HTML login page to send user name and password. This approach is similar to "Basic" but flexible to have customized login page.

3. DIGEST

Much secure than above two options, it specially applies a hash function to the password before sending to he server.

4. CLIENT-CERT

This also a better authentication schema where client is authenticated using client's digital certificate.

Authorization options

1. NONE

This indicate server should accept any connection including unprotected connections.

2. INTEGRAL

This ensures that the data be sent between client and server in such a way that it cannot be changed in transit.

3. CONFIDENTIAL

During the data transmissions this ensures other entities can't observer contents of the transmission.

In practice web servers treat the CONFIDENTIAL and INTEGRAL transport guarantee values identical.

In both CONFIDENTIAL and INTEGRAL options clients should use secure WebSocket (wss://) protocol.

Support multiple versions of Axis2 in WSO2 AS

2014-07-27T11:25:00.000+05:30

Some users of WSO2 AS tend to think that they don't have freedom to use what ever the Axis2 version they want instead have to stick to the default version supported by WSO2 AS distribution, but recent versions of WSO2 AS specially after AS 5.1.0 there is no such limitation. In this post I discuss how you could support multiple versions of Axis2 within WSO2 AS together with possible deployment options.

I have described each and every options in detail below and here is the summery.

Axis2 services as standalone WAR applications.
Axis2 services as standalone WAR applications using AS default Axis2 runtime environment.
Axis2 services as WAR applications using custom Axis2 runtime environment.
Axis2 services as AAR applications using AS default Axis2 runtime environment.
Axis2 services as AAR applications using custom Axis2 runtime environment.

Use case

WSO2 AS 5.2.1 version is distributed with Axis2 1..6.1 plus some custom patches. Assume one wants to use Apache Axis2 1.7.0 on WSO2 AS 5.2.1.

Note - Axis2 1.7.0 yet to be released hence I use Axis2 1.7.0-SNAPSHOT version for this post but what ever the details I cover here are common for any Axis2 version.

Note - In case if you use WSO2 AS 5.2.1, 5.2.0 or 5.1.0 versions you need to do following additional steps.

a. Open AS-HOME/repository/conf/tomcat/webapp-classloading-environments.xml file.

b. Find <DelegatedEnvironment> with name "Carbon", replace it with following configuration.

 <DelegatedEnvironment>  
       <Name>Carbon</Name>  
       <DelegatedPackages>*,!org.springframework.*,   
        !org.apache.axis2.*, !antlr.*,!org.aopalliance.*,   
        !org.apache.james.*, !org.apache.axiom.*,   
        !org.apache.bcel.*, !org.apache.commons.*,   
        !com.google.gson.*, !org.apache.http.*,   
        !org.apache.neethi.*, !org.apache.woden.*  
 </DelegatedPackages>


 </DelegatedEnvironment>  
     <DelegatedEnvironment>  
       <Name>Axis2</Name>  
       <DelegatedPackages>*</DelegatedPackages>  
 </DelegatedEnvironment>

1. Axis2 services as standalone WAR applications.

In fact here I don't need to mention any thing special you can think Axis2 as just another web framework and develop your service and deploy as a WAR file just like you develop any other web application such Spring, Apache Wicket, Apache Structs etc.

If you are a novice to Axis2 you can easily start with Axis2 web application Maven archetype, I have covered details about this Maven archetype here. Also you can find complete working sample from here.

Once you build this sample application you can deploy to WSO2 AS as a web application. Once you done that it is possible to access WSDL through following url.

 http://localhost:9763/axis2-war-standalone/HelloService?wsdl

2. Axis2 services as standalone WAR applications using AS default Axis2 runtime environment.

If you open and inspect WEB-INF/lib directory of above sample you can find number of Axis2 jar files and their dependencies. Size of the WAR file can be vary from 8MB to 10 MB or so on. This is ok if you deploy one or two services but in case if you deploy large number of services then packaging dependencies with each and every WAR file may not convenient and can be a extra overhead too.

The solution for this is to use default Axis2 runtime environment or add a new custom runtime environment (CRE) for Axis2. Under this point I cover first option and next point cover 2nd option by creating a custom CRE. In both approaches you don't need to duplicate any Axis2 or dependent Jar file inside WEB-INF/lib directory you have to include your application specific Jar files only.

Further in both approaches we use webapp-classloading.xml file to define runtime environment for the service. webapp-classloading.xml file is WSO2 AS specific application descriptor and it is expected to present on META-INF directory in case of a runtime environment customisation like this.

You can find complete working example for this option from here. Download, build and deploy this service then you can access to WSDL file in following URL.

 http://localhost:9763/axis2-war-dre/HelloService?wsdl

If you open webapp-classloading.xml file you should able to see following entry.

 <Classloading xmlns="http://wso2.org/projects/as/classloading">  
   <ParentFirst>false</ParentFirst>  
   <Environments>Axis2</Environments>  
 </Classloading>

Please note in this example we consumed default Axis2 version shipped with WSO2 AS.

3. Axis2 services as WAR applications using custom Axis2 runtime environment.

As I explained earlier here also we don't package any Axis2 related Jar file inside the service. The main difference from previous one is here we create a new CRE, which means you can bring any Axis2 version you want and share with your service just like you share default Axis2 runtime. Following are the required steps.

a. Download required Axis2 version from Apache Axis2 web site here. (Let's say Axis2-1.7.0-SNAPSHOT.zip )

b. Create a new directory called "axis217" under "AS-HOME/lib/runtimes" . We generally use "AS-HOME/lib/runtimes" directory to keep Jar files belong to custom runtimes.

c. Extract downloaded Axis2-1.7.0-SNAPSHOT.zip file and copy all jar files available on "Axis2-1.7.0-SNAPSHOT/lib" directory to above created AS-HOME/lib/runtimes/axis217" directory.

d. Open AS-HOME/repository/conf/tomcat/webapp-classloading-environments.xml file and add following entry which define a new CRE for Axis2 1.7.0-SNAPSHOT version.

   <ExclusiveEnvironments>  
     <ExclusiveEnvironment>  
       <Name>Axis217</Name>  
       <Classpath>  
         ${carbon.home}/lib/runtimes/axis217/*.jar;  
         ${carbon.home}/lib/runtimes/axis217/  
       </Classpath>  
     </ExclusiveEnvironment>  
   </ExclusiveEnvironments>

e. Download complete example code from here.

f. Build and deploy to WSO2 AS, you can access WSDL file through following url.


 http://localhost:9763/axis2-war-cre/HelloService?wsdl

Like in previous example if you open the webapp-classloading.xml file under META-INF directory of the sample service you should able to see following entry. This is how we refer "Axis217" CRE we just created inside the web service ( this allows applications/services to load required Axis2 dependencies from "Axis217" CRE ).

 <Classloading xmlns="http://wso2.org/projects/as/classloading">  
     <ParentFirst>false</ParentFirst>  
     <Environments>Axis217</Environments>  
 </Classloading>

4. Axis2 services as AAR applications using AS default Axis2 runtime environment.

So far for above examples we used WAR packaging but now let's look at how you could develop Axis2 service as a AAR archive and deploy.

In this AAR option first we have to deploy axis2.war file then deploy .AAR file through the admin interface provided by the Axis2. Here axis2.war application act as container within the WSO2 AS. For this approach also we could use default Axis2 runtime, please refer following procedure.

a. Download web archive version (WAR) of Axis2 from Apache Axis2 web site.

b. Extract axis2.war file and perform following modifications.

c. As we will use default Axis2 version available with WSO2 AS remove "lib" directory from extracted axis2 directory.

d. In order to use default Axis2 runtime, create a file called webapp-classloading.xml with following content.

 <Classloading xmlns="http://wso2.org/projects/as/classloading">  
    <ParentFirst>false</ParentFirst>  
    <Environments>Axis2</Environments>  
 </Classloading>

e. re-archive Axis2 directory as axis2.war and deploy into WSO2 AS.

Now you should able to see Axis2 admin console through following url which can be used to upload your AAR services.


 http://localhost:9763/axis2

Here is WSDL url for default version sample.


 http://localhost:9763/axis2/services/Version?wsdl

Note - If you use WSO2 AS 5.2.1 or previous version it may possible to get few JSP rendering issues on above mentioned Axis2 admin console but those are not affect to any service invocations.

5. Deploy web service as AAR file using custom Axis2 runtime environment.

This approach is also similar to previous one but instead of default Axis2 runtime we use Axis2 dependencies available with axis2.war distribution. Please refer following procedure.

a. Download web archive version (WAR) of Axis2 from Apache Axis2 web site.

b. Deploy axis2.war file into WSO2 AS.

Now you should able to see Axis2 admin console through following url which can be used to upload your AAR services.



 http://localhost:9763/axis2

Here is WSDL url for default version sample.


 http://localhost:9763/axis2/services/Version?wsdl

Note - If you use WSO2 AS 5.2.1 or previous version it may possible to get few JSP rendering issues on above mentioned Axis2 admin console but those are not affect to any service invocations.

WebSocket security patterns

2014-07-24T23:21:00.005+05:30

WebSocket protocol introduced "wss" prefix to define secure web socket connections that is for transport level security (TLS). But it does not define any authentication or Authorization mechanism, instead it is possible to reuse existing HTTP based authentication/Authorization mechanisms during the handshake phase.

Here I discuss two security patterns that can be used to connect secure WebSocket endpoint from a client. Assume WebSocket endpoint is secured with HTTP BasicAuth while HTTP/SSL used for transport level security.

1. ) Browser based clients

For web browser based clients most popular choice is to use JavaScript API for WebSocket but this API does not provide any approach to send "Authorization" or any other headers along with the handshake request. Following pattern can be used to overcome above issue.

The technique we use here is secure the web page where we run JS WebSocket client through BasicAuth security. Please refer the message flow.

1. User access the secure page through a web browser through HTTPS.

2. Since the page is secured web server return 401 status code.

3. Browser challenges user to enter valid user name and password then send them as a encoded value with "Authorization" header.

4. If credentials are correct server returns secure page.

5. JS WebSocket client on secured page send handshake request to the secured remote WebSocket endpoint through WSS protocol. Due to previous interaction with the same page browser persist and send authorization details along with the handshake request.

6. Since handshake request transmit through HTTPS it fulfil the both requirements, BasicAuth and TLS. Server returns handshake response back to the client.

7. Now it's possible to establish WebSocket connection among above two parties.

2.) Agent based client (Non browser based)

For agent based clients you could use a WebSocket framework which facilitate to add authentication headers and also to configure SSL configuration such as key store. Following diagram illustrate a pattern which we be can used with agents based clients.

1. Using the client side API of the WebScoket framework create a handshake request.

2. Set Authorization header and other required key store information for TLS.

3. Send handshake request through WebSocket framework API.

4. Server receive handshake and Authorization header through HTTPS . Validate the header and if valid send the handshake response back to the client.

5. Now it's possible to establish WebSocket connection among above two parties.

As an example Java API for WebSocket allows to send custom headers along with handshake request by writing a custom Configurator which extend from ClientEndpointConfig.Configurator.

Here is such example.

 public class ClientEndpointConfigurator extends  
           ClientEndpointConfig.Configurator {  
      @Override  
      public void beforeRequest(Map<String, List<String>> headers) {  
       String auth = "Basic " +   
          Base64Utils.encodeToString("user:pass".getBytes(Charset.forName("UTF-8")), false);  
       headers.put("Authorization", Arrays.asList(new String[]{auth }));  
       super.beforeRequest(headers);  
      }  
 }

Once you wrote this ClientEndpointConfigurator you can refer it from Client endpoint using 'ClientEndpoint' annotation as follows.

@ClientEndpoint(configurator=ClientEndpointConfigurator.class)

public class EchoClientEndpoint {

        ........................

By the way there is no portable API to define SSL configurations required for TLS but some framework such as Tyrus provides proprietary APIs . As an example refer how this facilitated in Tyrus through ClientManager API.

How to manage WSDL binding on ESB proxy services

2013-10-12T22:26:00.000+05:30

In WSO2 ESB if you associate a backend WSDL file when creating a proxy service it will generate an identical WSDL for the proxy service except WSDL port address's location attribute. Value of the WSDL port address's location attribute is modified according to ESB host name. By default ESB generate WSDL for proxy services with following three bindings.

SOAP 1.1 Binding
SOAP 1.2 Binding
HTTP Binding

But there are some situations that backend service only support one or two of above bindings not all three, specially most of the JAX-WS implementations such as CXF only generate SOAP 1.1 binding. In such case if you send a message to un-supported binding through the ESB you will get an error. To avoid such situations you could use following ESB parameters to control WSDL generation.

  <parameter name="disableSOAP11">true</parameter>

This will avoid generation of SOAP 1.1 binding

   <parameter name="disableSOAP12">true</parameter>

This will avoid generation of SOAP 1.2 binding

 <parameter name="disableREST">true</parameter>

This will avoid generation of SOAP 1.2 binding

Please note above setting can be used with Apache Synapse as well.

WSO2 ESB proxy services for JAX-WS backends

2013-08-04T20:32:00.003+05:30

Proxy service concept is one of the main useful component in WSO2 ESB. There are number of variant formats available to create proxy services such as pass-through proxy , WSDL based proxy, security proxy etc. When creating a proxy service it is possible to assign a WSDL file to describe the service this simplify service invocation from client side, usually client side tools are capable of understanding WSDL file associate with the proxy service so that they can generate client codes or can generate expected sample messages . As an example once the WSDL given SoapUI can generate expected sample messages. When a message is reach to the ESB and if it dispatch to a WSDL based proxy service then it's required to dispatch the message to a operation within the service in order to redirect messages to backend service, in this case dispatching to the service level only (without dispatching to a operation ) is not sufficient. But if you don't associate WSDL file during the proxy service creation then to redirect message to the backend service-level dispatching is sufficient.

In users point of view there are some use cases that operation level dispatching is useful.

1. Apply QoS features such as throttling, security per operation level instead of service level.

2. Associate WS-Policy per operation instead of per service.

Both service and operation dispatchers use information available with incoming messages to find correct service/operation, those information can be transport level properties or message level properties some of the given below.

Request URI
SOAPAction HTTP header
WS-Addressing headers
QName of the first child under SOAP Body element.

Here first it try to dispatch messages based on transport level properties and if it fails it try to perform dispatching based on message properties such as QName of the root element. Please note if it's possible to complete dispatching only based on transport level details that improves overall performance of the invocation because there is no need to build the message to find dispatching information. But in practical situations due to various reasons it is not possible to complete dispatching only using transport level details once such common use case is described below.

Use case -1

In JAX-WS specification it's not mandatory to generate unique SOAPAction property per each operation unless developer specifically annotate the SOAPAction with SEI, by default for JAX-WS services it generate "" as the expected value for all operation. Assume you create a WSDL associated proxy service for JAX-WS service and client send following data to the proxy service.

Valid SOAP message
Request URI up to service level ( e.h http://host/proxyServiceName )
HTTP SOAPAction =""

In above case using request URI it is possible to find the correct service but in order to find the correct operation it's required to build the message and look the QName of the first child under SOAPBoday this can affect to overall performance but still successful service invocation is possible.

Starting from 4.6.0 version WSO2 ESB uses new HTTP transport called pass-through which provides very high performance level, this blog post provides insights on pass-through transport but in simple terms it uses shared buffer and avoid message building at all. Now this new transport mechanism effect to above described use case -1 because now message building is not possible and hence operation dispatching is fail and messages will not process further. We have addressed this limitation in upcoming ESB 4.8.0 version, before I describe the solution let me introduce some of the workarounds which can be used with 4.60 and 4.7.0 versions.

For ESB 4.6.0/4.7.0

1.) Append operation name at the end of the Request URI so that request URI can be used to dispatch both service and operation.

  http://host/proxyServiceName/OperationName

2. If it's possible modify backend JAX-WS SEI so that each operation having unique SOAPAction value.

 @WebMethod(action="XXXX")

3. Move back to NHTTP transport instead of Pass-through in NHTTP on-demand message building is possible .

This is what you have on ESB 4.6.0

 <transportSender name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpSender">  
   <parameter name="non-blocking" locked="false">true</parameter>  
 </transportSender>  
 <transportReceiver name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpListener">  
   <parameter name="port" locked="false">8280</parameter>  
   <parameter name="non-blocking" locked="false">true</parameter>      
   <parameter name="httpGetProcessor" locked="false">org.wso2.carbon.transport.nhttp.api.PassThroughNHttpGetProcessor</parameter>     
 </transportReceiver>

Replace above code using following.

 <transportReceiver name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener">  
   <parameter name="port" locked="false">8280</parameter>  
   <parameter name="non-blocking" locked="false">true</parameter>  
   <parameter name="httpGetProcessor" locked="false">org.wso2.carbon.transport.nhttp.api.NHttpGetProcessor</parameter>  
   <parameter name="disableRestServiceDispatching" locked="false">true</parameter>  
 </transportReceiver>  
 <transportSender name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSender">  
   <parameter name="non-blocking" locked="false">true</parameter>  
 </transportSender>

Following two diagrams illustrate runtime processing when both service and operation dispatching are required and only service dispatching required scenarios.

For ESB 4.8.0 or any future versions

Now let me discuss the improvements we have done in ESB 4.8.0. Starting from this version users have the control to specify whether the proxy service should expect operation dispatching or not, in situation like use case -1 now users can disable operation level dispatching and still possible to use high-speed pass-through transport. There is a new parameter introduced called "disableOperationValidation" to control operation dispatching on proxy service, please refer the following sample.

 <proxy name="JAXWSServiceProxy">   
   <target>   
   <outSequence>   
    <send/>   
   </outSequence>   
   <endpoint>   
    <address uri="XXXXX"/>   
   </endpoint>   
   </target>   
   <publishWSDL uri="XXXX">   
   <parameter name="disableOperationValidation" locked="false">true</parameter>   
  </proxy>

Now let's discuss another use case, this one is identical to use case 1 but now we need to throttle only one operation in other words now we need to perform operation level dispatching . It's clear in this case we need to build the message to find correct operation so the one solution would be to move back to NHTTP transport but with 4.8.0 release there is another solution introduced to build messages only if necessary, there is a new dispatcher introduced called SynapseSOAPMessageBodyBasedDispatcher which can build messages if it's required. Using following steps you can enable SynapseSOAPMessageBodyBasedDispatcher to the ESB configuration.

1. Open a axis2.xml file

2. Locate the following entry.

       <handler class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher" name="SOAPMessageBodyBasedDispatcher"/>

3. Replace it using SynapseSOAPMessageBodyBasedDispatcher as follows.

       <handler class="org.apache.synapse.core.axis2.SynapseSOAPMessageBodyBasedDispatcher" name="SOAPMessageBodyBasedDispatcher"/>

Test all four OAuth2 grant types on WSO2 IS , WSO2 API Manager

2013-08-02T15:05:00.004+05:30

This topic is not something new as WSO2 IS supported for both OAuth 1.0 and OAuth 2.0 specifications for sometime , instead I'm writing this post to introduce one of OAuth2 sample application. In fact I developed this sample to understand OAuth 2.0 specification myself and thought to share it publicly so that someone else can used it to understand OAuth2 support on WSO2 platform. You can use this sample to test following four grant types on WSO2 IS or WSO2 APIM.

Athorization Code
Implicit
Resource Owner
Client Credentials

You can find all source codes for this sample from here https://github.com/sagaragu/OAuthWebapp

In first step you need to register a OAuth2 application either on WSO2 IS or WSO2 APIM, this step is very straightforward but if your not much clear you can follow this blog post by Prabath. Additionally same blog post introduce and explain another useful OAuth2 sample called "OAuth2 Playground2 " which you also can try, in fact before develop my sample I also use Playground2 sample to understand OAuth2 basics.

Once you register a OAuth2 application you can deploy the sample web app on any application server such as WSO2 AS or you could easily use embedded Maven Jetty plug in. Once you start the application server you can see following page and it's straightforward to test each grant type by clicking URL on index page.

Steps required to test "Athorization Code" are given below.

WSO2 ESB : Set WS-Security UT user names dynamically

2013-07-31T20:13:00.000+05:30

Proxy services deployed on WSO2 ESB can be used to cater various security requirements, among them following two patterns are very common.

(1) Expose an insecure backend service as a secured service using proxy services.

This can be done very easily by pointing to a WS - Security Policy file within the proxy configuration. In following example UTOverTransport.xml file specify the expected security configuration. ESB admin console provides a guided wizard for this use case.

 <proxy name="SampleProxy">  
   <target>  
    <outSequence>  
      <send/>  
    </outSequence>  
    <endpoint>  
      <address uri="http://www.w3schools.com/webservices/tempconvert.asmx"/>  
    </endpoint>  
   </target>  
   <enableSec/>  
   <policy key="conf:/repository/axis2/service-groups/SampleProxy/services/SampleProxy/policies/UTOverTransport"/>  
 </proxy>

(2) Expose secured backend service as a insecure service so that security tokens set by the ESB.

This also can be implemented easily by pointing to a WS - Security Policy file as a QoS option at the proxy Endpoint so that ESB add required security tokens to the out-going message. I have given such example with a policy file below.

 <proxy name="HelloProxy">  
   <target>  
    <outSequence>  
      <send/>      
    </outSequence>  
    <endpoint>  
      <address uri="https://localhost:9445/services/HelloService">  
       <enableSec policy="gov:/policy/UT-Policy.xml"/>  
      </address>  
    </endpoint>  
   </target>  
 </proxy>

In above proxy configuration security polices is defined in the UT-Policy.xml which is stored in embedded Registry.

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UTOverTransport">  
     <wsp:ExactlyOne>  
       <wsp:All>  
         <sp:TransportBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">  
           <wsp:Policy>  
             <sp:TransportToken>  
               <wsp:Policy>  
                 <sp:HttpsToken RequireClientCertificate="false"/>  
               </wsp:Policy>  
             </sp:TransportToken>  
             <sp:AlgorithmSuite>  
               <wsp:Policy>  
                 <sp:Basic256/>  
               </wsp:Policy>  
             </sp:AlgorithmSuite>  
             <sp:Layout>  
               <wsp:Policy>  
                 <sp:Lax/>  
               </wsp:Policy>  
             </sp:Layout>  
             <sp:IncludeTimestamp/>  
           </wsp:Policy>  
         </sp:TransportBinding>  
         <sp:SignedSupportingTokens xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">  
           <wsp:Policy>  
             <sp:UsernameToken sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient"/>  
           </wsp:Policy>  
         </sp:SignedSupportingTokens>  
         <ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">  
          <ramp:user>sagara</ramp:user>  
          <ramp:passwordCallbackClass>org.wso2.security.sample.PWCBHandler</ramp:passwordCallbackClass>  
         </ramp:RampartConfig>  
       </wsp:All>  
     </wsp:ExactlyOne>  
   </wsp:Policy>

If you look at above policy file carefully you can observe the user name is hard coded as <ramp:user> and we have defined another entry called <ramp:passwordCallbackClass>, during the runtime above user name set as the user name of UT token while PWCBHandler set the UT password related to given user name. Developers can access the user name within the PWCBHandler class and can look-up password from any convenient method such loading password from a encrypted property file or using database call etc.

One limitation of above approach is there is no way to set user name dynamically it has to be hard coded within <ramp:user> element. But there are number of use cases where it's required to set different user names dynamically with each message dispatching to the proxy service. One such use case within the WSO2 platform is OAuth2 to WS-Secuty security switching using WSO2 API Manger and WSO2 ESB.

AS an example assume we have a backend service which expect WS-Security UT with in-coming messages, now let's say we have created a API in WSO2 API Manger for above backend service. The challenge with this use case is API is secured with OAuth2 Access Token but we need to extract user name and have to set it as UT tokens before forward messages to the backend. One possible solution for this case is given below.

User invoke the API by providing a OAuth2 access tokens.
After successful authentication forward messages to the ESB along with JWT token where JWT token contains authenticated user name.
In ESB proxy service process the JWT token and add user name dynamically to UT token

Here the real challenge is how we could dynamically specify user name ? for this we could use another extension point called "RampartConfigCallbackHandler" together with a Axis2 Handler.

Step -1

Process JWT token from incoming message and set it as a property on current MessageContext. For demonstration I created a sample Handler called ExtractUserNameHandler as follows.

 public class ExtractUserNameHandler extends AbstractHandler {  
   public InvocationResponse invoke(MessageContext messageContext)  
       throws AxisFault {  
     String userName = null;  
     Map<String, String> headerMap = (Map<String, String>) messageContext  
         .getProperty(org.apache.axis2.context.MessageContext.TRANSPORT_HEADERS);  
     if(headerMap != null){    
     if (headerMap.containsKey("X-JWT-Assertion")) {  
       userName = getUserNameFromJWT(headerMap.get("X-JWT-Assertion"));  
     }  
     if(userName != null){  
       addToMessageContext(messageContext, userName);        
     }  
     }  
     return InvocationResponse.CONTINUE;  
   }

 protected void addToMessageContext(MessageContext messageContext, String userName) {  
     Map<String, String> rampConfigCBProperties = new Hashtable<String, String>();  
     rampConfigCBProperties.put("user_name", userName);  
     messageContext.setProperty("rampartConfigCallbackProperties",  
         rampConfigCBProperties);  
   }

 protected String getUserNameFromJWT(String jwtToken) {  
     String[] tokenParts = jwtToken.split("\\.");  
     String user = null;  
     if (tokenParts != null && tokenParts.length == 3) {  
       byte[] jsonClaims = Base64.decode(tokenParts[1]);  
       JsonParser parser = new JsonParser();  
       JsonElement element = parser  
           .parse(new JsonReader(new InputStreamReader(  
               new ByteArrayInputStream(jsonClaims))));  
       user = element.getAsJsonObject()  
           .get("http://wso2.org/claims/enduser").getAsString();  
       System.out.println("user name : " + user);  
       return user;  
     }  
     return null;  
   }  
 }

Step -2

Now we can implement RampartConfigCallbackHandler interface and possible to read the value from MessageContext so that we can dynamically add the user name to the security configuration.

 public class RampartConfigCallbackHandlerImpl implements  
     RampartConfigCallbackHandler {

public void update(RampartConfig config) {  
     Map<String, String> propertyMap = config.getPropertyMap();  
     if (propertyMap != null && propertyMap.containsKey("user_name")) {  
       System.out.println(" adding user name : "+ propertyMap.get("user_name"));  
       config.setUser(propertyMap.get("user_name"));  
     }  
     config.setPwCbClass("sample.PWCBHandler");  
   }  
 }

Step -3

Still we need to provide a WS-Policy file which specify the above created RampartConfigCallbackHandlerImpl class.

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"  
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"  
   wsu:Id="UTOverTransport">  
   <wsp:ExactlyOne>  
     <wsp:All>  
       <sp:TransportBinding  
         xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">  
         <wsp:Policy>  
           <sp:TransportToken>  
             <wsp:Policy>  
               <sp:HttpsToken RequireClientCertificate="false" />  
             </wsp:Policy>  
           </sp:TransportToken>  
           <sp:AlgorithmSuite>  
             <wsp:Policy>  
               <sp:Basic256 />  
             </wsp:Policy>  
           </sp:AlgorithmSuite>  
           <sp:Layout>  
             <wsp:Policy>  
               <sp:Lax />  
             </wsp:Policy>  
           </sp:Layout>  
           <sp:IncludeTimestamp />  
         </wsp:Policy>  
       </sp:TransportBinding>  
       <sp:SignedSupportingTokens  
         xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">  
         <wsp:Policy>  
           <sp:UsernameToken  
             sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">              
           </sp:UsernameToken>  
         </wsp:Policy>  
       </sp:SignedSupportingTokens>  
       <ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">  
         <ramp:rampartConfigCallbackClass>sample.RampartConfigCallbackHandlerImpl  
         </ramp:rampartConfigCallbackClass>  
       </ramp:RampartConfig>  
     </wsp:All>  
   </wsp:ExactlyOne>  
 </wsp:Policy>

Setting HTTP basic security in Maven Jetty plug-in

2013-01-25T21:56:00.000+05:30

Recently I had to test HTTP basic security for one of my web application project, just to save my time I didn't want to use any standalone server during development instead I tried to configure Maven Jetty plug-in to support HTTP basic security. Here I have given the procedure which I followed.

1.) Configure Maven Jetty plugin in project pom.xml file.

It's required to add a UserRealm under plug-in configuration section. Jetty provides number of in-built UserRealms, here I used HashUserRealm for simplicity which use in-memory HashMaps to store users and roles.

 <plugin>  
                     <groupId>org.mortbay.jetty</groupId>  
                     <artifactId>maven-jetty-plugin</artifactId>  
                     <configuration>  
                          <scanIntervalSeconds>3</scanIntervalSeconds>  
                          <webAppConfig>  
                               <contextPath>/</contextPath>  
                          </webAppConfig>  
                          <userRealms>  
                               <userRealm implementation="org.mortbay.jetty.security.HashUserRealm">  
                                    <name>basic security</name>  
                                    <config>jetty-users.properties</config>  
                               </userRealm>  
                          </userRealms>  
                     </configuration>  
                </plugin>  
           </plugins>

Then add a property file called jetty-users.properties which contains user names, passwords and user roles.

 sagara=sagara,ADMIN

2.) Configure web.xml file of the web application.

In this example we allow users with ADMIN role to access any URL within the application.

 <security-constraint>  
           <display-name>authorizedUsers</display-name>  
           <web-resource-collection>  
                <web-resource-name>ALL URLs</web-resource-name>  
                <url-pattern>/*</url-pattern>  
           </web-resource-collection>  
           <auth-constraint>  
                <role-name>ADMIN</role-name>  
           </auth-constraint>  
      </security-constraint>  
      <login-config>  
           <auth-method>BASIC</auth-method>  
           <realm-name>basic security</realm-name>  
      </login-config>  
      <security-role>  
           <description>administrator access</description>  
           <role-name>ADMIN</role-name>  
      </security-role>

Release of Axis2 1.6.2 and Sandesha2 1.6.2 , Rampart 1.6.2

2012-05-04T10:16:00.003+05:30

The Apache Axis2 team is pleased to announce the general availability of the following releases:

Axis2 1.6.2
Sandesha2 1.6.2
Rampart 1.6.2

Apache Axis2 is a complete re-design and re-write of the widely used Apache Axis engine and is a more efficient, more scalable, more
modular and more XML-oriented Web services framework. It is carefully designed to support the easy addition of plug-in "modules" that extend
its functionality for features such as security and reliability.

Apache Rampart is an Axis2 module that implements the specifications in the WS-Security stack.

Apache Sandesha2 provides WS-ReliableMessaging support for Axis2.

Axis2 1.6.2 is a maintenance release that contains more than 45 fixes.

Rampart 1.6.2 is a maintenance release containing number of bug fixes and compatible with the Axis2 1.6.2 release.

Sandesha2 1.6.2 is a maintenance release that is compatible with the Axis2 1.6.2 release.

The new versions are available for download at the following locations:

http://axis.apache.org/axis2/java/core/download.cgi
http://axis.apache.org/axis2/java/rampart/download/1.6.2/download.cgi
http://axis.apache.org/axis2/java/sandesha/download.cgi

As always, we welcome any and all feedback at:

java-dev@axis.apache.org - for developer-related questions/concerns
java-user@axis.apache.org - for general questions, usage, etc.

NOTE - Axis2 1.6.2 compatible with Axis2 Transports 1.0.0 version

Code generation and WSDL exposed over HTTPS

2012-05-03T18:50:00.000+05:30

In one of my previous post I explained how to use WSDL2JAVA tool behind a proxy together with basic authentication. Another such useful scenario is code generation for a WSDL which exposed over HTTPS protocol. In this case we have to provide key store details to the WSDL2JAVA tool. Basically it expect following two Java system properties.

 javax.net.ssl.trustStore  
 javax.net.ssl.trustStorePassword

Once you know those properties you can use WSDL2JAVA tool as follows.

 wsdl2java.sh -uri https://localhost:8443/services/SimpleService?wsdl -Djavax.net.ssl.trustStore=path/keystorename.keystore -Djavax.net.ssl.trustStorePassword=keypassword

How easy to test your web service over HTTPS

2012-05-02T15:57:00.002+05:30

I have seen many times people having issues with testing web services over HTTPS. This is not an unexpected behavior because number of improvements have been introduced from Axis2 1.5 release for HTTPS transport. With older versions it is possible to use HTTPS transport with Simple HTTPServer and some people already familiar with it too, but recent Axis2 releases no longer support for this option and it is compulsory to use Servlet transport in order to enable HTTPS.

Above modifications doesn't effect much on production systems because it's always recommend to use an Application server for production systems. When it come to development stage this changes required to use a Servlet container to test HTTPS services, Apache Tomcat is one of the good choice for this.

In this post I will discuss how to use Maven Jetty Plug-in to test Axis2 HTTPS transport very easily, all you need is to follow few steps that I have given below.

Step -1 Configure Axis2 for HTTPS transport.

It is required to define AxisServletListener in your axis2.xml for HTTPS transport, in case if you want to use both HTTP ad HTTPS it is possible to define AxisServletListener as two entries with two ports this guide provide more details about this. If you don't have axis2.xml file copy it from binary distribution and replace existing " transportReceiver " with following entries.

  <transportReceiver name="http"  
     class="org.apache.axis2.transport.http.AxisServletListener">  
     <parameter name="port">8080</parameter>  
   </transportReceiver>  
   <transportReceiver name="https"  
     class="org.apache.axis2.transport.http.AxisServletListener">  
     <parameter name="port">8443</parameter>  
   </transportReceiver>

Step - 2 Generate KeyStore.

Usually this is kind of a time wasting task but fortunately you can use keytool-maven-plugin to auto-generate keystore in each run. The only required step is add following entries into your POM file and it will save your time a lot.

       <plugin>  
         <groupId>org.codehaus.mojo</groupId>  
         <artifactId>keytool-maven-plugin</artifactId>  
         <executions>  
           <execution>  
             <phase>generate-resources</phase>  
             <id>clean</id>  
             <goals>  
               <goal>clean</goal>  
             </goals>  
           </execution>  
           <execution>  
             <phase>generate-resources</phase>  
             <id>genkey</id>  
             <goals>  
               <goal>genkey</goal>  
             </goals>  
           </execution>  
         </executions>  
         <configuration>  
           <keystore>${project.build.directory}/jetty-ssl.keystore</keystore>  
           <dname>cn=localhost</dname>  
           <keypass>axis2key</keypass>  
           <storepass>axis2key</storepass>  
           <alias>axis2key</alias>  
           <keyalg>RSA</keyalg>  
         </configuration>  
       </plugin>

Spacial Note - Above approach is not an replacement for production server configurations . It is highly recommend to follow standard procedures to configure production servers for HTTPS.

Step - 3 Configure and Run the service.

Now you need to add SSL Connectors for the Jetty configuration by adding following entries.

  <plugin>  
         <groupId>org.mortbay.jetty</groupId>  
         <artifactId>maven-jetty-plugin</artifactId>  
         <configuration>  
           <webAppConfig>  
             <contextPath>/</contextPath>  
           </webAppConfig>  
           <connectors>  
             <connector  
               implementation="org.mortbay.jetty.security.SslSocketConnector">  
               <port>8443</port>  
               <maxIdleTime>60000</maxIdleTime>  
               <keystore>${project.build.directory}/jetty-ssl.keystore</keystore>  
               <password>axis2key</password>  
               <keyPassword>axis2key</keyPassword>  
             </connector>  
             <connector  
               implementation="org.mortbay.jetty.nio.SelectChannelConnector">  
               <port>8080</port>  
               <maxIdleTime>60000</maxIdleTime>  
             </connector>  
           </connectors>  
         </configuration>  
       </plugin>

Run "mvn Jetty:run " this will start jetty server with both HTTP and HTTPS connectors . Now you can access to the WSDL content over HTTPS. According to above example you can fine WSDL file here.

Step- 04 - Configure Client.

Since now you can access to the WSDL file you are free to use any of your client side preferences to create a WS client , you may generate stub or possible to write service/operation clients. Before you invoke your service you need to perform one more extra step, that is provide your key store details to Java run time . In simply we can use above generated keystore with our client too.

Add following two lines before you invoke your client.

 System.setProperty("javax.net.ssl.trustStore","[location]/jetty-ssl.keystore");  
 System.setProperty("javax.net.ssl.trustStorePassword", "axis2key");

You can download full source code for this sample from here.

Axis2 clustering on Tomcat

2012-05-01T16:32:00.000+05:30

In this post I will discuss how to setup a Axis2 cluster using two Tomcat servers. It's not my intention to describe Axis2 cluster architecture or cluster configuration language, if you need such details refer provided references at the end of this post. Axis2 cluster implementation is based on pure API which you can implement using any Java multicast communication framework, by default Axis2 provide a cluster implemantation based on Tomcat Cluster Communication Module also known as Apache Tribes. Following diagram illustrate the design we are going to discuss in this post but I skip load balancer setup for simplicity but in real world scenario you could use load balancer such as Apache2 server or WSO2 Load Balancer that support for more advanced options.

Pre-requirements

1. Apache Tomcat server. ( Version 7.x.x preferable. )

2. Apache Axis2 WAR distribution (Version 1.6.2 preferable.)

Here I use same machine to setup two Tomcat server instances hence it's required to change server configuration of one instance. Let's say Node-1 having default configuration and Node-2 having custom configuration. Open the server.xml file and change server port, port nubers of HTTP and AJP Connectors as follows.

Node-1 (default configuration)

 <Server port="8005" shutdown="SHUTDOWN">  
 <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />  
 <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

Node-2

 <Server port="9005" shutdown="SHUTDOWN">  
 <Connector port="9090" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="9443" />  
 <Connector port="9009" protocol="AJP/1.3" redirectPort="9443" />

Now install Axis2 WAR distribution on both server instances and stop both servers to edit axis2 configuration file. Open axis2.xml file and edit cluster settings as follows.

Node -1

     <parameter name="AvoidInitiation">false</parameter>   
     <parameter name="domain">sample.cluster.domain</parameter>  
     <parameter name="mcastBindAddress">127.0.0.1</parameter>  
     <parameter name="localMemberHost">127.0.0.1</parameter>  
     <parameter name="localMemberPort">4000</parameter>

Node -2

     <parameter name="AvoidInitiation">false</parameter>   
     <parameter name="domain">sample.cluster.domain</parameter>  
     <parameter name="mcastBindAddress">127.0.0.1</parameter>  
     <parameter name="localMemberHost">127.0.0.1</parameter>  
     <parameter name="localMemberPort">4001</parameter>

Note that in a real network setup it's required to edit mcastBindAddress, localMemberHost settings in addition to localMemberPort value but in my local machine only localMemberPort has changed. After this has done start the Node -1, if there is no issue in your setup you could able to see log messages as follows on node-1 server console.

 [INFO] Initializing cluster...  
 [INFO] Cluster domain: sample.cluster.domain  
 [INFO] Using multicast based membership management scheme  
 Apr 30, 2012 6:37:13 PM org.apache.catalina.tribes.transport.ReceiverBase bind  
 INFO: Receiver Server Socket bound to:/127.0.0.1:4000  
 Apr 30, 2012 6:37:13 PM org.apache.catalina.tribes.membership.McastServiceImpl setupSocket  
 INFO: Setting cluster mcast soTimeout to 500  
 Apr 30, 2012 6:37:13 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Sleeping for 1000 milliseconds to establish cluster membership, start level:4  
 Apr 30, 2012 6:37:14 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Done sleeping, membership established, start level:4  
 Apr 30, 2012 6:37:14 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Sleeping for 1000 milliseconds to establish cluster membership, start level:8  
 Apr 30, 2012 6:37:15 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Done sleeping, membership established, start level:8  
 [WARN] Local member advertising its IP address as 127.0.0.1. Remote members will not be able to connect to this member.  
 [INFO] Local Member 127.0.0.1:4000(sample.cluster.domain)  
 [INFO] No members in current cluster  
 [INFO] Cluster initialization completed.  
 Apr 30, 2012 6:37:15 PM org.apache.catalina.startup.HostConfig deployDirectory  
 INFO: Deploying web application directory /home/sagara/dev/servers/axis2-clustering/tomcat/node1/webapps/ROOT  
 Apr 30, 2012 6:37:15 PM org.apache.coyote.AbstractProtocol start  
 INFO: Starting ProtocolHandler ["http-bio-8080"]  
 Apr 30, 2012 6:37:15 PM org.apache.coyote.AbstractProtocol start  
 INFO: Starting ProtocolHandler ["ajp-bio-8009"]  
 Apr 30, 2012 6:37:15 PM org.apache.catalina.startup.Catalina start  
 INFO: Server startup in 3068 ms

Now start the Node -2 and monitor log messages on Node-2 console

 [INFO] Initializing cluster...  
 [INFO] Cluster domain: sample.cluster.domain  
 [INFO] Using multicast based membership management scheme  
 Apr 30, 2012 6:37:50 PM org.apache.catalina.tribes.transport.ReceiverBase bind  
 INFO: Receiver Server Socket bound to:/127.0.0.1:4001  
 Apr 30, 2012 6:37:50 PM org.apache.catalina.tribes.membership.McastServiceImpl setupSocket  
 INFO: Setting cluster mcast soTimeout to 500  
 Apr 30, 2012 6:37:50 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Sleeping for 1000 milliseconds to establish cluster membership, start level:4  
 [INFO] New member 127.0.0.1:4000(sample.cluster.domain ) joined cluster.  
 Apr 30, 2012 6:37:51 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Done sleeping, membership established, start level:4  
 Apr 30, 2012 6:37:51 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Sleeping for 1000 milliseconds to establish cluster membership, start level:8  
 Apr 30, 2012 6:37:51 PM org.apache.catalina.tribes.io.BufferPool getBufferPool  
 INFO: Created a buffer pool with max size:104857600 bytes of type:org.apache.catalina.tribes.io.BufferPool15Impl  
 Apr 30, 2012 6:37:52 PM org.apache.catalina.tribes.membership.McastServiceImpl waitForMembers  
 INFO: Done sleeping, membership established, start level:8  
 [WARN] Local member advertising its IP address as 127.0.0.1. Remote members will not be able to connect to this member.  
 [INFO] Local Member 127.0.0.1:4001(sample.cluster.domain )  
 [INFO] Members of current cluster  
 [INFO] Member1 127.0.0.1:4000(sample.cluster.domain )  
 [INFO] Trying to send initialization request to 127.0.0.1:4000(sample.cluster.domain )  
 [INFO] Received configuration initialization message  
 [INFO] Trying to send initialization request to 127.0.0.1:4000(sample.cluster.domain )  
 [INFO] Received state initialization message  
 [INFO] Cluster initialization completed.  
 Apr 30, 2012 6:37:52 PM org.apache.catalina.startup.HostConfig deployDirectory  
 INFO: Deploying web application directory /home/sagara/dev/servers/axis2-clustering/tomcat/node2/webapps/ROOT  
 Apr 30, 2012 6:37:52 PM org.apache.coyote.AbstractProtocol start  
 INFO: Starting ProtocolHandler ["http-bio-9090"]  
 Apr 30, 2012 6:37:52 PM org.apache.coyote.AbstractProtocol start  
 INFO: Starting ProtocolHandler ["ajp-bio-9009"]  
 Apr 30, 2012 6:37:52 PM org.apache.catalina.startup.Catalina start  
 INFO: Server startup in 13334 ms

Additionally now you should able to see following log messages on Node-1 server console.

 Apr 30, 2012 6:37:50 PM org.apache.catalina.tribes.io.BufferPool getBufferPool  
 INFO: Created a buffer pool with max size:104857600 bytes of type:org.apache.catalina.tribes.io.BufferPool15Impl  
 [INFO] New member 127.0.0.1:4001(sample.cluster.domain) joined cluster.  
 [INFO] Received GetConfigurationCommand initialization request message from 127.0.0.1:4001(sample.cluster.domain)  
 [INFO] Received GetStateCommand initialization request message from 127.0.0.1:4001(sample.cluster.domain)

If you have followed me up to this point you have successfully setup a Axis2 cluster with two nodes. Now you can deploy any cluster aware web service on this cluster. For testing purposes let's write following POJO service and will deploy on both servers. I have given service code and service.xml below.

 package sample;  
 import org.apache.axis2.context.MessageContext;  
 public class Count {  
   public int count() {  
     int count;  
     MessageContext mc = MessageContext.getCurrentMessageContext();  
     Object ob = mc.getConfigurationContext().getProperty("count");  
     if (ob == null) {  
       count = 1;  
     } else {  
       count = (Integer) ob;  
       count++;  
     }  
     mc.getConfigurationContext().setProperty("count", count);  
     return count;  
   }  
 }

Note that we use ConfigurationContext to store our count values, ConfigurationContext is replicate among cluster members.

 <service name="count">   
   <parameter name="ServiceClass">sample.Count</parameter>  
   <operation name="count">  
   <messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />  
   </operation>  
 </service>

In order to test our cluster aware service we need a Web service client, for the simplicity I will use a browser and Axis2 REST support. Since we skip the load balancer setup following two different URLs can be use to invoke services . Once you invokes services on both servers you can notice that the count value is shared among two Axis2 instances clearly.

 http://localhost:8080/axis2/services/count/count  
 http://localhost:9090/axis2/services/count/count

References

Axis2 JMS transport and ActiveMQ

2012-04-21T19:14:00.001+05:30

In this post I will describe how to configure Axis2 JMS transport properly and test web services through JMS transport. For the simplicity I will use Apache ActiveMQ as the JMS server and will use ActiveMQ admin console as a JMS client to send and receive messages. In my future posts I will describe how to use ActiveMQ Maven plug-in with Axis2 and also how to test Axis2 JMS transports with few other implementations such as Apache QPID and WSO2 Message Broker.

First, If you don't have a ActiveMQ installation already, download the binary distribution from here and start the ActiveMQ server. If it's started properly make sure you can access to admin console through the following URL, we will use this admin console as a JMS client.

 http://0.0.0.0:8161/admin

The next step is add requited dependencies and configure JMS transport in Axis2. Here I use Axis2 Simple HTTP server but same steps can be used with any other application server too.

(1) Add following dependencies to the "lib" directory of Axis2.

1. axis2-transport-jms-1.x.x (axis2-transport-jms-1.7.0-SNAPSHOT.jar or axis2-transport-jms-1.7.0 )
2. axis2-transport-base-1.x.x (axis2-transport-base-1.7.0-SNAPSHOT.jar or axis2-transport-base- 1.7.0)
3. geronimo-j2ee-management_1.1_spec-1.0.x (geronimo-j2ee-management_1.1_spec-1.0.1.jar)
4. geronimo-jms_1.1_spec-1.1.x (geronimo-jms_1.1_spec-1.1.1.jar)
5. activemq-core-5.1.x (activemq-core-5.1.0.jar)
6. coomons-io-2.1 (coomons-io-2.1.jar)

You can find above dependencies on Axis2 transport project here or you can find latest development snapshots from Apache build server here.

(2) Like in any other Axis2 transport your next task is to configure particular transport through the axis2.xml file by adding underline TransportListener and TransportSender. For the JMS transport you can add following settings.

 <transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">  
   <parameter name="default" locked="false">             
     <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>  
     <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>      
     <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>  
   </parameter>  
 </transportReceiver>

 <transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender">  
   <parameter name="default" locked="false">             
     <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter>  
     <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter>      
     <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>  
   </parameter>  
 </transportSender>

Axis2 Transport user guide provide advanced configuration details such as separate configuration for JMS Queue and Topic etc.

(3) Start Axis2 server, If JMS transport is configured properly it is possible to see log message about JMS transport as follows.

 [INFO] JMS Sender started  
 [INFO] JMS ConnectionFactory : default initialized  
 [INFO] JMS Transport Sender initialized...  
 ..................  
 [INFO] JMS ConnectionFactory : default initialized  
 [INFO] JMS Transport Receiver/Listener initialized...  
 [INFO] Listening on port 8080  
 [INFO] JMS listener started  
 [INFO] Task manager for service : Version [re-]initialized  
 [INFO] Started to listen on destination : Version of type Queue for service Version  
 [INFO] Task manager for service : CalculatorService [re-]initialized  
 [INFO] Started to listen on destination : CalculatorService of type Queue for service CalculatorService  
 [INFO] Task manager for service : mtomService1Axis [re-]initialized  
 [INFO] Started to listen on destination : mtomService1Axis of type Queue for service mtomService1Axis  
 [INFO] [SimpleAxisServer] Started  
 [SimpleAxisServer] Started

Now you have configured Axis2 JMS transport properly and it's possible to use any JMS client to invoke web services deployed on Axis2. Let's try to invoke getVersion operation on Version web service through ActiveMQ admin console. Again in a browser go to the ActiveMQ admin console through the http://0.0.0.0:8161/admin URL, now you have to select "Send" tab to reach the send wizard. This wizard expect 3 basic inputs from you as input message, JMS destination ( in this case destination queue) and reply-to location. By looking at Axis2 server startup logs you can find hint about JMS destination bind to each web service, you can ensure availability of this JMS destination in ActiveMQ console too.

  [INFO] Started to listen on destination : Version of type Queue for service Version

For our test scenario let's use following properties.

Destination - Version
Reply-To - VersionResponse ( This destination is not available on ActiveMQ at this point, it will be created when the repose messages arrive to the JMS server)
In put message - Use following message
Correlation ID - Add a random number

 <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:axis="http://axisversion.sample">  
   <soap:Header/>  
   <soap:Body>  
    <axis:getVersion/>  
   </soap:Body>  
 </soap:Envelope>

Now you can see the response message by browsing "VersionResponse" Queue as follows.

How to use Axis2 WSDL2JAVA with proxy authentication

2012-04-13T18:56:00.001+05:30

Securing WSDL using basic authentication is a common practice for number of enterprise web service providers. Also in some business domains it's required to secure various WSDL URLs among business partners so that partners can access service contracts according to their business agreements by providing a user name and a password. As the most popular Java web service stack lot of people keep asking to enable basic authentication to WSDL2JAVA tool so that they can access WSDL files secured through basic authentication.

Now you can use following two options to specify proxy user name and password.

 -http-proxy-user [user name]      - Proxy user name for basic authentication.  
 -http-proxy-password [password]   - Proxy password for basic authentication.

The following examples show how to use above option in command line.

 wsdl2java.sh -http-proxy-user user-name -http-proxy-password password -uri http://localhost/axis2/services/Version?wsdl

 wsdl2java.sh -http-proxy-user user-name -http-proxy-password password -wv 2.0 -uri http://localhost/axis2/services/Version?wsdl2

Also these two options supported in Wsdl2Java Maven plug-in too.

 axis2.wsdl2code.http-proxy-user  - User name for proxy server.  
 axis2.wsdl2code.http-proxy-password - Password for proxy server.

Test Axis2 JAX-WS MTOM service using SoapUI

2012-03-24T21:37:00.006+05:30

In this post I have described how to write a MTOM aware JAX-WS service and how to use SoapUI to invoke this service. Consider a service called PictureService that uploads images through a web service, it uses a bean called PictureInfo that contains two fields as textual name of the image and image binary data.

 @XmlRootElement  
 public class PictureInfo {  
   private String name;  
   protected DataHandler imageData;  
   public String getName() {  
     return name;  
   }  
   public void setName(String name) {  
     this.name = name;  
   }  
   @XmlMimeType("application/octet-stream")  
   public DataHandler getImageData() {  
     return imageData;  
   }  
   public void setImageData(DataHandler imageData) {  
     this.imageData = imageData;  
   }  
 }

As you can see in the above code snippet getImageData() method annotated using XmlMimeType that instructs JAXB runtime to consider this particular filed as a MIME content. You can find web service interface and implementation in the following code snippet.

 @WebService(name = "pictureService")  
 public interface PictureService {  
   boolean uploadPicture(PictureInfo pictureInfo);  
 }

 @WebService(endpointInterface = "org.apache.axis2.sample.pictureservice.PictureService", serviceName = "pictureService")  
 public class PictureServiceImpl implements PictureService {  
   @Override  
   public boolean uploadPicture(PictureInfo pictureInfo) {  
     DataHandler dh = pictureInfo.getImageData();  
     try {  
       File F = new File("../data/"+ pictureInfo.getName() + ".jpg");  
       FileOutputStream fs = new FileOutputStream(F);  
       dh.writeTo(fs);  
       fs.flush();  
       fs.close();  
       return true;  
     } catch (Exception e) {  
       e.printStackTrace();  
     }  
     return false;  
   }  
 }

After compiling above classes it's required to package them as a jar file. Usually this is a straight forward task with a build tool like Maven. For the simplicity I used Axis2 simple HTTP server that shipped with binary distribution to deploy this sample application but it is possible to use any application server together with Axis2 WAR distribution. In case of Simple HTTP server use following steps to deploy the service properly.

Create a directory called "servicejars" under the Axis2 repository and place above created service jar file there. Axis2 deployment engine scan this directory in order to deploy JAX-WS services.
Create a directory called "data" as same level as "bin" directory, this directory used to store images uploaded by users.
Start Axis2 simple HTTP server.

It should be possible to access generated WSDL file through http://localhost:8080/axis2/services/pictureService?wsdl address.

Now create a SoapUI project by providing the above URL in the usual way as you create SoapUI project for any other web service. In the left side project explore window, find the automatically created "Request 1" message that should be under uploadPicture operation then open the request editor for this message. At this point you have need to perform following two tasks.

1. Set "Enable MTOM" property value to true because default value of this property is false. ( you can see message properties in a window located in left bottom side of your screen)

2. Fill sample values and attach a image using "Add an attachment" menu option. Before you send this message make sure value of "cid:" field is match with ContentID of the attachment. I have given a screen shot of such example here. After executing above method you can see uploaded image stored within "data" directory of the server.

Apache BarCamp Colombo 2012

2012-02-15T07:35:00.002+05:30

Axis2 archetype to create web application and Maven Jetty/Tomcat plug-ins.

2012-02-02T13:34:00.002+05:30

Axis2 provides number of web service deployment options. Unlike some other frameworks Axis2 can be integrate as a framework in a web application or can be used as a container to hold number of web services. Sometimes back Deepal wrote a nice tutorial to explain how to use Axis2 in a web application you can read his post here.

From Axis2 version 1.7.0 onwards we have introduced a new Maven archetype to create Axis2 embedded web applications. Following are the necessary step to use this archetype.

1.) It's possible to get list of available archetypes by invoking archetype:generate goal as follows. [ refer NOTE -1 ]

 mvn archetype:generate

2.) Select the number corresponds to "org.apache.axis2.archetype:quickstart-webapp (Maven archetype for creating a Axis2 web Service as a webapp)" . Then provide other input parameters such as group name, artifact name etc.

 541: local -> org.apache.axis2.archetype:quickstart (Maven archetype for creating a Axis2 web Service)  
 542: local -> org.apache.axis2.archetype:quickstart-webapp (Maven archetype for creating a Axis2 web Service as a webapp)  
 Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): 171: 542  
 [INFO] snapshot org.apache.axis2.archetype:quickstart-webapp:1.7.0-SNAPSHOT: checking for updates from quickstart-webapp-repo  
 Downloading: http://repository.apache.org/snapshots//org/apache/axis2/archetype/quickstart-webapp/1.7.0-SNAPSHOT/quickstart-webapp-1.7.0-20120131.070321-34.jar  
 10K downloaded (quickstart-webapp-1.7.0-20120131.070321-34.jar)  
 Downloading: http://repository.apache.org/snapshots//org/apache/axis2/archetype/quickstart-webapp/1.7.0-SNAPSHOT/quickstart-webapp-1.7.0-20120131.070321-34.pom  
 1K downloaded (quickstart-webapp-1.7.0-20120131.070321-34.pom)  
 Define value for property 'groupId': : sample  
 Define value for property 'artifactId': : sampleWebApp  
 Define value for property 'version': 1.0-SNAPSHOT: 1.0  
 Define value for property 'package': sample:  
 Confirm properties configuration:  
 groupId: sample  
 artifactId: sampleWebApp  
 version: 1.0  
 package: sample  
 Y:  
 [INFO] ----------------------------------------------------------------------------  
 [INFO] Using following parameters for creating project from Archetype: quickstart-webapp:1.7.0-SNAPSHOT  
 [INFO] ----------------------------------------------------------------------------  
 [INFO] Parameter: groupId, Value: sample  
 [INFO] Parameter: artifactId, Value: sampleWebApp  
 [INFO] Parameter: version, Value: 1.0  
 [INFO] Parameter: package, Value: sample  
 [INFO] Parameter: packageInPathFormat, Value: sample  
 [INFO] Parameter: package, Value: sample  
 [INFO] Parameter: version, Value: 1.0  
 [INFO] Parameter: groupId, Value: sample  
 [INFO] Parameter: artifactId, Value: sampleWebApp  
 [INFO] project created from Archetype in dir: /home/apps/sampleWebApp  
 [INFO] ------------------------------------------------------------------------  
 [INFO] BUILD SUCCESSFUL  
 [INFO] ------------------------------------------------------------------------  
 [INFO] Total time: 57 seconds  
 [INFO] Finished at: Tue Jan 31 13:28:46 IST 2012  
 [INFO] Final Memory: 30M/238M  
 [INFO] ------------------------------------------------------------------------

Now you can import generated Maven project to any of your favorite IDE but console is sufficient to run default service.

Generated project's POM file is already configured for Maven Jetty plug-in and It's possible to see following entries.

     <plugin>  
         <groupId>org.mortbay.jetty</groupId>  
         <artifactId>maven-jetty-plugin</artifactId>  
         <configuration>  
           <webAppConfig>  
             <contextPath>/</contextPath>  
           </webAppConfig>  
         </configuration>  
       </plugin>

3.) Run Jetty server using following command. [ NOTE -2 ]

 mvn clean jetty:run

4.) Above command will start Jetty server and deploy current Maven project as a web application in this case it deploy available web services too. You can access WSDL file for deployed web service using following URL.

 http://localhost:8080/services/SimpleService?wsdl

5.) You can use Axis2's WSDL2JAVA or tool like a SoapUi to generate web service client for above service alternatively you can test above service using your browser in a RESTfull manner.

 http://localhost:8080/services/SimpleService/helloService?msg=sagara

You should able to see following response in your browser.

 <ns:helloServiceResponse><ns:return>Hello sagara</ns:return></ns:helloServiceResponse>

6.) If you are happy with your service you can create a WAR archive using mvn package command and possible to deploy in real app server instance.

Axis2 Webapp archetype use Jetty as the default server but it's possible to use Tomcat as follows.

7.) Add tomcat-maven-plugin to the POM file and configure it properly.

 <plugin>  
      <groupId>org.codehaus.mojo</groupId>  
      <artifactId>tomcat-maven-plugin</artifactId>  
       <configuration>  
              <useSeparateTomcatClassLoader>  
               true  
             </useSeparateTomcatClassLoader>                       
        </configuration>  
   </plugin>

8.) Now all you need is to execute run goal as follows.

 mvn clean tomcat:run

9.) Also if you plan to deploy your service in a Tomcat instance you can you use deploy goal to deploy your service.

 mvn tomcat:deploy

Following are two sample configurations to use with deploy goal.

      <plugin>  
           <groupId>org.codehaus.mojo</groupId>  
            <artifactId>tomcat-maven-plugin</artifactId>  
            <configuration>  
                <useSeparateTomcatClassLoader>  
                  true  
                </useSeparateTomcatClassLoader>               
                <path>/ws</path>  
               <warFile>target/wepAppSample-1.0.war</warFile>  
               <username>tomcat</username>  
               <password>tomcat</password>  
             </configuration>  
       </plugin>

         <plugin>  
               <groupId>org.codehaus.mojo</groupId>  
               <artifactId>tomcat-maven-plugin</artifactId>  
               <configuration>  
                <useSeparateTomcatClassLoader>  
                 true  
                </useSeparateTomcatClassLoader>  
               <server>TomcatServer</server>  
                <path>/ws</path>  
               <warFile>target/wepAppSample-1.0.war</warFile>                
              </configuration>  
          </plugin>

NOTE -1
Until Axis2 1.7.0 version get released this archetype is not available on public Maven repos but you can point to Apache snapshot repository as follows.

 mvn archetype:generate -DarchetypeRepository=http://repository.apache.org/snapshots/

NOTE -2
Until Axis2 1.7.0 version get released it's required to add following snapshot repository to the project's POM file in order to grab snapshot artifacts.

         <repositories>  
           <repository>     
            <id>snapshots</id>  
            <url>http://repository.apache.org/snapshots</url>  
           </repository>    
         </repositories>

JAX-WS processing using Axis2 tools

2012-01-22T21:41:00.001+05:30

JAX-WS wsgen and wsimport tools were designed to generate portable artifacts so that those artifacts can be use with any JAX-WS vendor runtime also these tools distribute as a part of JDK. Traditionally Axis2 does not provide any JAX-WS tools, instead it's possible to execute artifacts generated by wsgen and wsimport tools within Axis2. Recently number of users are requested to enable JAX-WS processing through Axis2 tools such as WSDL2JAVA and JAVA2WSDL. Starting from 1.7.0 version Axis2 provides first class JAX-WS processing support for both WSDL2JAVA and JAVA2WSDL tools. Also it's possible use wsgen and wsimport tools with Axis2 in the usual manner.

There is a new command line option introduced as "jws" that enables switching between Axis2 native processing and JAX-WS processing. Once the "jws" option available the tool will switch to JAX-WS processing from default Axis2 native processing .

To provide other input options it is possible to use some of the existing WSDL2JAVA/JAVA2WSDL options or possible to use wsgen/wsimport options if those option names are not conflict with Axis2 tools option names. If such option name conflict occurs Axis2 option will get the priority.

WSDL2JAVA options

Option (Axis2)	Option (wsimport)
-uri [url or path]	-uri [url or path]	A url or path to a WSDL
-o [path]	-d [path]	Specify a directory path for the generated code
-p [pkg name]	-p [pkg name]	Specify a custom package name for the generated code
-http-proxy-host [host name]	-httpproxy [host:port]	specify a HTTP proxy server
-http-proxy-port [port]	-httpproxy [host:port]	specify a HTTP proxy server

Examples :

 wsdl2java.sh -jws -uri SimpleService.wsdl

 wsdl2java.sh -jws -uri SimpleService.wsdl -o out

 wsdl2java.sh -jws -uri SimpleService.wsdl -d out

JAVA2WSDL options

Option (Axis2)	Option (wsimport)
-cn [fully qualified class name]	-cn [fully qualified class name]	fully qualified class name
-o [path]	-d [path]	Output directory
-cp [class path uri]	-cp [class path uri]	list of classpath entries

Examples :

 java2wsdl.sh -jws -cn sample.UserService

 java2wsdl.sh -jws -cn sample.UserService -d out

 java2wsdl.sh -jws -cn sample.UserService -o out

Axis2 Simple HTTP server Maven plugin

2012-01-20T00:23:00.002+05:30

As I mentioned in my last blog post this post covers one of the new feature of upcoming Axis2 1.7.0 version. Recently we have done number of improvements for Axis2 Maven support. There are three new Maven related modules introduced as follows.

simple-server-maven-plugin - A Maven plug-in that allows to run Axis2's simple HTTP server as a maven plug-in.
quickstart archetype - Maven archetype to develop and package Axis2 native (AAR) web services.
quickstart-webapp - Maven archetype to develop and package Axis2 web services as a web application(WAR).

In this post I discuss how to use simple-server-maven-plugin and it's configuration options. At the moment simple-server-maven-plugin provides single goal as "axis2:run".

You can add simple-server-maven-plugin into your Maven POM file as follows.

     <plugin>  
         <groupId>org.apache.axis2</groupId>  
         <artifactId>simple-server-maven-plugin</artifactId>  
         <version>${axis2.version}</version>  
     </plugin>

Note : At the moment this plug-in available only with 1.7.0-SNAPSHOT version and until this get released with official Apache releases you have to do one extra step as mentioned here[1].

As you may know Axis2 services expect single meta data file called services.xml under a directory named META-INF. By default it expect to place this meta data files under the "src/main/resources/services" directory. In order to deploy multiple service META-INF should place inside a another directory. As an example /src/main/resources/services/SimpleService/META-INF/services.xml. Also by default it facilitates to place Axis2 modules (.mar) under src/main/resources/modules directory. Following picture shows one such a example directory structure.

Once you have completed above steps you can run Axis2 Simple HTTP server using run goal.

 mvn clean axis2:run

Now It's possible to access available service listing page by http://localhost:8080 URL.

simple-server-maven-plugin support for following configuration options.

Option
repoPath	Path to Axis2 repository by default run goal creates Axis2 repository inside the project's target directory.
confPath	Path to Axis2.xml configuration file.
stdServiceSrcDir	Directory to place service meta (META-INF/services.xml) information. This directory supports multiple service deployment. Default value is "src/main/resources/services".
moduleSrcDir	moduleSrcDir - Directory to place Axis2 modules (.mar) default value is "src/main/resources/modules"

Hope this plug-in save web service development time greatly and also this can be used to automate unit test easily.

[1] - Since above plug-in still not available on official Maven repositories it is required to add following SNAPSHOT repository to your POM file. But this is not required after Axis2 1.7.0 release.

    <pluginRepositories>  
           <pluginRepository>     
            <id>apache-snapshots</id>     
            <url>http://repository.apache.org/snapshots</url>  
           </pluginRepository>    
      </pluginRepositories>

What is new in Axis2 1.7.0 - 1

2011-11-16T04:16:00.001+05:30

I conducted a Fast Feather talk during the ApacheCon NA 2011 to give a overview about new features of upcoming Axis2 1.7.0 release. I started to write series of blog post mentioning new features of new release I will explain each of these features in detail and try to provide samples too.

As the starting post I attached a slide that shows overview of most of the new features.

What is new in Axis2 1.7.0 rlease - 1

View more presentations from sagara10.

SOAP encoding and Axis2

2011-10-20T12:55:00.007+05:30

As of today SOAP encoding only exists due to some historical reasons non of the standard web service framework supports for SAOP encoding that includes Axis2, Metro and CXF. Some people still tend to use SAOP encoding without knowing why WS frameworks discourage to use it or some have to use it when they implement web service clients. Usually I can see number of such queries on axis2-user list time to time. Here I discuss few workarounds useful when you dealing with SAOP encoding.

What is SOAP encoding

When authors of SOAP specification write it for first time they wanted to define a common way to describe messages but at that time XMLSchema was not completed and not in main stream too. Hence they came up with idea of SOAP Encoding as an extension of the SOAP specification that defines how a data value should be encoded in an XML.

SOAP encoding define it's own namespace as http://schemas.xmlsoap.org/soap/encoding/ and set of rules to follow. SOAP encoding introduced number of interoperability and validation issues. Tim Ewald described some of those issues in his article here.WS-I also highly discourage to use encoding systems in their basic profile.

SAOP encoding in server side

If you use code first approach there is nothing to worry Axis2 runtime generate WSDL that does not use SOAP encoding at all. But if you use contract first approach you need to make sure that you don't use SOAP encoding in your service contract instead XMLSchema provides very powerful type system for your messages.

SOAP encoding array concept is still used by many people, if you have such legacy WSDL file you could easily redesign your types using XMLSchema. Following example describes one such scenario.

First let's see SAOP encoding sample.

 <complexType name="ArrayOfStrings">  
  <complexContent>  
   <restriction base="SOAP-ENC:Array">  
    <attribute ref="SOAP-ENC:arrayType"  
          wsdl:arrayType="xsd:string[]"/>  
   </restriction>  
  </complexContent>  
 </complexType>

Now same thing can be easily rewritten using XMLSchema as follows.

 <complexType name="ArrayOfStrings"  
  <element name="item" type="xsd:string" maxOccurs="20"/>  
 </complexType>

SOAP encoding in client side

Sometimes it is required to access services that has service description with SOAP encoding constructs. By default Axis2 code generation tool called WSDL2JAVA fail on generating codes for such WSDL files. But as a workaround you could use XMLBeans data binding to generate clients codes for above WSDLs. XMLBeans simply generate Java beans for all the types available on schema . In this case it generate beans for all the types available on SOAP encoding schema here.

You can invoke code generation tool with XMLbeans data binding as follows.

 wsdl2java.sh -uri service.wsdl -d xmlbeans

Conclusion

As we discussed the best practice is avoid use of SOAP encoding when you design web services.In case if you are a consumer of service that use SAOP encoding in their WSDL, Axis2 XMLBeans data binding provide a great solution for you.

Apache Community building event within WSO2Con 2011

2011-09-11T23:02:00.004+05:30

We are planning to have a free Apache Community building event within
the WSO2Con conference next week (13th September to 15th September) in
Colombo, Sri Lanka. We would like to invite contributors /committers
on Apache Axis2, Apache WS, Apache ODE, Apache Synapse to take a part
of this event. Number of committers from above projects will be there
and it's a good chance to communicate with them and get your first
step on those mentioned projects. Also you can join with us using any
Freenode IRC client on #axis2 channel or use #Axis2 on Twitter.

This Community event sponsored by WSO2 and will be held on same conference venue. WSO2 is a leading and long-standing contributor of number of world class Apache projects that includes Axis2 , Synapse, WS, Woden etc. Most of WSO2 committers will participate to this event and it's a rear chance to meet them face to face and discuss your issues , suggestions etc. Also those who want to contribute also can get their hands dirty with those project's first step. No one can tell, isn't it your first step to be a Apache committer ? you better give a try and see .

you can find location and other details from here http://wso2.com/events/wso2con-2011-colombo/

One last thing , within WSO2 we not only develop and release products under Apache licence instead we use Apache like open development model, WSO2 engineering lists are completely open for anyone and we are encouraging community contribution.

How to get best use of AXIS2 Object support.

2011-07-31T18:14:00.001+05:30

Axis2 web service framework offers number of development approaches to match various user requirements instead of limiting to support one or two specifications. This is a one distinct feature that Axis2 go beyond from some other web service frameworks. If someone want to deploy a web service very quickly using POJOs without touching XML or SOAP, AXIS2 ADB is the ideal solution for him. ADB Object support is a one of the great feature and we have done some nice set of recent improvements too. I will discuss few tips within this post that users should know in order to get best use of Axis2 ADB Object support.

 Public Object objectService(Object obj){  
 System.out.println(obj)  
 return obj;  
 }

Since above method takes Object type as an argument and return type it should possible to send any java primitive or POJO as a parameter value. As an example for a sample String massage it is possible to have following payload.

 <ns2:obj   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
           xmlns:xs="http://www.w3.org/2001/XMLSchema"   
           xsi:type="xs:string">  
        Hello World  
 </ns2:obj>

In case of POJO message it is possible to have following payload.

 <ns2:obj xmlns:ns1="http://sample/xsd"   
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
                 xsi:type="ns1:Student">  
             <ns1:age>20</ns1:age>  
             <ns1:id>200</ns1:id>  
             <ns1:name>saman</ns1:name>  
            </ns2:obj>

In above messages “xsi:type” attribute carries type system information that is required in marshalling and unmarshalling. When you send a POJO value server need to aware with the schema information associate with that particular POJO type otherwise marshalling/unmarshalling process will not possible. Typically Axis2 run-time only aware with the types associate with a particular service method, if you send above second message you will get an exception something similar to below because server can’t identify type system associate with incoming message.

 Exception in thread "main" org.apache.axis2.AxisFault: Unknow type {http://sample/xsd}Student

the solution here is use a parameter called “extraClass” within your services.xml file.

e.g -

 <parameter name="extraClass">sample.Item,sample.Student</parameter>

The above parameter will instruct run-time to register type details of give classes and generate schema as well . Without schema generation it is not possible to write WS clients that capable of send and receive messages with above POJOs. That is what you all need in server side now you can test your service using a tool like SoapUI.

In client side easiest and quickest way to write a client is generate code using WSDL2JAVA tool , again by default WSDL2JAVA tool also ignore extra sachem type available on WSDL file when generating codes. But it is possible to change this behaviour by adding option
“-g” that instruct to generate codes for all the schema types available . You can use following command to generate client side codes for sample application .

 axis2-1.7.0-SNAPSHOT/bin/wsdl2java.sh -uri http://localhost:8080/services/SimpleObjectService?wsdl -g

Now you have generated POJOs in your client side you can use them with your Object service as follows.

 Student student = new Student();  
 student.setName("saman");  
 student.setId(200);  
 student.setAge(20);  
 req.setObj(student);  
 ObjectServiceResponse res = stub.objectService(req );  
 System.out.println(res.get_return());