Arun Gupta, Miles to go ...

TOTD #22: Java SE client for a Metro endpoint

Metro is the Web services stack in GlassFish. It is your one-stop shop from a simple Hello World to Secure, Reliable,  Transactional and .NET 3.0 interoperable endpoint. Metro Tooling is provided by NetBeans and other options are explained here.

Screencast #ws7 describes how a Metro endpoint can be easily created and deployed on GlassFish and invoked from a Web client using NetBeans IDE. This TOTD (as requested here and here) describes how a Secure and Reliable Metro endpoint can be invoked using a Java SE client.

Here is my environment:

• Windows Vista
• NetBeans 6
• GlassFish v2 (downloaded from glassfish.java.net and configured in NetBeans).
• Java SE 1.6.0 U4

Let's get started.

1. Following screencast #ws7 create a plain (without Reliability and Security enabled) Metro endpoint.
2. Create the Java SE client project
   1. In NetBeans IDE, create a new project of the type Java/Java Application. Name the project as "SEClient" and take all other defaults.
   2. Right-click on the newly created project, select "New", "Web Service Client...".
   3. Click on the "Browse..." button next to "Project" radio button and select the deployed Web service endpoint.
   4. Enter the package name as "client" and click on "Finish".
3. Invoke the plain Metro endpoint
   1. Right-click on the project, select "Properties", "Libraries", "Add JAR/Folder" and add "webservices-rt.jar" from the "lib" directory of GlassFish installation. Click on "OK".
   2. Expand the "Web Service References" node in the project and drag the leaf node in the "main" method of "Main.java" of the client project.
   3. Change the value of parameter "name" to "Duke".
   4. Right-click the project and select "Run". This will build the project, invoke the endpoint and show the results in Output window as "Hello Duke".
   5. If your GlassFish instance is configured to show SOAP messages then the following SOAP messages will be shown in the output window:
      
      ====[com.sun.xml.ws.assembler.server:request]====
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:sayHello xmlns:ns2="http://server/">
      <name>Duke</name>
    </ns2:sayHello>
  </S:Body>
</S:Envelope>
============
====[com.sun.xml.ws.assembler.server:response]====
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:sayHelloResponse xmlns:ns2="http://server/">
      <return>Hello Duke</return>
    </ns2:sayHelloResponse>
  </S:Body>
</S:Envelope>
============
4. Invoke the Reliable Metro endpoint
   1. Following the instructions in screencast #ws7, enable Reliability on Metro endpoint and re-deploy.
   2. In the client project, select the first child node of "Web Service References", right-click and select "Refresh Client".
   3. In the "Confirm Client Refresh" window, select "Also replace local wsdl file with original WSDLs located at:" checkbox and click on "Yes".
   4. Right-click the client project and select "Run". This will build the project, invoke the endpoint and show the results in Output window as "Hello Duke".
   5. The SOAP messages during this run will now contain Reliable Messaging protocol messages and resemble as shown below:
      
      ====[com.sun.xml.ws.assembler.server:request]====
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <To xmlns="http://www.w3.org/2005/08/addressing">http://localhost:8080/SEEndpoint/HelloServiceService</To>
    <Action xmlns="http://www.w3.org/2005/08/addressing">http://schemas.xmlsoap.org/ws/2005/02/rm/CreateSequence</Action>
    <ReplyTo xmlns="http://www.w3.org/2005/08/addressing">
      <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
    </ReplyTo>
    ...
5. Invoke the Secure Metro endpoint
   1. Following the instructions in screencast #ws7, disable Reliability and enable Security on Metro endpoint and re-deploy.
   2. In the client project, select the first child node of "Web Service References", right-click and select "Refresh Client".
   3. In the "Confirm Client Refresh" window, select "Also replace local wsdl file with original WSDLs located at:" checkbox and click on "Yes".
   4. Right-click on the first child of "Web Service References" node, select "Edit Web Service Attributes" and select "Use development defaults". This will ensure that client and endpoint security credentials match.
   5. Expand "Source Packages", "META-INF" and open "HelloServiceService.xml". The name of this file is derived from the service name at the endpoint and may be different. Specify the location of trust store by adding the following attributes to "sc:KeyStore" element:
      
      location="C:\testbed\glassfish\final\glassfish\domains\domain1\config\cacerts.jks" type="JKS" storepass="changeit"
      
      The updated element looks like:
      
      <sc:TrustStore wspp:visibility="private" peeralias="xws-security-server" location="C:\testbed\glassfish\final\glassfish\domains\domain1\config\cacerts.jks" type="JKS" storepass="changeit"/>
      
      Make sure to match the value of location and password of the trust store in your environment.
   6. Right-click the client project and select "Run". This will build the project, invoke the endpoint and show the results in Output window as "Hello Duke".
   7. The SOAP messages during this run are now secured using the default security profile in NetBeans. The SOAP messages resemble as shown below:
      
      ====[com.sun.xml.ws.assembler.server:request]====
<?xml version="1.0" ?>
<S:Envelope
  xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
  xmlns:exc14n="http://www.w3.org/2001/10/xml-exc-c14n#">
  <S:Header>
    <To xmlns="http://www.w3.org/2005/08/addressing" wsu:Id="5006">http://localhost:8080/SEEndpoint/HelloServiceService</To>
    <Action xmlns="http://www.w3.org/2005/08/addressing" wsu:Id="5005">http://server/HelloService/sayHelloRequest</Action>
    <ReplyTo xmlns="http://www.w3.org/2005/08/addressing" wsu:Id="5004">
      <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
    </ReplyTo>
    <MessageID xmlns="http://www.w3.org/2005/08/addressing" wsu:Id="5003">uuid:bb0e9571-a773-49bb-bad0-20a01d3af9f1</MessageID>
    <wsse:Security S:mustUnderstand="1">
      <wsu:Timestamp xmlns:ns10="http://www.w3.org/2003/05/soap-envelope" wsu:Id="3">
      <wsu:Created>2008-01-23T20:13:28Z</wsu:Created>
      ...

If you are using JDK version prior to Java SE 6 U4, then need to override the JAX-WS and JAXB API as described here. Java SE 6 U4 already includes JAX-WS and JAXB 2.1 APIs which are required for the Metro client to work.

Please leave suggestions on other TOTD that you'd like to see. A complete archive is available here.

Technorati: totd webservices metro glassfish netbeans javase

Posted by Arun Gupta in webservices  |  Comments[18]