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 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 stat 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.5 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.
If you're on Windows, you can download and run the Installer instead, which lets you click through a wizard, to setup and run the server as a Windows Service. You should do fine just clicking on next at each step, going with the default options.
Confirming that the Server is Up
If you used the Windows Installer, you will see a new icon in the system tray that will indicate server status.
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 use the ‘Administration’ right-click-menu item of the tray icon if you used the Windows Installer or access localhost on the default http or https port (typically 7762 and 7443) with IE or Firefox. You will see the provisioning screen below on first startup.
To setup the primary account, just type in a user name and preferably an e-mail ID, along with a 5 or more character password and click 'Create Account'.
Registering on Mooshup.com
Use the 'Sign Up' link on the home page to access the self registration page, where you can create your own account and complete the process by clicking on the verification link mailed to the e-mail ID you specify.
Creating Your First Mashup
Regardless of whether you're using the community site or your local system, once you login, you should see a welcome page with the options shown below.
Use the ‘Create a new mashup’ option of the 'Management tasks' pane 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.
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 that can.
Use the 'Save Changes' button and you will get back to the welcome page, but with your newly created Mashup displayed under 'My Mashups'.
Clicking on the name of the Mashup here will take you to the Mashup details page.
Here you can start, stop, edit or delete the service using the options in the 'Management Tasks' pane. More importantly, you can try out your Service's single operation using the 'Try the Service' link.
If you get a response from the service when you try it, pat yourself on the back, 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:
<http url="url-to-fetch" method="post"/>
Replace the url-to-fetch with the URL of the page you want to fetch.
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_1">
</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="response">
<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. I've called 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 as shown below.
3) It will return the contents of the feed as a string, as shown when tried below.
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.