|
|
| (11 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | {{ScoutPage|cat=Tutorial 3.7}}
| |
| − | == Abstract ==
| |
| − | This tutorial is a guide to developing [http://jax-ws.java.net/ JAX-WS] webservices in [http://www.eclipse.org/scout/ Eclipse Scout]. JAX-WS stands for '''J'''ava '''A'''PI for '''X'''ML '''W'''eb '''S'''ervices. 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 [http://jax-ws.java.net/2.2.5/ 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 [http://db.apache.org/derby/ Derby] database and allow the user to request a company's stock price with a 20 minute delay from the public [http://services.nexus6studio.com/StockQuoteService.asmx 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 our nightly updatesite:
| |
| − |
| |
| − | http://download.eclipse.org/scout/nightly/update/
| |
| − |
| |
| − | That is because Scout JAX-WS integration is not part of the [http://www.eclipse.org/indigo/ Eclipse Indigo] release but of the [http://www.eclipse.org/downloads/index-developer.php Eclipse Juno] release planned for mid of 2012.
| |
| − |
| |
| − | More details on how to do this can be found in the following {{ScoutLink|HowTo|Install Scout SDK|name=How-To}}
| |
| − |
| |
| − | == Resources ==
| |
| − | The Eclipse projects for this tutorial can be downloaded from our SVN at [https://dev.eclipse.org/svnroot/technology/org.eclipse.scout/scout.example/trunk/ 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 [https://dev.eclipse.org/svnroot/technology/org.eclipse.scout/scout.example/trunk/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://dev.eclipse.org/svnroot/technology/org.eclipse.scout/scout.example/trunk/org.eclipse.scout.tutorial.jaxws.database/script/create_database.sql create_database.sql] located in the Plug-In [https://dev.eclipse.org/svnroot/technology/org.eclipse.scout/scout.example/trunk/org.eclipse.scout.tutorial.jaxws.database org.eclipse.scout.tutorial.jaxws.database]. {{ScoutLink|Tutorial|3.7/Webservices with JAX-WS/Setup Derby database|Learn more}} on how to setup the derby database from scratch.
| |
| − |
| |
| − | == Preliminary work ==
| |
| − | First of all, you have to {{ScoutLink|Tutorial/3.7/Webservices with JAX-WS|Create Scout Project|create a new Scout project}}. Enter <code>org.eclipse.scout.tutorial.jaxws</code> as project name and choose <code>Outline Tree and Table Form</code> as template. {{ScoutLink|Tutorial/3.7/Webservices with JAX-WS|Configure Product Launch Configuration|Configure the product launch configuration}} to easily start the application.
| |
| − | Afterwards, {{ScoutLink|Tutorial|3.7/Create Derby SQL Service|name=create a Derby SQL Service}} to access company data and to persist webservice log entries. In order to display data from database, {{ScoutLink|Tutorial|3.7/Create Main Outline|name=create the Main Outline}} with a {{ScoutLink|Tutorial|3.7/Create Company Table Page|name=Company Table Page}} as its child page. In order to display stock quote information for a company, {{ScoutLink|Tutorial|3.7/Create Company Form|name=create a Company Form}}.
| |
| − |
| |
| − | To track webservice requests, they are logged into the database in the course of this tutorial. This is why a {{ScoutLink|Tutorial|Webservices with JAX-WS/Create WsLogTablePage|WS Log Table Page}} and {{ScoutLink|Tutorial|Webservices with JAX-WS/Create WsLogForm|WS Log Form}} 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 <code>org.eclipse.scout.jaxws216</code> to the server's required Plug-Ins in plugin.xml and to your product-files. {{ScoutLink|SDK|JAXWS-SDK/Add JAX-WS support to project|name=Learn more}} how to accomplish this.
| |
| − |
| |
| − | == 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.
| |
| − | Please find the created webservice consumer <code>StockQuoteWebServiceClient</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.
| |
| − |
| |
| − | == 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:
| |
| − |
| |
| − | '''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.
| |
| − | Please add the following conversion methods to your service.
| |
| − |
| |
| − | {{ScoutLink|Tutorial|Webservices with JAX-WS/Conversion methods for StockQuote service|name=Click here}} to get the source
| |
| − |
| |
| − | '''Change load-method to access webservice'''
| |
| − | 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:
| |
| − |
| |
| − | {{ScoutLink|Tutorial|Webservices with JAX-WS/Integrate StockQuote service into CompanyProcessService|name=Click here}} to get the source
| |
| − |
| |
| − | Finally, if you launch the application, you should see something like this:
| |
| − |
| |
| − | [[Image:Org.eclipse.scout.jaxws.tutorial.stockquote.png|400px]]
| |
| − |
| |
| − | == 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>.
| |
| − |
| |
| − | 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 {{ScoutLink|Concepts|JAXWS-RT/Handler|name=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'''
| |
| − | 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 {{ScoutLink|Tutorial|Webservices with JAX-WS/DatabaseLogHandler|name=following (source code)}}:
| |
| − |
| |
| − | After the handler is created, go back to the webservice consumer <code>StockQuoteWebServiceClient</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 {{ScoutLink|Tutorial|Webservices with JAX-WS/Register DatabaseLogHandler in webservice consumer|name=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:
| |
| − |
| |
| − | [[Image:Org.eclipse.scout.jaxws.tutorial.ApplicationWsLog.png|400px]]
| |
| − |
| |
| − | == 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 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 {{ScoutLink|Tutorial|Webservices with JAX-WS/Console Output for CompanyWebService|name=Console Output}} for more information.
| |
| − | 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].
| |
| − | 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 {{ScoutLink|Tutorial|Webservices with JAX-WS/Change WSDL file to return a list of companies|name=here}} to follow detailed instructions. Alternatively, you can download the changed WSDL file from [https://dev.eclipse.org/svnroot/technology/org.eclipse.scout/scout.example/trunk/org.eclipse.scout.tutorial.jaxws.server/WEB-INF/wsdl/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.
| |
| − |
| |
| − | Finally, you have to implement the method <code>getCompanies</code> accordingly. Here, we simply return a list of all companies in database. {{ScoutLink|Tutorial|Webservices with JAX-WS/CompanyWebService implementation|name=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 [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.
| |
| − |
| |
| − | <pre>
| |
| − | org.eclipse.scout.jaxws.security.provider.ConfigIniCredentialValidationStrategy#credentials=eclipse\=scout;
| |
| − | </pre>
| |
| − |
| |
| − | == 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.
| |
| − |
| |
| − | == Test the Webservice Provider ==
| |
| − | Launch the server and open your browser. Enter the URL [http://localhost:8080/tutorial/jaxws/ http://localhost:8080/tutorial/jaxws/] and you get a list of all your installed webservice providers.<br/>This looks as follows:
| |
| − |
| |
| − | [[Image:org.eclipse.scout.jaxws.WebserviceOverview.png|400px]]
| |
| − |
| |
| − | 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/jaxws/CompanyWebService?wsdl http://localhost:8080/tutorial/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 'eclise' 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.
| |
| − |
| |
| − | [[Image:org.eclipse.scout.jaxws.WebserviceTestWithSoapUI.png|400px]]
| |
| − |
| |
| − | ==See Also==
| |
| − | * [[:Category:Scout_JAXWS-RT|JAX-WS Runtime]]
| |
| − | * [[:Category:Scout_JAXWS-SDK|JAX-WS SDK]]
| |
| − |
| |
| − |
| |
| − | [[Image:Org.eclipse.scout.jaxws.CreateConsumer_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_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]]
| |
