[Download] | [Documentation Index] | [Release Note]
WSO2 Data Services Solution now supplies pluggable components in the form of Eclipse WTP plugins which enable it to be integrated with the popular IDE Eclipse. This guide is meant to demonstrate the use of the newly introduced Data Services tools in tandem with the Eclipse Web Tools Platform Project using WTP 2.0 drivers or later. The guide shows how to create a simple data service and deploy the service on a data services solution server.
Download Eclipse WTP 2.0 or later and extract it to a desired location. Eclipse WTP 2.0 or later requires j2sdk 5.0 or higher
Close any running instances of Eclipse WTP before starting the installation.
Download org.wso2.ws.dataservices.ide_1.0.0 and copy the file in to the eclipse plugin directory.
Note: If you are running eclipse ganymede under linux and the data service plugin is not visible, copy the plugin instead to the dropins directory instead which is located in parallel with the plugins directory of Eclipse WTP
When creating a data service it requires 3 components
Datasources
Queries
Operations
This is the data source which our data service will request data from. This release of the plugin supports 4 major types of datasources.
Relational databases
Excel files
CSV files
JNDI datasources
Currently in the plugin only mysql and derby is directly shown under relational databases.
This is where we can specify what to request from the datasource. Depending upon the type of datasource our method of request of data will differ.
This is what the user sees as a web service. An operation is simply a mapping to an existing query. Web service user only sees what you define in operations. For more information about how dataservices created goto …. With that short introduction you are good to go now.
Lets try and create a dataservice through the plugin now. This version of the plugin creates a dataservice through a wizard. The wizard will collect data required to follow to the next step in each page collecting all the necessary information to create a valid dataservice.
First lets start the Eclipse WTP IDE. You may or may not have projects currently loaded to the workspace.
In the above screenshot I have few projects loaded and in one project I have created a folder named "dataservice" in the hope of saving a copy of the dataservice in this service I might create.
To create a new dataservice
Press Ctrl + N or File -> New -> Other…
This will show the new dialog box
In the New Wizard dialog select WSO2 Dataservice Creation Wizard and click Next.
This will show the first page of the dataservice wizard.
This page determines what you want to do. i.e. Create or modify or just deploy a dataservice. In our case we will be creating a dataservice now.
Select "Create a new data service from scratch" among the 3 options at the top.
Then we need to specify where we are going to deploy the dataservice. Currently we can deploy the dataservice in the dataservices solution or later versions of WSAS 2.3. If you want to deploy it to a running instance of these servers accessible from your computer, then select the first option and specify the url (and port as shown in the example) to that server. However you will have to set the trustore if it is different from the default trust store available and user credentials required to authenticate with the server.
Click on the "Set truststore" button to specify the new truststore file.
After selecting a valid trustore it will ask for a valid password. If you leave blank at the password textbox and click ok, the default password for the dataservice solution will be used.
You should also set valid credentials to the server by clicking "Set Credentials"
Users are also given the option to try the deployed service if the deployement was successfull and there is no error at the server side. Just tick the "Try it after deploying" checkbox and after the service has been deployed the a browser will open to try the web service.
Other than deploying it to a running dataservice solution, if the binary districution of the server resides on a path where the eclipse insance has write access, you can select "CARBON based path" option and specify the path to the binary distribution.
If we want a copy of the dataservice saved on to the workspace tick the last option in the page and specify a workspace relative path in the text box provided.
If all the information stated are validated to be correct you can proceed to the next page in the wizard where you can specify datasources to the dataservice.
The 2nd page of the wizard is where we actually start building our dataservice. First you have to specify a valid service name. This name should comply any rules governing for creating service names.
This version of the plugin supports multiple datasources. Thus each time you click "Add" and add a datasource it will be listed in the table. By default the first datasource you add will have no name/id for it and thus will be called “[Default]” for the purpose of addressing it.
In the case of a missing datasource for a query (which we will be discussing int he next wizard page) it will by default assume its datasource as this "[Default]" datasource.
If you add more datasources hereafter adding the first one you will be required to specify a unique datasource id for them.
Click "Add" and you will be presented with a small dialog which requests for a datasource id and the datasource type. If it is the first datasource the datasource id will be readonly. The datasource type can be of 4 types. Here we will add a relational database datasource (RDBMS) as an example.
Connecting to a RDMBS requires that the relevant driver class being present in the class path. If it is not present you will be asked to specify the jar which contains the class.
Specify the path to the jar file in the provided textbox.
Note: It is not neccessary to provide the library which has the neccessary driver classes since if the server supports they will contain the driver class in it self. The wizard requires the driver class so that it can use the database connection for content assistance in the later stages of the wizard.
This textbox to specify the jar will only appear in the event of missing the driver class on the class path.
After specifying the relevant details for the database connection you can click "Test Connection" button to test the entered details to connect with the database
If the connection details are successfull the you will get a success massage. If not it will show the error of which you might have to change the entered values. However testing the connection may not applicable the database is not accessible from you computer (but can be accessed by the server of which you are deploying).
Click ok to add the datasource to the dataservice.
That is how you add a RDBMS datasource. Adding other types of datasources are also similar.
Lets see how we add an excel datasource.
Since this is the 2nd datasource we are adding we will have to specify a datasource id. Say we put the id as "StudentAgeDataSource" and click OK. Specify the excel file path and click ok.
Adding a CSV datasource is similar. But you are required to specify a few more information regarding the CSV.
Here the Starting row is the row which starts the data. Which means if you select "TRUE" for "Headers Available" the row number before that would contain the header row.
If you specify that the header is present you are required to specify the order of the headers. As soon as you specify that the headers are available the wizard attempts to open the specified CSV file and retrieve the headers.
Double click on the column row and it will set the next order number to that header. Double clicking on it again will remove the ordering rearranging the order numbers which was set after that header.
After that ofcourse you have to click "OK" to add the datasource to the dataservice.
You can just double click on a datasource listed on the table or select and click "Edit" to modify the details of the datasource. Deleting a datasource will delete any queries and operations which use those datasources/queries.
Adding queries to the datasources is simple as it is done in the Web UI wizard. Click "Add New Query" and the new query dialog will appear.
In the dialog specify the datasource which you want to create the query from. Each datasource type has a different way of specifying its query.
Help on the type of information needs to be provided for queries visit the Web UI wizard documentation.
One special feature offered by the plugin is that it supports content assistance for the SQL statement in RDBMS datasource.
If you have specified the RDBMS datasource details correctly (along with the driver library if it was not present) and the database is accessible through your computer pressing the Ctrl + Space would bring up a popup which would contain a list of tables present in the database specified in the RDBMS datasource. If you press "." After a table name it will popup a list of columsn present for that table.
This content assistance is provided when you specify output mappings also.
If you have specified the sql query correctly the wizard will list all the colums which can be present from executing the sql query you have specified.
Note: Removing output mappings will permanantly remove corresponding mapping values in defined operations which uses that particular query.
Adding operations to the dataservice is also very easy and is similar to the wizard in Web UI. For more information on how it is done visit Web UI wizard documentation.
After the adding all the necessary datasources, queries and operations now we are ready to deploy our dataservice. The accuracy of the dataservice cannot be determined completely by the plugin since validity of some of the configurations may depend upon the server that it is been deployed.
Click finish to deploy the dataservice. The wizard will start deploying the service in the specified location. If the location is a dataservice solution server it will authenticate with the server with the given credentials and send the dataservice to the server.
You are just trying save the dataservice in to a CARBON based path the wizard will create the dataservice file in the required folder.
In the case of deploying it to a server the wizard will attempt to test whether the service was deployed without errors.
It will wait for the server to load the service for 60 seconds. If the server loads the service successfully and publishes the wsdl the test will succeed. If not it will timeout with an error. You may have to visit the server and check the errors specified for the uploaded servervices and fix them in the wizard. Visit the documentation on faulty services for more information regarding this.
If the test was successfull and if you have ticked "try it" the wizard will launch the web browser to test the webservice.
Modifying an existing dataservice saved locally is as easy as creating a dataservice except that there is less work involved. Just click on the option "Modify an existing dataservice" and browse the dataservice file.
Other than just allowing to overwrite the local copy of the dataservice file rest of the configurations and settings is as same as creating a dataservice. You can go through the wizard, do the changes and click finish to deploy the service.
Deploying an existing dataservice saved locally is as easy as creating a dataservice except that there is onyl one page involved. Just click on the option "Deploy an existing dataservice file to a WSAS server or dataservice solution" and browse the dataservice file.
Specify the correct details on the url field and click finish to deploy.
When creating/modifying/deploying dataservices through the wizard we can have a copy of it in to our workspace. Or you can import it as a file to the workspace. Once you have it on the workspace you can modify it or deploy is by right clicking on the file in the package explorer.
Here the deploying and editing are as two seperate wizards. A uset may either edit the datasource or deploy it at a time. If by any chance the user requires to modify the dataservice manually not by the wizard, double click and open the file in the xml editor.