How to develop a JAX-WS service with WSO2 Developer Studio and deploy it in WSO2 API Manager

In this post I will show how to write a simple CXF based JAX-WS service using WSO2 Developer Studio and how to deploy it in WSO2 API Manager. My service will use API Manager carbon user store to get an email of a specific user.

Open Developer Studio dashboard (I’m using version 3.7.0). Under Create menu tab select JAX-WS Service Project:


Choose Create New JAX-WS Service and click Next:


Choose a project name, package and class name for your service and click Next:


Adjust project maven info if necessary and click Finish:


Notice in your project that there is an automatically generated  service class with a sample method and necessary annotations. All you need is add your methods and their implementation. You can read more about how to use jax-ws annotations here. In short, only @WebService annotation is required, because it marks which Java class needs to be exposed as a web service. All the other annotations are optional and can be used to customize the wsdl file of the web service.

Here is the code of my implementation:

Now, some basics about exception handling using JAX-WS. As you can see in my code there is a custom exception thrown from getEmail() method when something goes wrong. To be in compliance with JAX-WS specification a custom exception must:

  • extend java.lang.Exception class and be annotated with @WebFault;
  • use a fault bean to store the error message;
  • implement following constructors and methods:
    • WrapperException(String message, FaultBean faultInfo) A constructor where WrapperException
      is replaced with the name of your custom exception and FaultBean is replaced by the
      name of your fault bean.
    • WrapperException(String message, FaultBean faultInfo, Throwable cause) A constructor
      where WrapperException is replaced with the name of your custom exception and FaultBean
      is replaced by the name of your fault bean.
    • FaultBean getFaultInfo() Getter to obtain the fault information, where FaultBean is replaced by the
      name of your fault bean.

Here is an example of MyException class compliant with JAX-WS spec:

The fault bean is a POJO:

In my implementation of the service I’ve used a data source to access carbon user store, which I have exposed as a global JNDI resource. To register a JNDI resource globally(it means the resource will be visible to all webapps deployed in the server) do the following steps:

1. Place resource in <APIM_HOME >repository/conf/tomcat/catalina-server.xml:

2. Link the resource in <APIM_HOME >repository/conf/tomcat/context.xml:

3. Put a reference to your resource in <APIM_HOME >repository/conf/tomcat/web.xml:

To use the data source from you application, copy the code from getDataSource() method of my implementation.

If you have dependencies in your project, you can add the jars in WEB_INF/lib directory of your project. You can optionally add them in the cxf environment directory of the API Manager( <APIM_HOME>/lib/runtimes/cxf) if your app is deployed in cxf environment. You can read more about product environments and their configuration here.

You can now export your project as deployable file. Right-click on the project, select Export Project as Deployable Archive and choose destination location:


To deploy your JAX-WS service in the WSO2 API Manager go to API Manager management console. Under Applications select JAX-WS/JAX-RS and upload the archive you have exported in the previous step:


To test your service you can use the Tryit WSO2 Carbon feature. Under Applications select List and click on the name of your webapp. This will open Application Dashboard page of your web service:


As you can see, the wsdl of your web service is also available on this page.

Author: Renata



Curious to know more about this topic?

Working at i8c

i8c is a system integrator that strives for an informal atmosphere between its employees, who have an average age of approx 30 years old. We invest a lot of effort in the professional development of each individual, through a direct connection between the consultants and the management (no multiple layers of middle management). We are based in Kontich, near Antwerp, but our customers are mainly located in the triangle Ghent-Antwerp-Brussels and belong to the top 500 companies in Belgium (Securex, Electrabel, UCB, etc…).

Quality Assurance

i8c is committed to delivering quality services and providing customer satisfaction. That’s why we invested in the introduction of a Quality Management System, which resulted in our ISO9001:2000 certification. This guarantees that we will meet your expectations, as a reliable, efficient and mature partner for your SOA & integration projects.

i8c - ISO9001-2015

Also worth reading

Apigee Scope Validation using OpenAPI Specification

In API security and management, we often use a lot of different security mechanisms to protect the requested resource behind the API Gateway. One of these mechanisms is the validation of scopes to authorize a client on a specific sub-resource of the API. Most of

Read More »

Integrating with TIBCO CLOUD

Our experts Glenn, Jason, Jurgen, and Kevin dedicated an i8c FastTrack Day to examining the TIBCO iPaaS offering. Check out their Research & Development day report to learn what they uncovered. 👇  TIBCO CLOUD™ The TIBCO Cloud™ Integration enterprise integration platform-as-a-service (iPaaS) provides self-service integration

Read More »