Quick Start Guide
The WSO2 Mashup Server allows you to acquire web based information from a variety of sources such as Web Services, Web pages, Databases or Feeds, combine it in interesting and useful ways before exposing the result again as a Web Service or page, Feed or a Google gadget. Your Mashup can even interact with users via e-mails, instant messages and desktop alerts. This guide and an access to a Mashup Server should be all you need to start creating your own personalized web services in minutes.
Getting Started
Since you may be viewing this document on-line or in a local installation, let me start off by stating that you can either setup a WSO2 Mashup Server locally or register yourself at our community site and start writing your Mashups.
Setting Up Locally
If you've already got Java (Version 1.6.0_24 preferred) installed on your PC and an environment variable pointing to your Java Home defined, simply download the Binary Distribution of the Mashup Server, unzip it in a local folder and run the wso2mashup batch file (on Windows) or shell script (on Linux) found in the 'bin' directory to get it running.
Confirming that the Server is Up
If you unzipped a distribution, the console or log file will show you the progress of the server startup.
Once the server has started, open up the admin console on your browser. You can access http://localhost:9443/carbon on the default http or https port (typically 9763 and 9443) with IE or Firefox. You will see the provisioning screen below on first startup.
Creating Your First Mashup
Use the "Create" or "Upload" option of the Manage > Services > Add > Javascript menu to create your first mashup. You will be prompted for a name, and when you click 'create' a basic mashup will be created for you and displayed in the Mashup editor. Using "Upload" option, you can simply upload a mashup source file in .js format which will be then deployed automatically.
Saving and Testing the Mashup
The auto generated Mashup is a fully functional Javascript service. Like any other 'hello world' program it does nothing useful, but proves that you have everything in place to write a Mashup.
Use the 'Save Changes' button and you will get back to the Service Listing page where your newly created Mashup will be displayed(If the service is not listed, please refresh it after a few seconds). 'Apply Changes' button will save and deploy your service while your are in the editor page.
You can even design a Custom UI or a Google Gadget from this page. Using tabs at the top of the editor page, you can shift among them. "Generate Template" button at the Custom UI and Google Gadget tab will generate the initial template for both of them.
Clicking on the name of the Mashup will take you to the Mashup details page. By clicking on the "Try this service" link, you can access the Try it page for the service.
Service specific configurations could be set or accessed in this page. You can get more details here
If you get a response from the service when you try it, you've written your first mashup!
Adding the Interesting Bits
Now that you've seen how easy it is to write a service, you can start on getting it to actually do something. The next few sections will show you how to perform some actions that you can use as building blocks when creating your own mashups.
Scraping a Web Page
While instructions for using the Scraper host object are included in the user guide, this section shows you how to create a configuration file using the 'Scraping Assistant', which is a tool that will help you write a scraper configuration. The basic steps you need to follow to create a configuration that will get the contents of a web page as an XML document would be:
1) Open up the Scraper Tool, which will give you an empty config which we will fill up.
1) Add a line to retrieve a page available at a given URL, using the 'Add HTTP request' menu option, which will insert the single line below into the config and replace the url-to-fetch with the URL of the page you want to fetch.
<http url="url-to-fetch" method="post"/>
2) Add instructions to convert this HTML to XML, by selecting the previous line and the using 'Convert HTML to XML' menu option, which will surrounding the above statement with this pair of tags:
<html-to-xml outputtype="pretty"></html-to-xml>
3) Add instructions to put the result into a variable, which you can access from your Javascript mashup, by using the 'Convert to Variable' menu option with the existing code block selected. This will surround the existing code with the following:
<var-def name="variable-name"></var-def>
Optionally, use a variable name that has some semantic value, to arrive at a completed configuration as shown below.
4) Now you have a scraper configuration that you can use in a mashup. Paste it into your script and use it as shown below:
function getString() {
var config = <config>
<var-def name="mashupSite">
<html-to-xml outputtype="pretty">
<http url="http://wso2.org/projects/mashup" method="post"/>
</html-to-xml>
</var-def>
</config>
var scraper = new Scraper(config);
var result = scraper.response;
return result;
}
Use 'tryit to' test the operation; you should see the page content displayed as the response.
You can now modify your configuration to filter out the information you don't need from this page, or use logic within your mashup itself to extract the bits you need.
Accessing an External Web Service
The easiest way to access a Web Service hosted externally would be to generate a stub for this service and include it in your mashup.
1) Open up the 'JavaScript Stub Generator', paste the URL to the WSDL of the service you want to access in the correct input field, select the environment you will use it in (E4X) and select 'Generate from URL' to have the stub code generated for you as shown below.
2) Create a new Mashup, say 'Currency' and save it. You will find a Currency.resources directory created in your personal scripts directory. Create a new text file here for the stub and paste the generated code in it. Let's assume it 'convertor.stub.js'.
3) Edit the mashup and include an import statement to bring in your stub.
4) Call the {service}.operation using the stub, to get the result shown below:
Reading a Feed
1) With the three lines of code shown below, you can get all the entries of a given feed into an array.
var feedReader = new FeedReader();
var myFeed = feedReader.get("feed-url");
var feedEntries = myFeed.getEntries();
2) This can then be processed in a simple for-next loop.
this.serviceName = "FeedDemo";
feedTitles.inputTypes = { "feedURI" : "String" };
feedTitles.outputType = "String";
function feedTitles(feedURI) {
var feedReader = new FeedReader();
var myFeed = feedReader.get(feedURI);
var feedEntries = myFeed.getEntries();
var outString = "Titles";
for(var entry in feedEntries) {
outString += feedEntries[entry].title + "<break/>"
}
return outString;
}
3) It will return the contents of the feed as a string
That concludes the 'Quick Start Guide'. Please refer to mashup articles on the Oxygen Tank, in addition to the samples and documentation included with the product, for more on creating Mashups.
Note: getEntries()[n].link of Feed hostobject returns an array by default as it is used for both atom(atom feed might have many links) and rss.
Task Scheduling
Task Scheduling feature in Mashup Server gives you a much more flexibility in scheduling recurring jobs. You can schedule any JavaScript function using system hostobject's setInterval() or setTimeout() method. Each time those two methods are called, it creates a pending task which will be executed exactly at the specified time or time interval. An admin user can see all the pending task and their details of recurrence through Mashup Servers new Scheduled Task UI. Admins have the flexibility to delete or re-schedule those task as needed from the UI.
There may be two type of scheduled task in a mashup.
- A task which will be executed only once (using system.setTimeout())
- A task which will be executed specilfied number of times or infinitly with specified time interval(using system.setInterval())
