Jump to: navigation, search

Difference between revisions of "Scout/Tutorial/3.9/webservices/Webservices with JAX-WS"

< Scout‎ | Tutorial‎ | 3.9‎ | webservices
(See Also)
(page refactoring)
 
(5 intermediate revisions by 2 users not shown)
Line 6: Line 6:
  
 
== Resources ==
 
== Resources ==
<!--The completed projects for this tutorial can be downloaded from our SVN at [https://github.com/BSI-Business-Systems-Integration-AG/org.eclipse.scout.example/raw/3.8/jaxws].  
+
The completed projects for this tutorial can be downloaded from this Git repository [https://github.com/BSI-Business-Systems-Integration-AG/org.eclipsescout.demo/tree/master/jaxws org.eclipsescout.demo/jaxws (GitHub)].  
-->
+
 
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 [https://github.com/BSI-Business-Systems-Integration-AG/org.eclipse.scout.example/raw/3.8/jaxws/org.eclipse.scout.tutorial.jaxws.database/database/org.eclipse.scout.tutorial.jaxws.database.zip]. Alternatively, the database can be created from scratch by using the SQL script [https://github.com/BSI-Business-Systems-Integration-AG/org.eclipse.scout.example/raw/3.8/jaxws/org.eclipse.scout.tutorial.jaxws.database/script/create_database.sql]. [[{{BASEPAGENAME}}/Setup Derby database|Learn more]] on how to setup the derby database from scratch.
+
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 [https://github.com/BSI-Business-Systems-Integration-AG/org.eclipsescout.demo/raw/master/jaxws/org.eclipse.scout.tutorial.jaxws.database/database/org.eclipse.scout.tutorial.jaxws.database.zip org.eclipse.scout.tutorial.jaxws.database.zip]. Alternatively, the database can be created from scratch by using the SQL script [https://raw.github.com/BSI-Business-Systems-Integration-AG/org.eclipsescout.demo/master/jaxws/org.eclipse.scout.tutorial.jaxws.database/script/create_database.sql create_database.sql]. [[{{BASEPAGENAME}}/Setup Derby database|Learn more]] on how to setup the derby database from scratch.
  
 
== Requirements ==
 
== Requirements ==
 
For this tutorial to work, you will have to use a JDK (Java Development Kit).
 
For this tutorial to work, you will have to use a JDK (Java Development Kit).
  
Also, if you have multipe JDK versions installed, make sure you use the same version in your workspace as you use to run Eclipse itself. To check this go to 'Window' | 'Preferences' | 'Java' | 'Installed JREs'. In the list on the right hand side ensure that only one version is listed and that this version matches the one that the running Eclipse is using.
+
Also, if you have multipe JDK versions installed, make sure you use the same version in your workspace as you use to run Eclipse itself. To check this go to <tt>Window > Preferences > Java > Installed JREs</tt>. In the list on the right hand side ensure that only one version is listed and that this version matches the one that the running Eclipse is using.
  
During this tutorial we will analyze and edit [http://en.wikipedia.org/wiki/Web_Services_Description_Language WSDL] files. To do this in a convenient way we need to install the [http://wiki.eclipse.org/index.php/Introduction_to_the_WSDL_Editor Eclipse WSDL editor] if not already installed. To check this go to 'Help' | 'About Eclipse' and press the 'Installation Details' button. On the next dialog switch to the 'Features' tab and check if there exists an entry named 'Eclipse XML Editors and Tools' (column 'Feature Name') [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.WSDLExisting_01.png]. If this entry exists, the WSDL Editor is already installed and you can jump to the next section. Otherwise continue with the following steps:
+
[[Image:Installed_JREs.png|600px]]
1. Go to 'Help' | 'Install New Software...'.
+
2. Select the 'Kepler' updatesite from the 'Work with' listbox.
+
3. Under the category 'Web, XML, Java EE and OSGi Enterprise Development' check 'Eclipse XML Editors and Tools'.
+
4. Click next, next, read and accept the license and press finish.
+
5. After the download and the installation has been completed restart Eclipse and the WSDL Editor has been installed successfully.
+
  
 +
Go to <tt>Window > Preferences</tt>. Click on <tt>Java > Installed JREs</tt> and make sure, that a jdk-version is installed. Choose the jdk-version and click on <tt>Edit...</tt>. Check, if there is a file named <tt>tools.jar</tt>. If it does not, click on <tt>Add External JARs...</tt> and choose the file <tt>{sdk_folder}/lib/tools.jar</tt>.
  
  
[[Image:Installed_JREs.png|600px]]
+
During this tutorial we will analyze and edit [http://en.wikipedia.org/wiki/Web_Services_Description_Language WSDL] files. To do this in a convenient way we need to install the [http://wiki.eclipse.org/index.php/Introduction_to_the_WSDL_Editor Eclipse WSDL editor] if not already installed. To check this go to <tt>Help > About Eclipse</tt> and press the <tt>Installation Details</tt> button. On the next dialog switch to the <tt>Features</tt> tab and check if there exists an entry named <tt>Eclipse XML Editors and Tools</tt> (column <tt>Feature Name</tt>).
  
Go to 'Window' | 'Preferences'. Click on 'Java' | 'Installed JREs' and make sure, that a jdk-version is installed. Choose the jdk-version and click on 'Edit...'. Check, if there is a file named 'tools.jar'. If it does not, click on 'Add External JARs...' and choose the file 'tools.jar'.
+
[[Image:Org.eclipse.scout.jaxws.WSDLExisting_01.png]]
  
== Preliminary work ==
+
If this entry exists, the WSDL Editor is already installed and you can jump to the next section. Otherwise continue with the following steps:
 +
# Go to <tt>Help > Install New Software...</tt>.
 +
# Select the 'Kepler' updatesite from the 'Work with' listbox.
 +
# Under the category <tt>Web, XML, Java EE and OSGi Enterprise Development</tt> check <tt>Eclipse XML Editors and Tools</tt>.
 +
# Click next, next, read and accept the license and press finish.
 +
# After the download and the installation has been completed restart Eclipse and the WSDL Editor has been installed successfully.
 +
 
 +
 
 +
== Preliminary work ==
 
First of all, you have to [[{{BASEPAGENAME}}/Create Scout Project|create a new Scout project]].  
 
First of all, you have to [[{{BASEPAGENAME}}/Create Scout Project|create a new Scout project]].  
  
Line 40: Line 44:
  
 
== Ensure JAX-WS support is enabled for your project ==
 
== Ensure JAX-WS support is enabled for your project ==
In order to have JAX-WS support available in the project, select the project node 'org.eclipse.scout.tutorial.jaxws' in the Scout Explorer. In the Scout Object Properties scroll to the 'Technologies' section and ensure the checkbox 'Webservices with JAX-WS RI 2.1.6' is enabled. If not yet checked, enable the technology and confirm the popup dialog with 'Ok'.
+
In order to have JAX-WS support available in the project, select the project node <tt>org.eclipsescout.demo.jaxws</tt> in the Scout Explorer. In the Scout Object Properties scroll to the <tt>Technologies</tt> section and ensure the checkbox <tt>Webservices with JAX-WS RI 2.1.6</tt> is enabled. If not yet checked, enable the technology and confirm the popup dialog with <tt>Ok</tt>.
  
If JAX-WS support is enabled correctly you should see the 'Webservices (JAX-WS RI 2.1.6)' under the server node in the Scout Explorer. [http://wiki.eclipse.org/Image:Org.eclipse.scout.tutorial.jaxws.EnableJaxWsSupport_1.png]
+
If JAX-WS support is enabled correctly you should see the <tt>Webservices (JAX-WS RI 2.1.6)</tt> under the server node in the Scout Explorer.
 +
 
 +
[[Image:Org.eclipse.scout.tutorial.jaxws.EnableJaxWsSupport_1.png]]
  
 
== Create Webservice Consumer ==
 
== Create Webservice Consumer ==
On server node, go to the node <code>'Webservices (JAX-WS RI 2.1.6)' | 'Consumer' | ''''Services''''</code>. Right-click on that node to create a new webservice consumer [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateConsumer_10.png]. In the first wizard step, choose the 2nd option <code>WSDL FROM URL</code> and enter the URL to the [http://en.wikipedia.org/wiki/Web_Services_Description_Language WSDL] file of the stock quote service provider [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateConsumer_20.png]. In the course of this tutorial this would be [http://services.nexus6studio.com/StockQuoteService.asmx?wsdl 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. {{ScoutLink|SDK|JAXWS-SDK/Create webservice consumer|name=Click here}} to learn more about webservice consumer creation. In case you encounter problems to build the webservice stub, refer to the {{ScoutLink|Tutorial|Webservices with JAX-WS/Console Output for StockQuoteService|name=Console Output}} for more information.
+
On server node, go to the node <tt>Webservices (JAX-WS RI 2.1.6) > Consumer > '''Services'''</tt>. Right-click on that node to create a new webservice consumer.
Please find the created webservice consumer <code>StockQuoteServiceSoapWebServiceClient</code> in Scout Explorer [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.consumer_10.png]. 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, to change build properties for stub generation process, to edit binding customization files and more. Also, the authentication mechanism can be changed in the section <code>Authentication</code>. For more information on that Property View, please {{ScoutLink|SDK|JAXWS-SDK/Webservice consumer Property View|name=click here}}.
+
  
Next, we have to configure the endpoint URL of the webservice which is [http://services.nexus6studio.com/StockQuoteService.asmx http://services.nexus6studio.com/StockQuoteService.asmx]. For the sake of convenience, we hard-code this URL by specifying the property <code>URL</code> in the Property View [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.tutorial.consumer_10.png]. In real life, this would be done in config.ini to distinguish the different systems such as development, integration and production.
+
[[Image:Org.eclipse.scout.jaxws.CreateConsumer_3.9_10.png|Create webservice consumer]]
 +
 
 +
In the first wizard step, choose the 2nd option <tt>WSDL FROM URL</tt> and enter the URL to the [http://en.wikipedia.org/wiki/Web_Services_Description_Language WSDL] file of the stock quote service provider. In the course of this tutorial this would be [http://services.nexus6studio.com/StockQuoteService.asmx?wsdl http://services.nexus6studio.com/StockQuoteService.asmx?wsdl].
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.CreateConsumer_20.png|500px|Create webservice consumer]]
 +
 
 +
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 page {{ScoutLink|SDK|JAXWS-SDK/Create webservice consumer|name=Create webservice consumer}} provides more information about webservice consumer creation). In case you encounter problems to build the webservice stub, refer to the [[{{BASEPAGENAME}}/Console Output for StockQuoteService|Console Output]] for more information.
 +
 
 +
Please find the created webservice consumer <tt>StockQuoteServiceSoapWebServiceClient</tt> in Scout Explorer.
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.consumer_3.9_10.png|Webservice Consumer]]
 +
 
 +
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, to change build properties for stub generation process, to edit binding customization files and more. Also, the authentication mechanism can be changed in the section <tt>Authentication</tt>. (The page {{ScoutLink|SDK|JAXWS-SDK/Webservice consumer Property View|name=Webservice consumer Property View}} provides information on that Property View.)
 +
 
 +
Next, we have to configure the endpoint URL of the webservice which is [http://services.nexus6studio.com/StockQuoteService.asmx http://services.nexus6studio.com/StockQuoteService.asmx]. For the sake of convenience, we hard-code this URL by specifying the property <code>URL</code> in the Property View.
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.tutorial.consumer_3.9_10.png|Set URL of webservice Endpoint]]
 +
 
 +
In real life, this would be done in <tt>config.ini</tt> to distinguish the different systems such as development, integration and production.
  
 
== Integrate Webservice Consumer in application ==
 
== Integrate Webservice Consumer in application ==
Finally, the webservice is ready to be used by our tutorial application. Open the process service <code>CompanyProcessService</code> and follow the two steps described below:
+
Finally, the webservice is ready to be used by our tutorial application. Open the service <tt>CompanyService</tt> and follow the two steps described below:
  
  '''Add data conversion methods'''
+
===Add data conversion methods===
  Because data provided by the webservice is only of the type <code>xsd:string</code>, we have to convert them to their corresponding types.
+
Because data provided by the webservice is only of the type <tt>xsd:string</tt>, we have to convert them to their corresponding types.
  Please add the following conversion methods to your service.
+
Please add the following conversion methods to your service.
 
    
 
    
  [[{{BASEPAGENAME}}/Conversion methods for StockQuote service|Click here]] to get the source.
+
The corresponding source code is provided here: [[{{BASEPAGENAME}}/Conversion methods for StockQuote service|Conversion methods for StockQuote service]].
  Please note: use java.util.Date for the Date class and not e.g. java.sql.Date!
+
  
  '''Change load-method to access webservice'''
+
Please note: use <tt>java.util.Date</tt> for the Date class and not e.g. <tt>java.sql.Date</tt>!
  We have to change the implementation of <code>CompanyProcessService#load(CompanyFormData)</code> to access the stock quote webservice and include quote information for that company in the {{ScoutLink|Concepts|FormData}}.
+
 
  Please change the service's implementation as following:
+
===Change load-method to access webservice===
 
+
 
  [[{{BASEPAGENAME}}/Integrate StockQuote service into CompanyProcessService|Click here]] to get the source
+
We have to change the implementation of <tt>CompanyService#load(CompanyFormData)</tt> to access the stock quote webservice and include quote information for that company in the {{ScoutLink|Concepts|FormData}}.
 +
 
 +
Please change the service's implementation as following:[[{{BASEPAGENAME}}/Integrate StockQuote service into CompanyService|Source code for the CompanyService]].
  
 
Finally, if you launch the application, you should see something like this:
 
Finally, if you launch the application, you should see something like this:
  
[[Image:Org.eclipse.scout.jaxws.tutorial.stockquote.png|400px]]
+
[[Image:Org.eclipse.scout.jaxws.tutorial.stockquote.png|400px|Application displaying stock quote consumed by webservice]]
  
 
== Log Webservice Consumer's SOAP messages ==
 
== Log Webservice Consumer's SOAP messages ==
In order to log the SOAP messages for request and response, we have to add a <code>LogHandler</code> 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 <code>DatabaseLogHandler</code> that inherits from the Scout <code>LogHandler</code>.
+
In order to log the SOAP messages for request and response, we have to add a <tt>LogHandler</tt> 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 <tt>DatabaseLogHandler</tt> that inherits from the Scout <tt>LogHandler</tt>.
  
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 Handler
+
Because handlers can be used in both, consumers and providers, they are located in <tt>Webservices (JAX-WS RI 2.1.6) > Handlers</tt>. Right-click on that node to create a new Handler.
[http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_10.png]. In the dialog, enter the following values [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_20.png]:
+
  
'''Properties'''
+
[[Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_3.9_10.png|Create new Handler]]
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>
+
  
Double-click on the handler and implement it as [[{{BASEPAGENAME}}/DatabaseLogHandler|following (source code)]]:  
+
In the dialog, enter the following values:
 +
* 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 <code>StockQuoteServiceSoapWebServiceClient</code>. In Scout Property View, click on <code>Exec Install Handlers</code> to register the handler [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_30.png]. Simply add the <code>DatabaseLogHandler</code> to the list of handlers. Click [[{{BASEPAGENAME}}/Register DatabaseLogHandler in webservice consumer|here]] to get the source code.
+
[[Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_3.9_20.png|500px|Create new DatabaseLogHandler]]
 +
 
 +
Double-click on the handler and implement it as following: [[{{BASEPAGENAME}}/DatabaseLogHandler|source code for DatabaseLogHandler]]
 +
 
 +
After the handler is created, go back to the webservice consumer <tt>StockQuoteServiceSoapWebServiceClient</tt>. In Scout Property View, click on <tt>Exec Install Handlers</tt> to register the handler
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_3.9_30.png|Register Handler on consumer]]
 +
 
 +
Simply add the <tt>DatabaseLogHandler</tt> to the list of handlers. Click [[{{BASEPAGENAME}}/Register DatabaseLogHandler in webservice consumer|here]] to get the source code.
  
 
Finally, if you launch the application and open a company, the SOAP messages are written into the database. In turn, if you open a log message, you should see something like this:
 
Finally, if you launch the application and open a company, the SOAP messages are written into the database. In turn, if you open a log message, you should see something like this:
  
[[Image:Org.eclipse.scout.jaxws.tutorial.ApplicationWsLog.png|400px]]
+
[[Image:Org.eclipse.scout.jaxws.tutorial.ApplicationWsLog.png|400px|Webservice Log in application]]
  
 
== Create Webservice Provider ==
 
== Create Webservice Provider ==
On server node, go to the node <code>'Webservices (JAX-WS RI 2.1.6)' | 'Provider' | ''''Services''''</code>. Right-click on that node to create a new webservice provider [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_0.png]. In the first wizard step, choose the 1st option to create a webservice provider from scratch, meaning not based on an existing [http://en.wikipedia.org/wiki/Web_Services_Description_Language WSDL] file [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_10.png]. Click next (two times) to enter the WSDL name which is <code>CompanyWebService.wsdl</code>. Also, change the name for the service operation to <code>getCompanies</code> [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_20.png]. Click Finish to create the webservice provider. {{ScoutLink|SDK|JAXWS-SDK/Create webservice provider|name=Click here}} to learn more about webservice provider creation. In case you encounter problems to build the webservice stub, refer to the [[{{BASEPAGENAME}}/Console Output for CompanyWebService|Console Output]] for more information.
+
On server node, go to the node <tt>Webservices (JAX-WS RI 2.1.6) > Provider > '''Services''''</tt>. Right-click on that node to create a new webservice provider.
Please find the created webservice provider <code>CompanyWebService</code> in Scout Explorer [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.provider_10.png]. In the Scout Property View of this provider, you can access the various files such as the WSDL file, implementation class or the JAX-WS service type. Also, there you find links to rebuild the webservice stub, to change build properties for stub generation process, to edit binding customization files and more. Also, the authentication mechanism can be changed in the section <code>Authentication and session context</code>. For more information on that Property View, please {{ScoutLink|SDK|JAXWS-SDK/Webservice provider Property View|name=click here}}.
+
  
So far, our webservice consists of a single operation to return companies. To open the WSDL file in the WSDL editor, click on the link 'CompanyWebService.wsdl' in the Scout Property View [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_50.png], To open the implementing port type, double click the webservice node or click on the 'CompanyWebService' link in the PropertyView [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_60.png].
+
[[Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_3.9_0.png|Create webservice provider]]
As you can see, this webservice consists of a single operation <code>getCompanies</code> with a <code>String</code> as its return value and a <code>String</code> as its parameter. We will change that to return a list of company objects with no input parameter. Because this webservice is a Contract-First webservice, meaning that we are designing the WSDL file by ourself rather than generating it based on Java classes, open the WSDL editor [http://wiki.eclipse.org/Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_50.png] to change the service. Click [[{{BASEPAGENAME}}/Change WSDL file to return a list of companies|here]] to follow detailed instructions. Alternatively, you can download the changed WSDL file from [https://raw.github.com/BSI-Business-Systems-Integration-AG/org.eclipsescout.demo/master/jaxws/org.eclipse.scout.tutorial.jaxws.server/WEB-INF/wsdl/provider/CompanyWebService.wsdl here].
+
  
As you changed the WSDL file, you have to regenerate the stub anew. Thereto, click on 'Rebuild webservice stub' in the Scout Property View of the provider [http://wiki.eclipse.org/Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_170.png]. If the WSDL file is valid, the stub generation will succeed. Otherwise, please refer to the {{ScoutLink|Tutorial|Webservices with JAX-WS/Console Output for CompanyWebService|name=Console Output}} to see what went wrong. Because we changed the method <code>getCompanies</code>, compilation errors are shown in the <code>CompanyWebService</code> Port Type [http://wiki.eclipse.org/Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_180.png]. Remove this wrong <code>getCompanies</code> method and add the unimplemented method instead [http://wiki.eclipse.org/Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_190.png]. As you can see, the method returns a list of companies. That is exactely what we wanted to have.
+
In the first wizard step, choose the 1st option to create a webservice provider from scratch, meaning not based on an existing [http://en.wikipedia.org/wiki/Web_Services_Description_Language WSDL] file
  
Finally, you have to implement the method <code>getCompanies</code> accordingly. Here, we simply return a list of all companies in database. [[{{BASEPAGENAME}}/CompanyWebService_implementation|Click here]] to get the source.
+
[[Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_10.png|500px|Choose how to create the webservice provider]].
  
One last thing we still have to do. Because we configured the webservice to have authentication installed and to validate the request's credentials against config.ini [http://wiki.eclipse.org/Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_70.png], we have to specify the list of valid credentials in config.ini. Thereto, add the following line to the config.ini: That allows the user <code>eclipse/scout</code> to access our webservice.
+
Click next (two times) to enter the WSDL name which is <tt>CompanyWebService.wsdl</tt>. Also, change the name for the service operation to <tt>getCompanies</tt> .
  
<pre>
+
[[Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_20.png|500px|Specify webservice properties]]
 +
 
 +
Click Finish to create the webservice provider. (The page {{ScoutLink|SDK|JAXWS-SDK/Create webservice provider|name=Create webservice provider}} provides more information about webservice provider creation). In case you encounter problems to build the webservice stub, refer to the [[{{BASEPAGENAME}}/Console Output for CompanyWebService|Console Output]] for more information.
 +
 
 +
Please find the created webservice provider <tt>CompanyWebService</tt> in Scout Explorer.
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.provider_3.9_10.png|Webservice provider]]
 +
 
 +
In the Scout Property View of this provider, you can access the various files such as the WSDL file, implementation class or the JAX-WS service type. Also, there you find links to rebuild the webservice stub, to change build properties for stub generation process, to edit binding customization files and more. Also, the authentication mechanism can be changed in the section <tt>Authentication and session context</tt>. For more information on that Property View, please see the page {{ScoutLink|SDK|JAXWS-SDK/Webservice provider Property View|name=Webservice provider Property View}}.
 +
 
 +
So far, our webservice consists of a single operation to return companies. To open the WSDL file in the WSDL editor, click on the link <tt>CompanyWebService.wsdl</tt> in the Scout Property View
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_50.png|Open WSDL file of the CompanyWebService]].
 +
 
 +
To open the implementing port type, double click the webservice node or click on the <tt>CompanyWebService</tt> link in the PropertyView
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_60.png|Open webservice Port Type]].
 +
 
 +
As you can see, this webservice consists of a single operation <tt>getCompanies</tt> with a <tt>String</tt> as its return value and a <tt>String</tt> as its parameter. We will change that to return a list of company objects with no input parameter. Because this webservice is a Contract-First webservice, meaning that we are designing the WSDL file by ourself rather than generating it based on Java classes, open the WSDL editor to change the service:
 +
 
 +
[[Image:Org.eclipse.scout.jaxws.CreateWebServiceProvider_50.png]]
 +
 
 +
Detailed instructions are provided here: [[{{BASEPAGENAME}}/Change WSDL file to return a list of companies|Change WSDL file to return a list of companies]]. Alternatively, you can download the changed WSDL file from the repository: [https://raw.github.com/BSI-Business-Systems-Integration-AG/org.eclipsescout.demo/master/jaxws/org.eclipse.scout.tutorial.jaxws.server/WEB-INF/wsdl/provider/CompanyWebService.wsdl CompanyWebService.wsdl].
 +
 
 +
As you changed the WSDL file, you have to regenerate the stub anew. Thereto, click on <tt>Rebuild webservice stub</tt> in the Scout Property View of the provider.
 +
 
 +
[[Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_3.9_170.png|Rebuild webservice stub]].
 +
 
 +
If the WSDL file is valid, the stub generation will succeed. Otherwise, please refer to the {{ScoutLink|Tutorial|Webservices with JAX-WS/Console Output for CompanyWebService|name=Console Output}} to see what went wrong. Because we changed the method <tt>getCompanies</tt>, compilation errors are shown in the <tt>CompanyWebService</tt> Port Type:
 +
 
 +
[[Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_3.9_180.png|600px|Compilation errors in Port Type due to change of WSDL file]]
 +
 
 +
Remove this wrong <tt>getCompanies</tt> method and add the unimplemented method instead:
 +
 
 +
[[Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_3.9_190.png|600px|Add unimplemented methods of port type interface]].
 +
 
 +
As you can see, the method returns a list of companies. That is exactely what we wanted to have.
 +
 
 +
Finally, you have to implement the method <tt>getCompanies</tt> accordingly. Here, we simply return a list of all companies in database. [[{{BASEPAGENAME}}/CompanyWebService_implementation|Click here]] to get the source.
 +
 
 +
One last thing we still have to do. Because we configured the webservice to have authentication installed and to validate the request's credentials against config.ini, we have to specify the list of valid credentials in <tt>config.ini</tt>.
 +
 
 +
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_70.png|Authentication and credential validation settings]]
 +
 
 +
Thereto, add the following line to the <tt>config.ini</tt>: That allows the user <tt>eclipse/scout</tt> to access our webservice.
 +
 
 +
<source lang="ini">
 
org.eclipse.scout.jaxws.security.provider.ConfigIniCredentialValidationStrategy#credentials=eclipse\=scout;
 
org.eclipse.scout.jaxws.security.provider.ConfigIniCredentialValidationStrategy#credentials=eclipse\=scout;
</pre>
+
</source>
  
 
== Log Webservice Providers's SOAP messages ==
 
== Log Webservice Providers's SOAP messages ==
To log the SOAP requests and response, click on <code>'Webservices (JAX-WS RI 2.1.6)' | 'Provider' | 'Services' | 'CompanyWebService' | ''''Handler Registration''''</code> [http://wiki.eclipse.org/Image:org.eclipse.scout.jaxws.tutorial.LogCompanyWebService_10.png]. Click on the link 'Add handler chain' to create a handler chain and 'Add handler' to add a handler to the chain [http://wiki.eclipse.org/Image:org.eclipse.scout.jaxws.tutorial.LogCompanyWebService_20.png]. By clicking on the 'Browse' button, choose  'DatabaseLogHandler' as the log handler.
+
To log the SOAP requests and response, click on <tt>Webservices (JAX-WS RI 2.1.6) > Provider > Services > CompanyWebService > '''Handler Registration'''</tt>.
 +
 
 +
[[Image:org.eclipse.scout.jaxws.tutorial.LogCompanyWebService_3.9_10.png|Add DatabaseLogHandler to CompanyWebService]]
 +
 
 +
Click on the link <tt>Add handler chain</tt> to create a handler chain and <tt>Add handler</tt> to add a handler to the chain
 +
 
 +
[[Image:org.eclipse.scout.jaxws.tutorial.LogCompanyWebService_3.9_20.png|Add DatabaseLogHandler to CompanyWebService]]
 +
 
 +
By clicking on the <tt>Browse</tt> button, choose  <tt>DatabaseLogHandler</tt> as the log handler.
  
 
== Test the Webservice Provider ==
 
== Test the Webservice Provider ==
Launch the server and open your browser. Enter the URL [http://localhost:8080/tutorial_server/jaxws/ http://localhost:8080/tutorial_server/jaxws/] and you get a list of all your installed webservice providers.<br/>This looks as follows:
+
Launch the server and open your browser. Enter the URL [http://localhost:8080/tutorial_server/jaxws/ http://localhost:8080/tutorial_server/jaxws/] and you get a list of all your installed webservice providers.
 +
 
 +
This looks as follows:
  
 
[[Image:org.eclipse.scout.jaxws.WebserviceOverview.png|400px]]
 
[[Image:org.eclipse.scout.jaxws.WebserviceOverview.png|400px]]
Line 118: Line 203:
 
To test your webservice implementation, download a webservice testing tool such as [http://www.soapui.org/ SoapUI].
 
To test your webservice implementation, download a webservice testing tool such as [http://www.soapui.org/ SoapUI].
  
In SoapUI, create a new 'SoapUI project' and enter [http://localhost:8080/tutorial_server/jaxws/CompanyWebService?wsdl http://localhost:8080/tutorial_server/jaxws/CompanyWebService?wsdl] as your initial WSDL file. By double-clicking on the 'Request 1' node, the request dialog opens. On the property page, enter 'eclipse' as username and 'scout' as password. By clicking on the green 'play' button, the request is sent to your webservice and the SOAP response appears on the right side.
+
In SoapUI, create a new <tt>SoapUI project</tt> and enter [http://localhost:8080/tutorial_server/jaxws/CompanyWebService?wsdl http://localhost:8080/tutorial_server/jaxws/CompanyWebService?wsdl] as your initial WSDL file. By double-clicking on the <tt>Request 1</tt> node, the request dialog opens. On the property page, enter <tt>eclipse</tt> as username and <tt>scout</tt> as password. By clicking on the green <tt>play</tt> button, the request is sent to your webservice and the SOAP response appears on the right side.
  
[[Image:org.eclipse.scout.jaxws.WebserviceTestWithSoapUI.png|400px]]
+
[[Image:org.eclipse.scout.jaxws.WebserviceTestWithSoapUI.png|400px|Test webservice with SoapUI]]
  
 
==See Also==
 
==See Also==
 
* [[:Category:Scout_JAXWS-RT|JAX-WS Runtime]]
 
* [[:Category:Scout_JAXWS-RT|JAX-WS Runtime]]
 
* [[:Category:Scout_JAXWS-SDK|JAX-WS SDK]]
 
* [[:Category:Scout_JAXWS-SDK|JAX-WS SDK]]
 
 
[[Image:Org.eclipse.scout.jaxws.CreateConsumer_3.9_10.png|thumb|Create webservice consumer]]
 
[[Image:Org.eclipse.scout.jaxws.CreateConsumer_20.png|thumb|Create webservice consumer]]
 
[[Image:Org.eclipse.scout.jaxws.consumer_10.png|thumb|Webservice Consumer]]
 
[[Image:Org.eclipse.scout.jaxws.tutorial.consumer_10.png|thumb|Set URL of webservice Endpoint]]
 
[[Image:Org.eclipse.scout.jaxws.tutorial.stockquote.png|thumb|Application displaying stock quote consumed by webservice]]
 
[[Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_10.png|thumb|Create new Handler]]
 
[[Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_3.9_20.png|thumb|Create new DatabaseLogHandler]]
 
[[Image:Org.eclipse.scout.jaxws.tutorial.CreateDatabaseLogHandler_30.png|thumb|Register Handler on consumer]]
 
[[Image:Org.eclipse.scout.jaxws.tutorial.ApplicationWsLog.png|thumb|Webservice Log in application]]
 
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_0.png|thumb|Create webservice provider]]
 
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_10.png|thumb|Choose how to create the webservice provider]]
 
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_20.png|thumb|Specify webservice properties]]
 
[[Image:Org.eclipse.scout.jaxws.provider_10.png|thumb|Webservice provider]]
 
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_50.png|thumb|Open WSDL file of the CompanyWebService]]
 
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_60.png|thumb|Open webservice Port Type]]
 
[[Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_170.png|thumb|Rebuild webservice stub]]
 
[[Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_180.png|thumb|Compilation errors in Port Type due to change of WSDL file]]
 
[[Image:org.eclipse.scout.jaxws.tutorial.EditWsdl_190.png|thumb|Add unimplemented methods of port type interface]]
 
[[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_70.png|thumb|Authentication and credential validation settings]][[Image:org.eclipse.scout.jaxws.CreateWebServiceProvider_70.png|thumb|Authentication and credential validation settings]]
 
[[Image:org.eclipse.scout.jaxws.WebserviceTestWithSoapUI.png|thumb|Test webservice with SoapUI]]
 
[[Image:org.eclipse.scout.jaxws.WebserviceTestWithSoapUI.png|thumb|Test webservice with SoapUI]]
 
[[Image:org.eclipse.scout.jaxws.tutorial.LogCompanyWebService_10.png|thumb|Add DatabaseLogHandler to CompanyWebService]]
 
[[Image:org.eclipse.scout.jaxws.tutorial.LogCompanyWebService_20.png|thumb|Add DatabaseLogHandler to CompanyWebService]]
 

Latest revision as of 13:59, 21 August 2013


Scout
Wiki Home
Website
DownloadGit
Community
ForumsBlogTwitter
Bugzilla
Bugzilla

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.

Resources

The completed projects for this tutorial can be downloaded from this Git repository org.eclipsescout.demo/jaxws (GitHub).

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. Learn more on how to setup the derby database from scratch.

Requirements

For this tutorial to work, you will have to use a JDK (Java Development Kit).

Also, if you have multipe JDK versions installed, make sure you use the same version in your workspace as you use to run Eclipse itself. To check this go to Window > Preferences > Java > Installed JREs. In the list on the right hand side ensure that only one version is listed and that this version matches the one that the running Eclipse is using.

Installed JREs.png

Go to Window > Preferences. Click on Java > Installed JREs and make sure, that a jdk-version is installed. Choose the jdk-version and click on Edit.... Check, if there is a file named tools.jar. If it does not, click on Add External JARs... and choose the file {sdk_folder}/lib/tools.jar.


During this tutorial we will analyze and edit WSDL files. To do this in a convenient way we need to install the Eclipse WSDL editor if not already installed. To check this go to Help > About Eclipse and press the Installation Details button. On the next dialog switch to the Features tab and check if there exists an entry named Eclipse XML Editors and Tools (column Feature Name).

Org.eclipse.scout.jaxws.WSDLExisting 01.png

If this entry exists, the WSDL Editor is already installed and you can jump to the next section. Otherwise continue with the following steps:

  1. Go to Help > Install New Software....
  2. Select the 'Kepler' updatesite from the 'Work with' listbox.
  3. Under the category Web, XML, Java EE and OSGi Enterprise Development check Eclipse XML Editors and Tools.
  4. Click next, next, read and accept the license and press finish.
  5. After the download and the installation has been completed restart Eclipse and the WSDL Editor has been installed successfully.


Preliminary work

First of all, you have to create a new Scout project.

Afterwards, create a Derby SQL Service to access company data and to persist webservice log entries.

In order to display data from the database, create a Company Table Page.

To display stock quote information for a company, create a Company Form.

To track webservice requests, they are logged into the database for this tutorial. This is why a WS Log Table Page and WS Log Form are to be created.

Ensure JAX-WS support is enabled for your project

In order to have JAX-WS support available in the project, select the project node org.eclipsescout.demo.jaxws in the Scout Explorer. In the Scout Object Properties scroll to the Technologies section and ensure the checkbox Webservices with JAX-WS RI 2.1.6 is enabled. If not yet checked, enable the technology and confirm the popup dialog with Ok.

If JAX-WS support is enabled correctly you should see the Webservices (JAX-WS RI 2.1.6) under the server node in the Scout Explorer.

Org.eclipse.scout.tutorial.jaxws.EnableJaxWsSupport 1.png

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.

Create webservice consumer

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. In the course of this tutorial this would be http://services.nexus6studio.com/StockQuoteService.asmx?wsdl.

Create webservice consumer

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 page Create webservice consumer provides more information about webservice consumer creation). In case you encounter problems to build the webservice stub, refer to the Console Output for more information.

Please find the created webservice consumer StockQuoteServiceSoapWebServiceClient in Scout Explorer.

Webservice Consumer

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, to change build properties for stub generation process, to edit binding customization files and more. Also, the authentication mechanism can be changed in the section Authentication. (The page Webservice consumer Property View provides information on that Property View.)

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.

Set URL of webservice Endpoint

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 service CompanyService 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 corresponding source code is provided here: Conversion methods for StockQuote service.

Please note: use java.util.Date for the Date class and not e.g. java.sql.Date!

Change load-method to access webservice

We have to change the implementation of CompanyService#load(CompanyFormData) to access the stock quote webservice and include quote information for that company in the FormData.

Please change the service's implementation as following:Source code for the CompanyService.

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

Application displaying stock quote consumed by webservice

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 Handler.

Create new Handler

In the dialog, enter the following values:

  • 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>

Create new DatabaseLogHandler

Double-click on the handler and implement it as following: source code for DatabaseLogHandler

After the handler is created, go back to the webservice consumer StockQuoteServiceSoapWebServiceClient. In Scout Property View, click on Exec Install Handlers to register the handler

Register Handler on consumer

Simply add the DatabaseLogHandler to the list of handlers. Click here to get the source code.

Finally, if you launch the application and open a company, the SOAP messages are written into the database. In turn, if you open a log message, you should see something like this:

Webservice Log in application

Create Webservice Provider

On server node, go to the node Webservices (JAX-WS RI 2.1.6) > Provider > Services'. Right-click on that node to create a new webservice provider.

Create webservice provider

In the first wizard step, choose the 1st option to create a webservice provider from scratch, meaning not based on an existing WSDL file

Choose how to create the webservice provider.

Click next (two times) to enter the WSDL name which is CompanyWebService.wsdl. Also, change the name for the service operation to getCompanies .

Specify webservice properties

Click Finish to create the webservice provider. (The page Create webservice provider provides more information about webservice provider creation). In case you encounter problems to build the webservice stub, refer to the Console Output for more information.

Please find the created webservice provider CompanyWebService in Scout Explorer.

Webservice provider

In the Scout Property View of this provider, you can access the various files such as the WSDL file, implementation class or the JAX-WS service type. Also, there you find links to rebuild the webservice stub, to change build properties for stub generation process, to edit binding customization files and more. Also, the authentication mechanism can be changed in the section Authentication and session context. For more information on that Property View, please see the page Webservice provider Property View.

So far, our webservice consists of a single operation to return companies. To open the WSDL file in the WSDL editor, click on the link CompanyWebService.wsdl in the Scout Property View

Open WSDL file of the CompanyWebService.

To open the implementing port type, double click the webservice node or click on the CompanyWebService link in the PropertyView

Open webservice Port Type.

As you can see, this webservice consists of a single operation getCompanies with a String as its return value and a String as its parameter. We will change that to return a list of company objects with no input parameter. Because this webservice is a Contract-First webservice, meaning that we are designing the WSDL file by ourself rather than generating it based on Java classes, open the WSDL editor to change the service:

Org.eclipse.scout.jaxws.CreateWebServiceProvider 50.png

Detailed instructions are provided here: Change WSDL file to return a list of companies. Alternatively, you can download the changed WSDL file from the repository: CompanyWebService.wsdl.

As you changed the WSDL file, you have to regenerate the stub anew. Thereto, click on Rebuild webservice stub in the Scout Property View of the provider.

Rebuild webservice stub.

If the WSDL file is valid, the stub generation will succeed. Otherwise, please refer to the Console Output to see what went wrong. Because we changed the method getCompanies, compilation errors are shown in the CompanyWebService Port Type:

Compilation errors in Port Type due to change of WSDL file

Remove this wrong getCompanies method and add the unimplemented method instead:

Add unimplemented methods of port type interface.

As you can see, the method returns a list of companies. That is exactely what we wanted to have.

Finally, you have to implement the method getCompanies accordingly. Here, we simply return a list of all companies in database. Click here to get the source.

One last thing we still have to do. Because we configured the webservice to have authentication installed and to validate the request's credentials against config.ini, we have to specify the list of valid credentials in config.ini.

Authentication and credential validation settings

Thereto, add the following line to the config.ini: That allows the user eclipse/scout to access our webservice.

org.eclipse.scout.jaxws.security.provider.ConfigIniCredentialValidationStrategy#credentials=eclipse\=scout;

Log Webservice Providers's SOAP messages

To log the SOAP requests and response, click on Webservices (JAX-WS RI 2.1.6) > Provider > Services > CompanyWebService > Handler Registration.

Add DatabaseLogHandler to CompanyWebService

Click on the link Add handler chain to create a handler chain and Add handler to add a handler to the chain

Add DatabaseLogHandler to CompanyWebService

By clicking on the Browse button, choose DatabaseLogHandler as the log handler.

Test the Webservice Provider

Launch the server and open your browser. Enter the URL http://localhost:8080/tutorial_server/jaxws/ and you get a list of all your installed webservice providers.

This looks as follows:

Org.eclipse.scout.jaxws.WebserviceOverview.png

To test your webservice implementation, download a webservice testing tool such as SoapUI.

In SoapUI, create a new SoapUI project and enter http://localhost:8080/tutorial_server/jaxws/CompanyWebService?wsdl as your initial WSDL file. By double-clicking on the Request 1 node, the request dialog opens. On the property page, enter eclipse as username and scout as password. By clicking on the green play button, the request is sent to your webservice and the SOAP response appears on the right side.

Test webservice with SoapUI

See Also