Sunday, July 29, 2012

Customizing WSO2 API Store/Publisher App-Part2

From the Part 1 of this tutorial[1], we discussed on overview of API-Store and its directory structure.This tutorial will be focus on the flow of how a user request is handle by API Store web-application front-end and a example to try out.

Browser Request Flow of the API-Store Front-end

Below image will explain the flow of browser request processing happened inside the API-Store jaggery application.Similarily API-Publisher jaggery application will also handle browser requests.
When a user access the API Store/Publisher application through the web-browser,that request will first hit on the relevant page located at 'site/pages' directory in API-Store/Publisher.Then inside that page,to handle the rendering of the web page,it'll call the render() function defined in jagg.jag file resides on location 'jagg/jagg.jag' inside the both applications.

To invoke that render() method,we are passing a json string which contains the base page name,page body layout name and sub layout blocks names[eg:In the below image we have set a sub layout block name called 'api/listing' to be set to the 'middle' section of the layout] and their corresponding inputs.Once render() method invoked by the web page;it first check whether the relevant blocks[in site/blocks directory] and templates[in site/themes/templates directory] for base page,page body layout and for sub layout blocks,exists.

If not processing will stop and rendering of web page also stopped.Else if the relevant blocks and templates exists,inputs passing for the render method(),will retrieved and processed by the relevant blocks and will pass the processed data to the relevant templates.From the relevant templates,html rendering will happened and the user will able to see the reqested web page will rendered in browser properly.


As you got a basic idea of what each directories doing in the API Store web application,now its time to get use of them with an example. To get a better idea of the flow on creating a new web page inside the API-Store application,below steps will explain how to add such a new page to the API-Store inorder to view created APIs per user.Sample code can be found from here.
  1. First Navigate to API-Store web-application code from [1] or simply navigate through the API Manager binary pack as {API Manager Home}/repository/deployment/server/jaggeryapps/apistore.
  2. Then create the page called ‘list-user-apis.jag’ by navigating to ‘apistore/src/site/pages/’ directory.This page will list down the APIs created by logged user for the API-Store.Add the page content as its title,base page,layout,included templates by refering to the file inside the attached sample/page directory.
  3. Then add a url mapping for it in jaggery.conf file in web-application as below;
    "urlMappings":[           {               "url":"/apis/list",               "path":"/site/pages/list-user-apis.jag"  } ]
  4. If you look the attached code sample,since in your added page [list-user-apis.jag],you have defined a template to be included in ‘middle’ part of the layout called ‘list-apis’;Navigate to ‘apistore/src/site/themes/fancy/templates’ and add the directory  ‘list-apis’.
  5. Add a template jag and a initializer jag inside it. Add the html code to template.jag and add imports to javascript files and css relevant to this template into initializer.jag. [You can find the sample code for this template.jag and initializer.jag by navigating to attached sample/templates/list-apis].
  6. Upto now you have completed adding ‘view’ part of your page.Now its time to add the ‘controller’ and ‘model’ part of it.For that add a directory called ‘list-apis’into the directory ‘apistore/src/site/blocks’ of the web-application and add the block.jag inside it.[Note that template and corresponding block directories should named as equal.]
  7. Since you need to output the list of APIs from corresponding template.jag,you can use ‘getOutputs()’ function in block.jag to invoke the relevant method from ‘apistore’ module and return the processed output from block to the template file.[You can find this block from navigating to attached sample/blocks/list-apis.]
  8. The directory ‘apistoreweb/src/module’ contains reference to all the functions plugged through the java module into web-application.
    In above case under ‘api store web/src/module/api/’ directory there’s a jag file called ‘published-by-provider.jag’ which contains the corresponding javascript method [getPublishedAPIsByProvider] which will invoke the required java method from the apistore hostobject for this example.
  9. Thus you don’t need to add a new java method to java module as to plugged into the web-application.But in-case,if you want to add a new java-level method ,first add it to the API-Store/API-Publisher Host Object and then add that method to a jag file inside a subdirectory of the  ‘api store web/src/module/’ directory.And make sure you have defined that method to the ‘module.jag’ in that subdirectory as well.
  10. So now you have done necessary changes to update your change from API-Store web app.Start the API Manager server and navigate to {API Manager Server}/repository/deployment/server/jaggeryapps. Then replace the existing directory ‘apistore’ ,with your changed apistore web app directory.Since exploded mode hot deployment is enabled as default,you can see the changes reflected to web-app UI without restarting the server.
  11. From the browser access “https://ip:port/apistore/apis/list”,then you’ll see the list of published API names by corresponding logged user for the web-app. 

Customizing WSO2 API Store/Publisher App-Part1

Up to now,hope most of the audience is familiarized with writing java web applications. Now it's time to write a complete javascript based web application with the help of Jaggery.


Jaggery is a Server Side Javascript Framework to write web-applications and HTTP-focused web services for all aspects of the application:front-end, communication, server-side logic and persistence in pure javascript. It offers a completely javascript way to write all parts of Web applications and services as a way to reduce/eliminate mismatches across different layers of the Web application and API development experience. Such that it provides closing the gap between web apps from web services by allowing one to create both application and APIs at the same time.For more information visit the site [1] ,which contains more information,API documentation and samples of it.

This article will focus on how to write a web application with Jaggery. For that as a real use-case,it'll focus on the implementation of two web applications released with WSO2 API Manager [available with Beta1 version] known as API-Store and API-Publisher.

WSO2 API Manager

WSO2 API Manager is a complete solution for publishing APIs,creating and managing  a developer community and for scalably routing API traffic.Basically it contains with three components called API-Store,API -Publisher and API-Gateway. Out of these three API-Store and API-Publisher are web-applications developed to interact with third party users.Importantly those were bulit as javascript web applications by using Jaggery.For more information on API Manager refer  [2].

Getting Started

Pre-RequestiesWSO2 API Manager

In real world, web applications are not much simple as above. For a web application there are a large number of inter-connected UI pages written using HTML,CSS and Javascript with JQuery or a similar library and the interaction with back-end is happening via form POST,JSON or XML data processing and data storing part done via SQL or a file type.As you can see every step of the process has significant impedance mismatches. This is where Jaggery comes to the spot as its capability of writing all parts of Web applications as a way to reduce/eliminate impedance mismatches across different layers of the Web application and API development experience.
If we pay attention on API Publisher and API-Store web applications,below is the general view of how we have implemented them with the help of jaggery.


Simply we can separate the story into three components.

1.Back-end Java Implementation [Data Access Layer]

All the API Manager apps related functionalities were written based on a java API as a Data Access Layer and some of the metadata had been stored to WSO2 Governance Registry while final storage kept as database storage.

2.Java Module implementation based on Javascript Hostobjects[3]

As API-Manager related functionalities have been implemented based on a java API and not on a Web Service API,to invoke those back-end java implementations,there was a requirement to plug a java module to interact with both back-end layer[java] and front-end application[javascript]. That's how the two javascript hostobjects named as APIProviderHostObject and APIStoreHostObject were written and mapped the java logic in back-end to the javascript in front-end application.
How we have plugged these two hostobjects to the web-applications in API-Manager product is that,we have defined a module called 'apistore' from these two host objects from a module.xml file which you can found from {API Manager Home}/modules/apistore/module.xml and define two hostobjects inside that module.Sameway you can write your own java modules and plugged as above.

3.Front-end web-app implementation

Front-end web-applications has been written based on jaggery with using HTML,CSS and Javascript and Jquery. For clarity and extensibility purposes,the web-applications have followed Model View Controller pattern. Below shown image is the folder structure of the api-store web app. Note that there's no specific directory structure to create a jaggery app,its upon to you based on the complexity of the app.

API-Store jaggery app directory structure

1) jaggery.conf -This file specifies the application specific configurations. It has used to define the URL-mappings for the pages, define welcome page,security-constraints,etc.
2) site directory -This directory contains below important sub-directories;

  1. Themes- The web-app has the capability of multiple-theme support and easily a user can add a new theme with less customized effort to the app. Currently API-Store app contains two themes called 'fancy' and 'modern'.Each theme contains;     

    • CSS -Contains the stying files of the application.

    • Images-Contains the styling images of the application.

    • js-Contains the globally used JavaScript libraries related files as jquery,bootstrap

    • templates-Contains views of the web-application. The layout of a web page has been separated into layout blocks and each UI of such layout blocks has created using templates. A template can be considered as a re-usable UI block. Inside such a template the rendering HTML for the web UI part and related javaScript event triggering have been included. Note that these templates can be reusable in any page,by including it to the required page. Each template should contain two files as; 

       -template.jag-Which contains the html code.Below is a sample template code.

      <% jagg.template( "api", function(inputs, outputs, jagg) { %>
      //The outputs displaying from the template and the inputs for the template can be via outputs and inputs parameters. 
      //All the htmls included here
       <% }); 

        -initializer.jag -Which uses to initialize the template by embedding javascript files or css to the template.Below is a sample initializer code. 

      <% jagg.initializer( "api ", {    preInitialize:function (data) {                
       //Below is how to import a javascript and CSS file to a template         
       jagg.addHeaderJS("template", "key", "jsFilePath"); 
      jagg.addHeaderCSS("template", "key", "CSSFilePath");  
       } }); %> 

      The layout which is predefined for a web page in API-Store is as below and the templates are set to the each sub layout parts according to the below layout.  

      The basic layout for a web page in API-Store is as above and it can be found with navigating to ‘templates/layout/base/template.jag’.  

      The basic web page template of the app can be found from templates/pages/base/remplate.jag.

      This base page contains the globaly common stylesheets and other related ui library references.

      From a template,you can include another template also by using following code.In current API-Store app you can find such a location from here.

      jagg.includeBlock("nameOfTemplae", inputParamsAsaJson);


  1. Blocks -

    This directory can be considered as the Controller part of the web app. User actions on each View(template) are sent to the relevant block and then it handle the incoming HTTP requests.

    Each template has a corresponding block. Handling of incoming HTTP requests done from the jag files included inside directory called ‘ajax’ of each block.A block receives user requests and translates them to actions that the module directory should take from these jag files.Then with the response from module directory,the block selects the appropriate template [view] to pass the response as an input to the template.Below is a sample code of a block.


        jagg.block("api", {
           initializer:function (data) {
           //This initializer function is required when defining a block
         getInputs:function () { //This method is optional,and it can be used to define input                                           //parameters for a block. 
          getOutputs:function(inputs) { //Do some operations from the inputs of the block.  }

  1. Conf - This directory contains configurations related to web application User Interface. Inside the 'conf' directory,there's a file called site.conf which contains the settings for default theme,site context of the web application.

  1. Pages- This directory contains the main pages that the web-application.This is the intial location comes after a browser request done by a user.

    In a page you can define its titile,what is the basic page and the layout referring from this page,what templates need to add into the page layout and inputs which has to pass into those templates as a json and page will render accordingly using render method of jagg.jag file. Below is a sample code block to render the page with defining its base page,tittle and templates for layouts.

"title":"API Store Listing",  //Page title
"pagePath":"/site/pages/list-apis.jag", //Page path
"name":"layout/extended", //Page layout
"inputs":{   //Page inputs
  "name":"api/listing", //template for the middle
   "inputs":{  //inputs for the template

3) Module directory 

This can be considered as the 'Model' of the application. It handles the state of the application.When a block invoke an action of a particular module from this directory,it will invoke the relevant function from javascript hostobject.

From jaggery server runtime,it'll process the requests which will go to javascript hostobjects.Then the server will return the response from backend as a mapped javascript object with java response and pass the response again to block and then block will pass the response to corresponding template[view].

4) jagg directory

This is the most important directory of the API-Store web application as it contains the file jagg.jag ,which has kept for handling all functionalities to control and manage interactions among the modules,blocks and templates of the application. It contains custom methods develop for API Store/Publisher web applications to control its functionalities from Jaggery.Some of the important methods defined here is as below

  • jagg.render(obj) -To render the html content for a particular web-page of the application.
  • jagg.getThemePath() -To retrieve the theme defined in 'site/conf/site.json'.
  • jagg.getUserTheme() -To retrieve the user's theme defined in session.
  • jagg.getAbsoluteUrl(path) -To retrieve the absolute path of a relative url .
  • jagg.addHeaderJS(template, key, js) -To import a js file to a given template header .





Thursday, July 26, 2012

Validating WSDLs

WSDL: It stands for Web Services Description Language.It's a document written in XML.The document describes a web service.It specifies the location of the service and the operations(or methods) the service expose.
There are two versions of WSDLs as WSDL1.0 and WSDL2.0.This blog post will explain how you can validate those two types of WSDLs

To validate WSDL 1.0 you can get support of WSDL4J library support and it can be done as follow java code snippet.Relevant  wsdl4j API can be found at here.

    javax.wsdl.xml.WSDLReader wsdlReader10 =  

To validate WSDL2.0,you can get support of apache Wooden library and it can be done as following java code snippet.Relevant wooden API can be found  at here.
   org.apache.woden.WSDLReader wsdlReader20 

Once you entered an invalid wsdl url.readWSDL() method will throw an exception and stop reading it fully.
To differentiate WSDL 1.0/WSDL2.0 from your code .you can check wsdl namespace.

Namespace of WSDL1.0: ""
Namespace of WSDL2.0: ""

Thursday, July 19, 2012

Applying a WSDL from a local entry to a proxy service in WSO2 ESB

Local Entry (Local Registry Entry)

The local registry acts as a memory registry where an user can store text strings, XML strings, and URLs. Local entries can be used to hold various configuration elements required by sequences and proxy services. Usually they are used to hold WSDLs, XSDs, XSLT files etc. A local entry can contain XML content as well as plain text content. A local entry can be configured to load content from a remote file too. WSO2 ESB allows to add new local entries easily using user interface configuration

From this blog,I'll explain  how to attach a WSDL to a proxy service from local registry. Note that you can keep a WSDL as a local entry. But it is recommended to keep wsdls in the registry instead, for easier and better management.

Below steps will explainhow to add a WSDL from a local entry to a proxy service.
  1. Extract WSO2 ESB downloaded pack and start it.
  2. Log-in to ESB admin-console.
  3. Create the local entry for WSDL.

  • Navigate to ESB_menu->Manage->Service Bus->Local Entries 

  • Select Add Local Entries option and add the wsdl from In-lined XML Entry option or Source URL Entry option. 
  • After finished adding it,you'll see the local entry is listed in UI.For more information refer the document [1]. 

  1. Create the proxy service 
  • Navigate to ESB_menu->Manage->Add->Proxy Service and select your wanted proxy service template.Here we will select custom proxy template.
  • Then for the 'Publish WSDL Options';set 'Publishing WSDL' as 'Pick from registry' as below.

  • To enter 'Reference Key' value click on 'Configuration Registry' link appeared in the UI 
  • Then you will see the Resource Browser UI will pop up.

  • In that Resource Browser UI,on the top you'll see,there's a field called 'Local Registry' with a drop down.

  • Click on the drop down and you'll see the added local entry is listed there as in below image. 
  • Select your local entry from this dropdown and click 'Ok' on resource browser UI.Note that please don't picked the path for wsdl from browsing the registry tree.
  • Then proceed with setting endpoints,insequences,outsequences,etc properly to your proxy service.Finally you'll able to successfully create the proxy service. 

How Facebook Orders Your Search Results

When I logged in to Facebook [when I'm free ;)] and tries to search about a friend ,I always notice some names will listed down with a order very fastly.

Have you ever wondered how Facebook orders your search results? Clearly they have some ordering about who they think you are looking for, and they seem to guess pretty well.Facebook order it based on who you interact with, whose profile you look at and who you have recently become friends with.To verify this with a book-marklet ,refer this interesting blog