Scout/Tutorial/3.7/Webservices with JAX-WS

Abstract

This tutorial is a guide to developing JAX-WS webservices in Eclipse Scout. JAX-WS stands for Java API for XML Web Services. The JAX-WS version supported by Eclipse Scout is JAX-WS RI 2.1.6 bundled with Java SE 6. We are not using the lastest version (such as JAX-WS RI 2.2.5 because we encountered a lot of problems in having a newer version aside the Java built-in internal JAX-WS RI 2.1.6 implementation.

The scope of this tutorial is to create a simple Scout application with a webservice consumer and a webservice provider installed. The application will load company data from a Derby database and allow the user to request a company's stock price with a 20 minute delay from the public StockQuoteService. Also, a webservice will be published to access the application's company data from within another application.

Requirement

In order to run this tutorial, you require to have the latest Eclipse Scout Plug-Ins from the nightly updatesite. That is because Scout JAX-WS integration is not part of the Eclipse Indigo release but of the Eclipse Juno release planned for mid of 2012. For more information on the Eclipse release plan, please see Eclipse releases.

Resources

The Eclipse projects for this tutorial can be downloaded from our SVN at scout.example. All projects that belong to this tutorial start with the name org.eclipse.scout.tutorial.jaxws.*

In order to run the tutorial you need to have the Derby database installed on your system. A ready-to-go database can be downloaded from org.eclipse.scout.tutorial.jaxws.database.zip. Alternatively, the database can be created from scratch by using the SQL script create_database.sql located in the Plug-In org.eclipse.scout.tutorial.jaxws.database. The Scout documentation has been moved to https://eclipsescout.github.io/. on how to setup the derby database from scratch.

Preliminary work

First of all, you have to The Scout documentation has been moved to https://eclipsescout.github.io/.. Enter org.eclipse.scout.tutorial.jaxws as project name and choose Outline Tree and Table Form as template. The Scout documentation has been moved to https://eclipsescout.github.io/. to easily start the application. Afterwards, The Scout documentation has been moved to https://eclipsescout.github.io/. to access company data and to persist webservice log entries. In order to display data from database, The Scout documentation has been moved to https://eclipsescout.github.io/. with a The Scout documentation has been moved to https://eclipsescout.github.io/. as its child page. In order to display stock quote information for a company, The Scout documentation has been moved to https://eclipsescout.github.io/..

To track webservice requests, they are logged into the database in the course of this tutorial. This is why a The Scout documentation has been moved to https://eclipsescout.github.io/. and The Scout documentation has been moved to https://eclipsescout.github.io/. are to be created.

Add JAX-WS support to the project

In order to have JAX-WS support available in the project, add the Plug-In org.eclipse.scout.jaxws216 to the server's required Plug-Ins in plugin.xml and to your product-files. The Scout documentation has been moved to https://eclipsescout.github.io/. how to accomplish this.

Create Webservice Consumer

On server node, go to the node 'Webservices (JAX-WS RI 2.1.6)' | 'Consumer' | 'Services'. Right-click on that node to create a new webservice consumer [1]. In the first wizard step, choose the 2nd option WSDL FROM URL and enter the URL to the WSDL file of the stock quote service provider [2]. In the course of this tutorial this would be http://services.nexus6studio.com/StockQuoteService.asmx?wsdl. By pressing TAB or clicking somewhere outside the URL field, the WSDL file is evaluated. If this is about a valid WSDL file, click Finish to create the webservice consumer. The Scout documentation has been moved to https://eclipsescout.github.io/. to learn more about webservice consumer creation. In case you encounter problems to build the webservice stub, refer to the The Scout documentation has been moved to https://eclipsescout.github.io/. for more information. Please find the created webservice consumer StockQuoteWebServiceClient in Scout Explorer [3]. In the Scout Property View of this consumer, you can access the various files such as the WSDL file or the service type. Also, there you find links to rebuild the webservice stub, change build properties for stub generation process, for editing binding customization files and more. Also, the authentication mechanism can be changed in the section Authentication. For more information on that Property View, please The Scout documentation has been moved to https://eclipsescout.github.io/..

Next, we have to configure the endpoint URL of the webservice which is http://services.nexus6studio.com/StockQuoteService.asmx. For the sake of convenience, we hard-code this URL by specifying the property URL in the Property View [4]. In real life, this would be done in config.ini to distinguish the different systems such as development, integration and production.

Integrate Webservice Consumer in application

Finally, the webservice is ready to be used by our tutorial application. Open the process service CompanyProcessService and follow the two steps described below:

 Add data conversion methods
 Because data provided by the webservice is only of the type xsd:string, we have to convert them to their corresponding types.
 Please add the following conversion methods to your service.
 
 The Scout documentation has been moved to https://eclipsescout.github.io/. to get the source

 Change load-method to access webservice
 We have to change the implementation of CompanyProcessService#load(CompanyFormData) to access the stock quote webservice and include quote information for that company in the The Scout documentation has been moved to https://eclipsescout.github.io/..
 Please change the service's implementation as following:
 
 The Scout documentation has been moved to https://eclipsescout.github.io/. to get the source

Finally, if you launch the application, you should see something like this:

Log Webservice Consumer's SOAP messages

In order to log the SOAP messages for request and response, we have to add a LogHandler to the webservice client. In Scout, there already exists a simple version of such a log handler, but the log is only written to the logging facade, not to the database. That is why we write our own DatabaseLogHandler that inherits from the Scout LogHandler.

Because handlers can be used in both, consumers and providers, they are located in 'Webservices (JAX-WS RI 2.1.6)' | 'Handlers'. Right-click on that node to create a new The Scout documentation has been moved to https://eclipsescout.github.io/. [5]. In the dialog, enter the following values [6]:

Properties
Name: DatabaseLogHandler
Package: <do not change>
Super Type: LogHandler (click on 'Browse' to search for that type)
Run in Scout transaction: check because we are writing to database
Session factory: <do not change>

After the handler is created, go back to the webservice consumer StockQuoteWebServiceClient. In Scout Property View, click on Exec Install Handlers to register the handler [7]. Simply add the DatabaseLogHandler to the list of handlers. Click The Scout documentation has been moved to https://eclipsescout.github.io/. to get the source code.

Finally, if you launch the application, you should see something like this: