Invoking secure web services using SOAPUI - part1

SOAPUI is a very useful free tool which can be used in SOA testing. Service invocation using SOAPUI is straight forward and you can find a lot of references by surfing web. However, there are limited information about invoking services with various QOS (Quality of Service) features such as WS-Security, WS-Addressing etc.

This post takes you through the simplest QOS scenario, a web service is secured with UserName token policy and how SOAPUI is used to invoke such a service.

I will use the default HelloService hosted in WSO2 WSAS in this demonstration but the service invocation approach is similar with any service provider.

Pre-requisites:

1. Download and install SOAPUI-3.6.1 or later (free version)

2. Download and install WSO2 WSAS-3.*

Step 1

First, we need to secure a web service hosted in WSAS. We will configure HelloService so that only the users in admin group will be allowed to invoke the service. In order to do that, start WSO2 WSAS and log in to management console. Then, select HelloService from Deployed Services page.

You will be directed to the service dashboard of HelloService as follows.

Click on Security link and Select "Enable Security" option. Then select, UserNameToken security scenario.

In the next screen, select admin user group and click on finish to apply the security policy for HelloService.

Step 2
We have configured server side security policy. If you look at the WSDL of HelloService (http://localhost:9763/services/HelloService?wsdl), you will notice that UserNameToken security policy is added to the service.
Now, we need to configure SOAPUI project to talk to HelloService with the required user credentials.

First, start SOAPUI and create a new project. Specify https://localhost:9443/services/HelloService?wsdl as the initial WSDL. Keep the other default settings.
You will see the following project structure.



Replace ? with an input value in the request editor and run the test. You will encounter a SOAPFault, Missing wsse:Security header in request, since we did not send security headers with the request.
Lets configure client side security now. In the Request Properties pane of SOAPUI project, you will find the following properties.

Username
Password
WSS-Password Type
WSS TimeToLive

Specify the following values for the above properties.

Username = admin
Password = admin
WSS-Password Type = PasswordText
WSS TimeToLive = 2000

Run the test. Have a look at the raw request view. You will see security header is added to the request.
Thats all! We will look at more advanced scenarios such as signing and encrypting messages with SOAPUI in future posts.

How to specify a custom scope for WS-Discovery target service

As I explained in a previous blog post, WS-Discovery support is included in the latest WSO2 carbon release (3.0.0).
WSO2 WSAS can be considered as a target service hosting provider. A default scope is assigned to all the target services discovered by a Discovery Proxy.
If a discovery client looks for a service based on the service type, or some scopes, the client sends probe message to the DiscoveryProxy. Then the proxy responds back to the client with the appropriate service metadata.
Suppose we need to specify a scope for the services deployed on WSAS (target services). How can we do that?

You can specify the service scope(s), by adding a parameter in the services.xml of the Axis2 Service archive (*.aar) as follows.

<parameter name="wsDiscoveryParams">
<Scopes>http://wso2.org/engineering</Scopes>
</parameter>

Then, you can probe the services either through WS-Discovery Control Panel in WSO2 ESB management console as shown here or using WS-Discovery Client API as follows.

DiscoveryClient client = new DiscoveryClient(cfgCtx, discoveryProxyURL);
TargetService[] services = client.probe(types, scopes, matchingCriteria);

Hierarchical service deployment support in WSO2 WSAS-3.2.0

WSO2 WSAS-3.2.0 is the latest version of WSO2 Web Services Application Server which consists of some new features as well as a lot of bug fixes. Hierarchical service deployment is one of the new features included in the latest WSAS.
Hierarchical service deployment model allows you to deploy two (or more) different versions of the same service in a very easy manner.
Lets see how multiple versions of the same services can be deployed on WSAS-3.2.0

Pre-requisites:
Download WSO2 WSAS-3.2.0 from here

Step 1

Start WSO2 WSAS by running wso2server.sh{bat} from WSAS_HOME/bin
Access management console using https://localhost:9443/carbon and log in with the default credentials(admin/admin)

Select Axis2 Service from the left navigation menu.



You will notice there is an input text box, Service Hierarchy. Here you can specify a service path. eg:- /marketing/test
Browse a service archive (eg:- Axis2Service.aar) in your local file system and click on Upload.
The service will be deployed successfully, go to the service list page and you will the service is listed there as follows. The service name is prefixed with the hierarchy path you have given when deploying the service (marketing/test/Axis2Service)



Step 2

Now, we are going to deploy a different version of the same Axis2Service. Access the Manage --> Services --> Add --> Axis2 Service page and specify a new service hierarchy (eg:- /sales/test)
Browse the same service archive which have deployed in the previous step (Axis2Service.aar) and click on upload.

Now, you will notice a different version of the same service, sales/test/Axis2Service listed in the service management page.

Likewise, you can deploy many versions of the same service and make use them in your SOA infrastructure. Hierarchical service deployment facility can be used in Spring, Jax-WS and Jar services as well.

WS-Discovery with WSO2 Carbon

WS-Discovery defines a protocol to locate web services on a network, more specifically in a SOA.

The newest release of WSO2 Carbon platform (version 3.0.0) provides a complete implementation of the WS-Discovery managed mode.

This post demonstrates an end-to-end workflow of WS-Discovery support in WSO2 Carbon. With WS-Discovery components for WSO2 Carbon, any Carbon server can act as a WS-Discovery client, a WS-Discovery proxy or a WS-Discovery target service. We will use three products from WSO2 Carbon product suite, namely WSO2 Governance Registry (G-reg), WSO2 ESB and WSO2 WSAS.

WSO2 G-reg acts as the central repository in which the discovered services and the related meta data are stored. WSO2 WSAS is used to host the target services. WSO2 ESB participates in the scenario as a discovery client which looks for services and endpoints.

Lets start with setting up the environment.

Pre-requistes:

Download WSO2 Governance Registry-3.5.0, WSO2 WSAS-3.2.0 and WSO2 ESB-3.0.0

Install and run each product. In this demonstration, I will run G-reg in http port 9763 and https port 9443. WSAS on http port 9764 and https port 9444. ESB on http port 9765 and https port 9445. In this way, I can run all three products in single machine.

Step 1

As I explained initially, WSO2 Governance Registry acts as the discovery proxy. If you access the https://localhost:9443/services/DiscoveryProxy?wsdl, you will find out the wsdl of the discovery proxy service. Make a note of the DiscoveryProxy service endpoint (https://localhost:9443/services/DiscoveryProxy)

Step 2

Now, we need to configure WSAS instance, so that it takes part in service discovery scenario. WSAS is used to host target services. Therefore, it sends a unicast Hello messages to a Discovery Proxy when the services join a network. So, we must configure the Discovey Proxy service endpoint in WSAS.

Open WSAS_HOME/repository/conf/axis2.xml and add the following parameter.

<parameter name="DiscoveryProxy">https://localhost:9443/services/DiscoveryProxy</parameter>

Save the file and restart WSAS. This will enable WSAS to send unicast hello messages when the services are deployed.

Now, access the management console of WSO2 Governance Registry instance and go to Metadata-->List-->Services page. You will see that 3 discovered services are listed there.

These are the three default services included in WSAS. When starting WSAS, those three services have sent the hello messages to the discovery proxy and register them in G-reg.

Image:- Discovered services in G-reg



Now, log in to WSAS management console and deploy a new service. If you refresh the above service list page, you will see a new service is discovered by G-reg and it is assigned a unique service name.



Step 3



The third member participates in our scenario is WSO2 ESB, which acts as a discovery client. WSO2 ESB provides you with a user interface to mange the client aspects of WS-Discovery. Using that, you can connect to remote WS-Discovery proxies and probe them for any services and service endpoints which have been already discovered.



Log in to ESB management console and select Configure > WS-Discovery from the left navigation menu to access WS-Discovery Control panel.







Image:- WS-Discovery Control Panel in ESB



In order to connect to the remote DiscoveryProxy (in G-reg) and make use of the discovered services, we should configure a discovery proxy in ESB. Click on "Add Discovery Proxy" link to add a new proxy. You will be directed to discovery proxy settings screen in which you can give a name for the proxy and the remote DiscoveryProxy URL (In our case https://localhost:9443/services/DiscoveryProxy). You will be redirected to the home page of WS-Discovey Control Panel once the proxy is created. The created proxy will be listed in the control panel home page. Click on "View" to find the target services and endpoints discovered by the proxy. You will be directed to a page as shown below.







Here, you will see that 4 service are discovered and shown with a UUID and associated endpoints of each discovered service.

Click on a discovered service UUID. You will be directed to a new page with more information about the service. Using this page, either you can create an ESB endpoint or directly create an ESB proxy service referring to the discovered service.



We have seen the basic workflow of WS-Discovey implementation of WSO2 Carbon platform. If you have any issues with the above steps, drop me a mail or contact WSO2 ESB forum at www.wso2.org

How to invoke a secured web service without maintaining a policy at the client side

When we call a secure web service, the most common way of invocation is to use a policy which is compliant with the service policy at the client side. Usually, the client side policy is placed at the client file system. We have observed how this is done in few posts which published earlier.
However, there is a major drawback in this method, user has to change the client policy whenever the service policy is changed.
In order to overcome this limitation, we can use Axis2 DynamicClient to derive client policy by referring to the service WSDL which essentially keeps the service policy.

Lets see how this can be done using WSO2 WSAS-3.1.*

Pre-requisite:

Download and install WSO2 WSAS-3.1.*

Step 1

We are going to secure the default HelloService shipped with WSAS. We configure HelloService with "Sign and Encrypt - X509 Authentication" policy. In order to do that, first start WSO2 WSAS server by running wso2server.sh which is located at WSO2WSAS_HOME/bin directory.
Then, log in to the management console by accessing https://localhost:9443/carbon

Select the default HelloService and navigate to the service dashboard. Click on Security and configure Sign and Encrypt - X509 Authentication security scenario as shown below. Make sure to use wso2carbon.jks as trusted key store and private key store.



Thats all we have to do at the server side. Lets write a client to invoke the service.

Step 2

Here we are going to use Axis2 Dynamic Client which is an extension of the ServiceClient class.
First, instantiate a dynamicClient object using RPCServiceClient by passing ConfigurationContext, WSDL Url of the service, the QName of the service and the port name as parameters.

RPCServiceClient dynamicClient = new RPCServiceClient(null, new URL("http://localhost:9763/services/HelloService?wsdl"),
           new QName("http://www.wso2.org/types", "HelloService"), "HelloServiceHttpSoap12Endpoint"); 

Then, we can engage rampart module as follows.

dynamicClient.engageModule("rampart");

Now we should update the client side policy with the rampart-config programatically.

      RampartConfig rc = new RampartConfig();

      rc.setUserCertAlias("wso2carbon");
      rc.setEncryptionUser("wso2carbon");
      rc.setPwCbClass(SecureClient.class.getName());

      CryptoConfig sigCryptoConfig = new CryptoConfig();

      sigCryptoConfig.setProvider("org.apache.ws.security.components.crypto.Merlin");

      Properties prop1 = new Properties();
      prop1.put("org.apache.ws.security.crypto.merlin.keystore.type", "JKS");
      prop1.put("org.apache.ws.security.crypto.merlin.file", "/home/charitha/products/wsas/wso2wsas-3.1.3/resources/security/wso2carbon.jks");
      prop1.put("org.apache.ws.security.crypto.merlin.keystore.password", "wso2carbon");
      sigCryptoConfig.setProp(prop1);

      CryptoConfig encrCryptoConfig = new CryptoConfig();
      encrCryptoConfig.setProvider("org.apache.ws.security.components.crypto.Merlin");

      Properties prop2 = new Properties();

      prop2.put("org.apache.ws.security.crypto.merlin.keystore.type", "JKS");
      prop2.put("org.apache.ws.security.crypto.merlin.file", "/home/charitha/products/wsas/wso2wsas-3.1.3/resources/security/wso2carbon.jks");
      prop2.put("org.apache.ws.security.crypto.merlin.keystore.password", "wso2carbon");
      encrCryptoConfig.setProp(prop2);

      rc.setSigCryptoConfig(sigCryptoConfig);
      rc.setEncrCryptoConfig(encrCryptoConfig); 

Next, we can add the above rampartConfig to the service policy derived from the wsdl as follows.

       Map endPoints = dynamicClient.getAxisService().getEndpoints();
       AxisBinding axisBinding = ((AxisEndpoint) endPoints.values().iterator().next()).getBinding();
       Policy policy = axisBinding.getEffectivePolicy();
       policy.addAssertion(rc);
       axisBinding.applyPolicy(policy); 

Now, we can invoke the service using dynamicClient by passing the parameters as an object array and return types as an class array.

Object[] returnArray = dynamicClient.invokeBlocking(new QName("http://www.wso2.org/types", "greet"),
                new Object[]{"hello"}, new Class[]{String.class});

        System.out.println(returnArray[0]); 

Thats all! To complete our scenario, make sure to have callback handler method similar to the one below.

public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {

        WSPasswordCallback pwcb = (WSPasswordCallback) callbacks[0];
        String id = pwcb.getIdentifer();
        if ("wso2carbon".equals(id)) {
            pwcb.setPassword("wso2carbon");
        }

How to configure persistent RM in WSO2 WSAS

WSO2 Web Services Application Server (WSAS) provides with a storage manager in which you can persist messages transmitted between RMS (reliable messaging source) and RMD (reliable messaging destination). By configuring persistent RM, you can prevent messages loses even if the server is down. This post guides you through the steps to configure persistent RM in the latest versions of WSO2 WSAS (WSAS-3.*). I assume you have a basic understanding about WS-RM, if not, please read http://www.infoq.com/articles/fremantle-wsrm-introduction first.
Pre-requisites
Download and install WSO2 WSAS-3.1.1

Persistent implementation of WS-RM will be supported in most of the popular DBMSs. However, I will use MySQL server 5.* in this demonstration. Therefore, install and configure MySQL.

Step 1
As the first step, we need to create the persistent storage which is going to be used in reliable message transmission. Lets create a data base and the necessary table as follows.

mysql>create database SANDESHA_DB;


mysql>use SANDESHA_DB;


mysql>create table wsrm_sender (
message_id varchar(255) not null,
message_context_ref_key varchar(255),
internal_sequence_id varchar(255),
sequence_id varchar(255),
to_address varchar(255),
inbound_sequence_id varchar(255),
send smallint,
sent_count integer,
message_number bigint,
resend smallint,
time_to_send bigint,
message_type integer,
last_message smallint,
inbound_message_number bigint,
transport_available smallint,
flags integer,
primary key (message_id)
);

mysql>create table wsrm_rmd (
sequence_id varchar(255) not null,
to_epr_addr varchar(255),
to_epr blob,
reply_to_epr_addr varchar(255),
reply_to_epr blob,
acks_to_epr_addr varchar(255),
acks_to_epr blob,
rm_version varchar(255),
security_token_data varchar(255),
last_activated_time bigint,
closed smallint,
terminated_flag smallint,
polling_mode smallint,
service_name varchar(255),
flags integer,
reference_message_key varchar(255),
highest_in_message_id varchar(255),
last_in_message_id varchar(255),
server_completed_messages blob,
outof_order_ranges blob,
to_address varchar(255),
outbound_internal_sequence varchar(255),
next_msgno_to_process bigint,
highest_in_message_number bigint,
rmd_flags integer,
primary key (sequence_id)
);

mysql>create table wsrm_rms (
create_seq_msg_id varchar(255) not null,
sequence_id varchar(255),
to_epr_addr varchar(255),
to_epr blob,
reply_to_epr_addr varchar(255),
reply_to_epr blob,
acks_to_epr_addr varchar(255),
acks_to_epr blob,
rm_version varchar(255),
security_token_data varchar(255),
last_activated_time BIGINT,
closed smallint,
terminated_flag smallint,
polling_mode smallint,
service_name varchar(255),
flags integer,
id bigint,
internal_sequence_id varchar(255),
create_sequence_msg_store_key varchar(255),
reference_msg_store_key varchar(255),
last_send_error blob,
highest_out_relates_to varchar(255),
client_completed_messages blob,
transport_to varchar(255),
offered_endpoint varchar(255),
offered_sequence varchar(255),
anonymous_uuid varchar(255),
last_send_error_timestamp bigint,
last_out_message bigint,
highest_out_message_number bigint,
next_message_number bigint,
terminate_added smallint,
timed_out smallint,
sequence_closed_client smallint,
expected_replies bigint,
soap_version integer,
termination_pauser_for_cs smallint,
avoid_auto_termination smallint,
rms_flags integer,
primary key (create_seq_msg_id)
);

mysql>create table wsrm_invoker (
message_context_ref_key varchar(255) not null,
sequence_id varchar(255),
context blob,
msg_no bigint,
flags integer,
PRIMARY KEY (message_context_ref_key)
);

mysql>create table wsrm_msgctx (
ctx_key varchar(255) not null,
ctx blob,
PRIMARY KEY (ctx_key)
);

Note: From WSAS-3.2.0 onwards, the following columns must be added to the wsrm_rms table in addition to the columns specified above.

offered_endpoint_epr_addr varchar(255),
offered_endpoint_epr varchar(255),
reallocated integer,
internalSeqIDOfSeqUsedForReallocation varchar(255),

Step 2

Since we are going to establish a JDBC connection to a MySQL DB, copy mysql jdbc driver to WSAS_HOME/repository/components/lib and restart WSAS
Log in to WSAS management console and click on modules -->list. Click on configure link of the sandesha2 module.
By default, WSO2 WSAS uses an inmemory implementation of WS-RM. You can change it to persistent by changing Storage Manager property. Configure the rest of the persistent storage details as follows.

Connection String - jdbc:mysql://localhost:3306/SANDESHA_DB
Driver Name - com.mysql.jdbc.Driver
Username - your mysql username 
Password - your mysql password

Step 3

Now, you have enabled persistent RM in WSO2 WSAS. However, due to a bug in the latest WSAS releases, you should update the following property in WSAS_HOME/conf/axis2.xml

<parameter name="Sandesha2StorageManager">persistent</parameter>

Make sure to restart WSAS after configuring the above element in axis2.xml

Step 4

Now, you are ready to send requests to a service hosted in WSAS through RM and verify persistent RM. In order to do that, engage sandesha2 module in a service and send series of requests (say 100 requests) using a RM client (I assume you are familiar with sending soap messages with RM headers. I will publish a separate post on complete RM client-server invocation soon). After transmitting 30 requests, shutdown WSAS and restart. You will notice that after the server is restarted, the message transmission will be resumed from the message no: 31

If you have any issues with the steps given above, please drop me a mail.

How to run multiple WSO2 WSAS instances in a single host

I have published a simple three step tutorial on running multiple WSO2 WSAS instances in a single host in WSO2 Oxygen Tank. Have a look!

How to enable JMS in WSO2 WSAS-3.*

WSO2 WSAS provides with a simple and easily configurable UI to enable transports. In this post, we are going to look at how JMS is enabled in WSAS-3.* versions.

Pre-requisites:
----------------
You can use any JMS provider as you preferred. I'm going to use Apache ActiveMQ-5.2.0 for this example.
Download the latest version of WSO2 WSAS from here

Step 1
-------
Suppose you have downloaded WSO2 WSAS-3.* and extracted in to a directory in your file system. Let it be WSAS_HOME

First, we need to start ActiveMQ message broker. Go to ActiveMQ_Install_dir/bin and run activemq.bat
Also, the following ActiveMQ libraries must be copied to WSAS_HOME/repository/components/lib directory

• activeio-core-3.1-SNAPSHOT.jar (ActiveMQ_Install_dir\lib\optional)
  
• activemq-core-5.0.0.jar (ActiveMQ_Install_dir\lib\)
• geronimo-j2ee-management_1.0_spec-1.0.jar (ActiveMQ_Install_dir\lib\)
• geronimo-jms_1.1_spec-1.0.jar (ActiveMQ_Install_dir\lib\)

Now, restart WSO2 WSAS

Step 2
-------
Log in to WSAS management console (username=admin, password=admin) and click on Manage --> Transports at the left navigation menu.
You will be directed to the Transport Management page as follows.



Step 3
-------
Locate JMS transport in the above Transport Management page and click on enable next to transportListener
Following page will be shown where you can configure JMS listener according to your JMS provider.



similarly, you can enable JMSSender.

If JMS is configured correctly as in the above steps, you will see the JMS endpoints of your service will be shown in the WSDLs or service dashboard as follows.

Where to put third party jars in WSO2 WSAS?

In the pre-carbon versions of WSO2 WSAS (2.* and older), you may have used WSAS_HOME/lib/extensions directory to put third party jars such as jdbc drivers.

After WSO2 WSAS became a part of WSO2 Carbon platform, a.k.a WSAS-3.* versions, all third party jars should be placed inside WSAS_HOME/repostiroy/components/lib directory of your WSAS distribution.

**This is applicable to all WSO2 Carbon products (WSAS, ESB, G-reg, IS, BPS)

How to deploy WSAS-3.X on Oracle WebLogic 10.3

WSO2 DOES NOT ENCOURAGE INSTALLING WSO2 APPLICATION SERVER (previously known as WSAS) ON TOP OF OTHER APPLICATION SERVERS. WSO2 HAS DECIDED TO DROP SUPPORT FOR WEBAPP DEPLOYMENT MODE OF THE WSO2 PLATFORM AND PRODUCTS.






Once Azeez has written a 10 minute guide to installing WSO2 WSAS on Weblogic server. That guide explains the steps to deploy 2.X family of WSAS on weblogic. With the introduction of WSO2 Carbon platform in December 2008, WSO2 WSAS is no longer distributed as a separate war distribution. Hence, the instructions given in that document is not applicable when deploying WSO2 WSAS-3.X series on Oracle WebLogic server.
Since all WSO2 java products are built on Carbon platform, users can configure running WSO2 products on any application server using a set of components included in binary distributions. I have already explained the steps to deploy WSO2 BPS on tomcat and WSO2 WSAS-3.X on Jboss.

This post describes the steps to deploy WSO2 WSAS-3.X on WebLogic 10.3

Step1

Create a new weblogic domain by running config.sh {bat} located at WebLogic_HOME/wlserver_10.3/common/bin directory.
Lets assume the new domain is wsas.

Access your weblogic domain direcrtory and start weblogic (Go to WebLogic_HOME/user_projects/domains/wsas/bin and run startWebLogic.cmd)

Step 2
Download the latest version of WSO2 WSAS-3.X from here. Extract the downloaded zip into a directory. Copy conf, database, repository and resources directories in to a new folder. Here after, we will refer it is wsas-repo (i.e:- C:\wsas\wsas-repo)

Also, create a new directory, wso2wsas and copy the WEB-INF directory located at the webapps/ROOT directory of the downloaded WSO2 WSAS-3.X to wso2wsas directory. Now, your wsas-repo should have five sub directories - conf, database, repository, resources and wso2wsas.
wso2wsas will be used as the webapp root directory.

Step 3

We need to enable SSL in weblogic server. Log in to weblogic administration console (You should have configured username and password for admin console when creating your WebLogic domain) and go to Environment --> servers. Select AdminServer.
Click on KeyStores tab. Configure keystores as shown below.



Keystore = Custom Identity & Custom Trust


Custom Identity Keystore = C:\wsas\wsas-repo\resources\security\wso2carbon.jks

Custom Identity Keystore Type = JKS

Custom Identity Keystore Passphrase = wso2carbon

Confirm Custom Identity Keystore Passphrase = wso2carbon

Custom Trust Keystore = C:\wsas\wsas-repo\resources\security\wso2carbon.jks

Custom Trust Keystore Type = JKS

Custom Trust Keystore Passphrase = wso2carbon

Confirm Custom Trust Keystore Passphrase = wso2carbon

Now, select SSL tab and enter the following values.

Identity and trust locations = keystores

Private Key Alias = wso2carbon

Private Key Passphrase = wso2carbon

Confirm Private Key Passphrase = wso2carbon


Save the configuration and go to the General tab. Select the check box next to "SSL listen port enabled".

Now we have configured the necessary changes to enable SSL on weblogic. Lets continue with deploying WSO2 WSAS on weblogic.

Step 4

Now, we should update the set of config files shipped with WSO2 WSAS. We will update carbon.xml, axis2.xml, registry.xml and user-mgt.xml which can be found at the above wsas-repo\conf directory.
First, open carbon.xml and update the ServerURL element as follows.

<ServerURL>https://localhost:7002/wso2wsas/services/</ServerURL>

Note that we have configured weblogic to run on 7002 port.

Update WebContextRoot element as follows.

<WebContextRoot>/wso2wsas</WebContextRoot>

Save and close carbon.xml.

Open registry.xml and update DB URL as follows.

<url>jdbc:h2:C:\wsas\wsas-repo\database\WSO2CARBON_DB;create=true</url>

Now, open user-mgt.xml and update database URL as follows.

<url>jdbc:h2:C:\wsas\wsas-repo\database\WSO2CARBON_DB;create=true</url>

Make sure to specify the absolute path of the WSO2CARBON_DB in both of the above elements.

We must change the http and https ports in In Transports section of axis2.xml as follows.

<transportReceiver name="http"
class="org.wso2.carbon.core.transports.http.HttpTransportListener">
<parameter name="port">7001</parameter>

</transportReceiver>

<transportReceiver name="https"
class="org.wso2.carbon.core.transports.http.HttpsTransportListener">

<parameter name="port">7002</parameter>
</transportReceiver>

Step 5

We have completed the required configurations and we can deploy WSO2 WSAS on weblogic now.
First, shutdown the weblogic server instance if it is still running.
open a new command window and change the directory to WebLogic_HOME/user_projects/domains/wsas/bin.
Define an environment variable called CARBON_HOME and set the path to your wsas-repo directory.

In windows; set CARBON_HOME=C:\wsas\wsas-repo
In linux; export CARBON_HOME=\home\user\wsas\wsas-repo

Run startWebLogic.cmd

Once the server is started successfully, log in to weblogic administration console using https://localhost:7002/console
Then, go to the Summary of Deployments page and select Install.
Locate the deployment root by selecting C:\wsas\wsas-repo\wso2wsas directory. (web app root directory will be shown with a radio button option as follows.



Click on next to proceed through the wizard and continue with the default settings.
Once the deployment is successful, save the configuration and select start --> servicing all requests

Now, we are done with the deployment. You could access the management console using https:\\localhost:7002\wso2wsas\carbon

Note:-
1. In order to set the log4j logs, you may copy log4j.properties file in the extracted WSO2WSAS-3.X directory to wsas-repo\wso2wsas\WEB-INF\classes

2. If you want to deploy JaxWS services in WSAS/WebLogic platform, you should do the following configuration to avoid a class casting issue (https://wso2.org/jira/browse/CARBON-4835)

- Remove weblogic.jar/META-INF/services/com.sun.xml.ws.api.wsdl.writer.WSDLGeneratorExtension & restart Carbon

3. Also, Make sure to copy xalan-*.jar, xercesImpl-*.jar and xml-apis-*.jar from the lib/endorsed directory of the extracted WSAS binary distribution to weblogic endorsed directory before you start WSAS.

Domain hosting

How to deploy WSO2 WSAS-3.* on JBoss

WSO2 DOES NOT ENCOURAGE INSTALLING WSO2 APPLICATION SERVER (previously known as WSAS) ON TOP OF OTHER APPLICATION SERVERS. WSO2 HAS DECIDED TO DROP SUPPORT FOR WEBAPP DEPLOYMENT MODE OF THE WSO2 PLATFORM AND PRODUCTS.





WSO2 WSAS can be deployed on most of the application servers with a simple set of configuration steps. This post describes the steps to deploy WSO2 WSAS-3.* on JBOSS 5.*


Step 1
Download WSO2 WSAS-3.0.1 from here. Extract the downloaded zip into a directory. Copy conf, database, repository and resources directories in to a new folder. Here after, we will refer it is wsas-repo (i.e:- C:\wsas\wsas-repo)

Step 2
Lets refer to your jboss installation directory, JBOSS_HOME. Go to JBOSS_HOME\server\default\deploy directory and create a new folder, wso2wsas.war.
Now, copy wso2wsas-3.0.1\webapps\ROOT\WEB-INF to JBOSS_HOME\server\default\deploy\wso2wsas.war

Step3
We need to enable https in JBOSS. Therefore, edit JBOSS_HOME\server\default\deploy\jbossweb.sar\server.xml by editing the following entry. (This entry is commented out by default)

<!-- SSL/TLS Connector configuration using the admin devl guide keystore-->
<Connector protocol="HTTP/1.1" SSLEnabled="true"
port="8443" address="${jboss.bind.address}"
scheme="https" secure="true" clientAuth="false"
keystoreFile="C:\wsas\wsas_repo\resources\security\wso2carbon.jks"
keystorePass="wso2carbon" sslProtocol = "TLS" />

Make sure to give the exact location of wso2carbon.jks as highlighted above.

Step 4

We have done the configurations required inJBoss. Now, we must do the necessary configurations in a set of config files shipped with WSO2 WSAS. We will update carbon.xml, axis2.xml, registry.xml and user-mgt.xml which can be found at wsas-repo\conf directory.
First, open carbon.xml and update the ServerURL element as follows.

<ServerURL>https://localhost:8443/wso2wsas/services/</ServerURL>

Note that we have configured tomcat to run on 8443 port.
Save and close carbon.xml.

Open registry.xml and update DB URL as follows.
<url>jdbc:derby:C:/wsas/wsas-repo/database/WSO2CARBON_DB;create=true</url>

Now, open user-mgt.xml and update database URL as follows.

<url>jdbc:derby:C:/wsas/wsas-repo/database/WSO2CARBON_DB;create=true</url>

Make sure to specify the absolute path of the WSO2CARBON_DB in both of the above elements.

It is required to change the contextRoot in the service path of axis2.xml. Change it to wso2wsas.

<parameter name="contextRoot">/wso2wsas</parameter>

We must change the http and https ports in In Transports section of axis2.xml as follows.

<transportReceiver name="http"
class="org.wso2.carbon.core.transports.http.HttpTransportListener">
<parameter name="port">8080</parameter>

</transportReceiver>

<transportReceiver name="https"
class="org.wso2.carbon.core.transports.http.HttpsTransportListener">

<parameter name="port">8443</parameter>
</transportReceiver>

Step 6

We have completed the required configurations. Now, open a new command window and change the directory to JBOSS_HOME/bin.
Define an environment variable called CARBON_HOME and set the path to your wsas-repo directory.

In windows; set CARBON_HOME=C:\wsas\wsas-repo
In linux; export CARBON_HOME=\home\user\wsas\wsas-repo

Start JBoss from the same command window/shell.

WSO2 WSAS will be started successfully. You can access the management console using https:\\localhost:8443\wso2wsas\carbon

How to deploy a Java web service on WSO2 WSAS and secure it with Username token policy

I demonstrate how to deploy a java web service on WSAS and secure it with user name token policy.

Adding BPEL features to WSO2 WSAS/ESB

A few days back, WSO2 has released carbon feature packs which allow users to integrate various functional components into their existing WSO2 products. I blogged about plugging in service hosting components into ESB while we were preparing for carbon release. With the carbon feature packs, now it is much more easier to add the functionalities what you want.

WSO2 BPS provides the facilities to execute business processes written using the WS-BPEL standard. BPEL feature pack enables the business process management inside your WSO2 WSAS or ESB instances.
Let's see how BPEL features can be added to WSO2 WSAS or ESB.

Pre-requisites:
Install WSO2 WSAS-3.0.1 or WSO2 ESB-2.0.1

Step 1
We are hoping to install BPEL features into WSAS or ESB. Therefore, download BPEL feature pack from here.

Step 2
Unzip the downloaded feature pack into a directory in your file system (suppose it is $BPEL_feature_pack_home)
You will see two sub directoris inside the extracted zip file, plugins and repository.

Go to $BPEL_feature_pack_home/plugins/ directory and copy all the jars to WSAS_HOME/webapps/ROOT/WEB-INF/plugins/ directory. (WSAS_HOME is the root directory of your WSO2 WSAS instance)

Then, go to $BPEL_feature_pack_home/repository directory and copy the contents to WSAS_HOME/repository.

Step 3
Restart WSO2 WSAS and access management console. You will see the BPEL features shown in the left menu as follows.



Thats it. We have installed BPEL features into WSAS. You could follow the same steps to install BPEL features into WSO2 ESB.

Get your Axis2 service or module archives validated using WSO2 tools

When creating Axis2 service archives (AARs) or module archives (MARs), it is important to adhere to the defined archive structure and standards. With the help of automated tools, you can validate these archives. WSO2 service and module validators can be used to validate your service or module archives freely in an efficient manner.
These tools are shipped as components inside WSO2 WSAS and hosted in WSO2 Oxygen tank developers portal as well.

If you have WSO2 WSAS binary distribution, validating aar or mar files is a simple process as given below.

1. Access WSAS management console using http://localhost:9443/carbon
2. Select Service Validator in the left menu



3. Select your axis2 service archive (aar file) and click on Validate AAR
4. Validation report will be shown as given below.



If WSAS binary distribution is not available, you can get your service or module validated using the online validator hosted in WSO2 Oxygen tank.

1. Go to http://wso2.org/tools
2. Click on Service Validator link under Validators section

you will be directed to the above AAR validator UI where the service archive can be validated.

Similarly, module archives (MARs) as well as service and module descriptors (services.xml. modules.xml) can be validated.

New look of WSO2 WSAS SOAP Message Tracer

Soap Tracer may not be a strange tool if you are familiar with WSO2 Web Services application server (WSAS). However, you will notice a new look and improved graphical representation of SOAP messages in Soap Tracer shipped with WSAS 3.0.
You will experience the difference with the newly released WSAS-3.0-beta1

- Download and unzip the binary distribution
- Log in to management console with user name and password, admin/admin
- Select Soap Message Tracer in the left menu
- Change the status to ON
- Invoke a service (Simply run tryit with the default HelloService)
- Go back to Soap Message Tracer and see the request and soap messages

How to use jconsole to monitor and manage WSO2 WSAS

Service or system monitoring and management are essential components of any SOA framework. WSO2 WSAS provides two different mechanisms to manage and monitor web services.
1. Ajax based GUI console
2. JMX based monitoring facility

In this post, I'm going to demonstrate the second option, JMX based service and system monitoring component. You can find more information about WSAS GUI console from here.

JMX (Java Management Extension) provides a set of tools and APIs for applying a standard client/server-based architecture to monitoring and management of a Java application.
J2SE version 5.0 adds core support for the Java Management Extensions (JMX) into the Java standard libraries. We are going to use Jconsole, included in jdk1.5 or newer versions, to explore the management and monitoring capabilities provided by WSO2 WSAS.

Pre-Requisites

Download and install WSO2 WSAS-2.2.1 or later

Step 1

JMX port is disabled by default in WSAS. Open WSO2WSAS_HOME/conf/server.xml and uncomment the following element.

<!--The JMX Port-->
<JMX>9999</JMX>

Step 2

Start WSO2 WSAS (run wso2wsas.bat or sh).

Make a note of the JMX url which will be printed on server startup console
i.e:- JMX Service URL : service:jmx:rmi:///jndi/rmi://YourHost:9999/server

Step 3

Start command prompt (or shell in linux), type Jconsole and hit enter. JConsole:Connect to Agent window will be popped up.



Enter JMX url (service:jmx:rmi:///jndi/rmi://YourHost:9999/server)
Enter admin as user name and password. Note that, any user with admin privileges can log in to JMX.
Click on Connect.

You will be directed to the summary page of Jconsole as follows.



Step 4

Click on MBeans tab. You will see the Mbeans tree in the left pane. Select org.wso2.wsas MBean.
ServerAdmin, ServiceAdmin and StatisticsService MBeans will be listed there.
Select ServerAdmin.



You will see shutdown, restart, restartGracefully, shutdownGracefully, startMaintenance and endMaintenance administrative functions when clicking on Operations tab in the above screen.

Step 5

We observed a few administrative function of WSo2 WSAS which were exposed through JMX in the above step. Lets see how service statistics are monitored using Jconsole.

Click on StatisticsService Mbean at the left pane. Next, select Operations tab.
Following screen will be displayed.



In order to check service statistics, we must invoke a service deployed on WSAS. Open your browser and enter the following URL.
http://localhost:9762/services/version/getVersion
This will send a HTTP GET request to the default Version service.

Now enter 'version' as the value of the getServiceRequestCount operation in above screen and click on getServiceRequestCount.
You will get '1' as the response.



Invoke Version service a few more times (just send http GET requests using the above URL).
Enter 'version' as parameter 1 (p1) and 'getVersion' as parameter 2 (p2) of getOperationRequestCount operation.
You will see a operation return value similar to the one bwlow.



Now, you will be able to proceed with more operations and get the statistics of server and system status.

How to avoid "java.security.InvalidKeyException:illegal Key Size" error when invoking secured services in WSO2 WSAS

"java.security.InvalidKeyException:illegal Key Size" error is a common issue which occurs when you try to invoke a secured web service in an environment where the provision for java unlimited security jurisdiction is not done.
This can be avoided by installing Java Cryptography Extension (JCE) unlimited strength jurisdiction policy files.

1. Suppose you are using jdk15. Go to http://java.sun.com/javase/downloads/index_jdk5.jsp

2. Go to the Other Downloads section and click on download link next to "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 5.0"

3. Download jce_policy-1_5_0.zip and extract it in to a directory.

4. You will find local_policy.jar and US_export_policy.jar files there in the extracted directory. Copy these two files to $JAVA_HOME/jre/lib/security directory. (These files will already be there. you may replace them)

5. Restart WSO2 WSAS and invoke your secured service again. You will not encounter the "invalidkeyException" any more.

WSDL2Code UI tool - Easy and efficient code generation utility

If you are an Apache axis2 user, you may already familiar with WSDL2Java code generation tool. WSO2 WSAS is powered by Apache Axis2 and includes a rich set of features to interact with web services. WSDL2Code is a UI based tool integrated with WSO2 WSAS which allows users to generate code from a WSDL hosted in a remote server or a local file system.
Lets see how WSDL2Code tool makes web service developement effort much easier and productive.

Step 1
Download and Install WSO2 WSAS

Step 2
Start wso2wsas. Go to WSAS_HOME/bin and run wso2wsas.bat{sh}

Step 3
Go to http://localhost:9762
Welcome page of the WSAS console will be displayed. Click on WSDL2Code at the left navigation menu. You will be directed to the following screen.



You can see multiple code generation options in the above screen. These code gen options are similar to the command line options available in WSDL2java tool.

Step 4
Lets generate client stub against default version service using the above tool.
Enter 'http://localhost:9762/services/version?wsdl' in the -uri option available on the top of the page.
Select -uw option and click on 'Generate'
It will prompt to save the generated zip file (e.g:- 1.2151049949841125E12.zip). Save it in a directory in your local file system.

Step 5
Unzip the generated file (You will see src folder, build.xml and pom.xml in the extracted directory) and go to the directory where you extracted the zip file.
Assuming your IDE is eclipse, enter the following command to export the generated code in to eclipse and setting up WSAS libraries at once.

mvn eclipse:eclipse

(If you have not installed maven2, download it from here and add maven_home/bin to your PATH)

You will see 'BUILD SUCCESSFUL' message at the end of executing above command.

Step 6
Open eclipse and go to Window-->Preferences-->Java-->Build path-->Classpath variables
Create a new variable, M2_REPO and enter your maven2 repository path as the value. (maven2 repository is located at user home directory. e.g:- C:/Documents and Settings/Charitha/.m2/repository)
(Note that this step has to be done only once. If the M2_REPO variable is already defined, you can ignore this step)

Step 7
In eclipse, select File-->import-->Existing projects into workspace-->next
Browse root directory of the extracted zip file above. Click 'Finish'.
New project will be added to the workspace with an id like N10001-version. You should see that all the necessary WSAS libraries are added to the project.

Now the only remaining step is to write client to invoke version service as follows

public class VersionClient {

public static void main(String[] args)throws Exception {
VersionStub stub = new VersionStub();
System.out.println(stub.getVersion());
}

}

You may realize how WSO2 WSAS reduce the complexity of web service invocation with these kind of tools. Even if you are beginner to the world of SOA, WSO2 WSAS can be considered as the best paltform to get started with minimum effort.

WS-Reliable Messaging with WSO2 WSAS - II

This is the part two of my previous post on WS-Reliable messaging with WSO2 WSAS - 1
I'd suggest you to follow the steps given in there before proceeding with this.

We looked at how WSO2 WSAS and WSO2 Mercury module are used in one-way (IN-ONLY) message interaction in reliable manner. In this post I'll explain the procedure to do the same with Request Reply(IN-OUT) messaging system using single transport channel.

Step 1

Follow the step 1 - Service Configuration and step 2 - Generate stubs of part one of this post with the service implementation class given below.

package org.wso2.wsas.service;
public class MercuryService{

//Twoway messaging
public int Add(int a, int b){

try {
Thread.sleep(3000);
} catch (InterruptedException e) {
e.printStackTrace();
}
return a+b;
}
}

Note that I inserted a Thread.sleep() in service to wait ~3 seconds before returning results so that we may have enough time to block the transport channel when testing reliable message transmission.

Step 2

If you have followed the step 1 and step 2 exactly as given in part 1 of this post by just replacing service impl. class with the above, you should be able to continue with the client as given below.

Open your IDE and write the following client to invoke service with RM.
Make sure to add jars in WSAS_HOME/lib and the generated client stub jar to your class path in order to compile the client.

public class RequestReplyAnnonClient{

public static void main(String args[])throws AxisFault{

ConfigurationContext cc = ConfigurationContextFactory.createConfigurationContextFromFileSystem
("C:\\RM\\client-repo"+"C:\\RM\\client-repo\\conf\\axis2.xml");

MercuryServiceStub stub = new MercuryServiceStub(cc);
MercuryServiceStub.Add request = new MercuryServiceStub.Add();
request.setA(12);
request.setB(8);

stub._getServiceClient().engageModule("Mercury");

for (int i = 0; i < 29; i++) {
try {
//Two-way invocation
MercuryServiceStub.AddResponse response = stub.Add(request); System.out.println(response.get_return());
} catch (RemoteException e) {
e.printStackTrace();
} try
{
Thread.sleep(1000);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
// Setting the last message stub._getServiceClient().getOptions().setProperty("MercuryLastMessage", Constants.VALUE_TRUE);
try {
MercuryServiceStub.AddResponse response = stub.Add(request); System.out.println(response.get_return());
} catch (RemoteException e) {
e.printStackTrace();
} try
{ Thread.sleep(1000);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
In order to have the reliable messaging support at the client, we need to engage Mercury module with "stub._getServiceClient().engageModule("Mercury")". We also need to have ConfigurationContext to define the client repository where the Mercury.mar and axis2 configuration file (axis2.xml) is placed. Create a directory, client-repo and copy WSAS_HOME/repository/modules/mercury.mar to client-repo/modules directory. Also, create a sub-directory conf under client-repo and copy an axis2.xml file ( I have used axis2.xml copied from Axis2-1.4) in to that folder. As in one-way scenario, we need to let Mercury know when we are complete. The simplest way to do this is to mark the LastMessage with stub._getServiceClient().getOptions().setProperty("MercuryLastMessage", Constants.VALUE_TRUE)

Step 3

Compile and run the client. You should configure tcpmon in order to monitor request and response messages.

You will notice that the first message travels through tcpmon contains <wsrm:CreateSequence> as the first first child of soap body. If the transport channel does not get blocked, CreateSequenceResponse message will be returned to client immediately.

You will see that <wsrm:MessageNumber>1</wsrm:MessageNumber> soap header element in the next message where the actual request payload is transmitted. The response of this message may include <wsrm:SequenceAcknowledgement> which denotes the ack to the first message. This will be continued until the last message in which the <wsrm:LastMessage /> as a header element could be seen. (In our test, the message number should be 30)
The end of whole sequence will be denoted by TerminateSequance message.

Lets check whether the reliability is actually provided by WSO2 mercury module when the transport channel is interrupted.

When the 3rd message is sent (Message number 3), click on "Stop" button of Tcpmon listen port. You will see the following in tcpmon.



This mimics the behavior of typical network interruption in data communication. Wait a few seconds and restart the listen port.



As you can see, the response of request message number 3 will be returned when the transport channel is restarted and continues with the rest of the messages. No messages are lost though the channel interruptions are occurred. All 30 messages will be delivered reliably even the network communication issues are occurred during message transmission.

We have looked at one of a basic tests which can be done in order to verify how WSO2 WSAS and mercury module provides reliable message delivery in web service communication. There are more. I'll discuss them in a future post.

Retrieving web service metadata using wso2-mex module

I have published a Knowledge base post at Wso2 oxygen tank which describes the procedure to retrieve web service metadata using wso2 WSAS and wso2-mex module .
You will find it useful since there are no much documents available on the web regarding ws-MEX (ws-MetaDataExchange) configuration and usage.