How to consume admin services in WSO2 Carbon with your own front end.

WSO2 Carbon is a OSGI based middle ware platform which powers the WSO2 products such as WSO2 Application server, WSO2 ESB, etc. In other words, Carbon provides core functionalities such as user management, feature management, registry services, etc which are essential part of any product. Product themselves add their unique behaviour via specific features (bundles).

The Carbon platform consists of a front-end and a back-end. In its most simplest deployment scenario you can deploy any carbon based WSO2 product  in a single web container such as Apache Tomacat. But its architecture allows you to deploy its front end as a separate web-app. This facility is immensely useful if you are working multiple instances of the product. Instead of having a separate front end for each and every instance you can use only one front-end to control all the deployed back-ends. The figure below gives a high level view of the carbon platform.

During a feature development for the WSO2 Carbon, I wanted to give some customized web services calls to the back end server. Since the existing management console does not have the functionality that I'm testing I had to write some code to give my own web service calls. Nothing new; just web services calls. Here I'm documenting my effort.

Running the WSO2 carbon in Standalone mode.

Download the binary distribution of Carbon from the project home, unzip it to your local file system. Root directory of the unzipped carbon directory is the CARBON_HOME. Open up a shell and within the $CARBON_HOME/bin , run the server as,

$> ./wso2server.sh

Log in to the system by giving the username and password (default being admin for both). You should see the bare bones carbon platform with the user manager and the feature manager.

Carbon admin services

The Carbon admin services are not visible via the Carbon management console. You can access the service description of the admin services if you know the admin service. Here I'm accessing the URL assuming that the default https port in carbon (9443).

> https://localhost:9443/services/AuthenticationAdmin?wsdl

  

Before accessing any other Admin services we have to get the credentials by authenticating ourselves via the Admin service. Then we can use the token to authenticate ourselves while accessing other admin services.

Generating code for the admin services

we have to generate the client stubs to access the back end web-services. You can write your own web services clients using axis2 client API, but the wsdl2java tool hides all the complexity from the user and present you with a proxy to the back end service.

The stub generation happens during the project build process within the maven pom files. It uses the maven ant run plug in to execute the wsdl2java tool.

Accessing the Admin service and authenticating ourselves

we should provide the back end server URL , client trust store details in order to log in to the back end server via a web services. We use the session cookie returned by the service to authenticate ourselves in the following service calls.

1 // setting the system properties for javax.net.ssl
2         AuthenticationAdminServiceClient.setSystemProperties(SampleConstants.CLIENT_TRUST_STORE_PATH,
3                 SampleConstants.KEY_STORE_TYPE, SampleConstants.KEY_STORE_PASSWORD );
4         AuthenticationAdminServiceClient.init(authenticationAdminURL);
5         System.out.println("retrieving the admin cookie from the logged in session....");
6         adminCookie = AuthenticationAdminServiceClient.login(SampleConstants.HOST_NAME,
7                 SampleConstants.USER_NAME, SampleConstants.PASSWORD);

Accessing the Provisioning service and getting the list of installed features.

Then during the provisioning stub invocation we have to give the retrieved admin cookie with the its service URL. View the ProvisioningAdminService service descriptor by pointing your browser to: 

> https://localhost:9443/services/ProvisioningAdminService?wsdl

1 // initializing the provisioning admin client  using the cookie we got from the authentication client.
2         ProvisioningAdminServiceClient.init(provisioningAdmingServiceURL, adminCookie);
3         FeatureWrapper[] featureWrapper = ProvisioningAdminServiceClient.getInstalledFeatures();
4         System.out.println(" the installed feature list...");
5         for(FeatureWrapper fw :featureWrapper){
6             // getting the names of installed features..
7             System.out.println(fw.getWrappedFeature().getFeatureName() + "- -" + 
8                     fw.getWrappedFeature().getFeatureDescription());
9         }

Things to note

• we have to provide our client with Java key store files found under resources folder, inside CARBON_HOME.
• I have saved WSDL in the local file system, for code generation.
• The path the client trust-store is hard coded in the SampleConstatns.java file

The code I used to test the behaviour is attached with this blog post. Since it uses maven it should not be hard to create a IDE specific project files from the maven pom.xml files. :)

Summary

The Carbon architecture allows you to control the server back end with your own front end. This can be a web-console, standalone java-app, etc. Carbon is the base platform for all the wso2 server products. Hence the demonstrated approach hold true for any carbon based wso2 product.

Download the code for the carbon simple front end.