Quick Start Guide 2011v1 Version 2011v1 2011 Standards for Technology in Automotive Retail David Carver STAR Jason Loeffler Karmak Jonathan Wilson Navistar Russell Shephard T-Systems Daniel Hicks Honda Charlie Quirt CIECA Michelle Vidanes STAR Bridget Almas STAR Oleg Litvak Karmak

The purpose of this document is to provide a guide for quickly getting up and running with the STAR Web Services.

The STAR Web Services Quick-Start Guide contains a brief introduction to the STAR web services and the development tools that can be used to create them, as well as some implementation examples. This document is not intended to be a comprehensive design specification or development reference.  It is only intended to give the reader the information necessary to gain a basic understanding of the STAR web services.

This document is intended for architects and web developers who are interested in implementing the STAR web services for STAR BOD document exchange.  The document was designed for developers with existing knowledge of implementation practices of Web Services.

The goal of the Standards for Technology in Automotive Retail (STAR) organization is to develop and promote the use of voluntary information technology (IT) standards as a catalyst to fulfill the business information needs of dealers and manufacturers while reducing the time and effort previously required.   To accomplish this goal, STAR has developed a series of Special Interest Groups (SIGs) to address specific points of interest in the retail automotive industry.  These SIGs, comprised of voluntary participants from member organizations, are chartered with: Developing and maintaining standard messaging formats for dealer communications.  STAR currently supports two formats: Establishing a common messaging architecture for transmitting standard message formats promoting interoperability among retail system providers (RSPs) and original equipment manufacturers (OEMs) throughout the retail automotive industry. The Architecture  SIG produces a series of documents referred to as the Transport Package that includes:

The STAR Web Services transport was designed to provide a platform for secure and reliable delivery of any type of content in a standardized manner.  The chosen architecture neither precludes nor requires attachments outside the body of the SOAP message for transportation of content.  The chosen packaging methodology is well supported by all major Web Services toolkits and infrastructures and meets STAR’s transport requirements.

Web services do not require the adoption of a common platform, but adherence to the standard protocols.  These protocols can be adhered to on most platforms. Web services are very versatile by design. Web services provide for code re-use in which the same web service can be used for several different clients. Web services can incorporate failover functionality. Web services provide easy integration with external data sources.

A development framework can be defined as a set of patterns, definitions and guidelines that assist how application development is performed.  Many software development tool vendors provide development frameworks along with their products that include best practices for program design and sample code or code generators that automatically create commonly used code fragments. This section contains an overview of some of the most popular development frameworks for web services.  It can assist you in the selection of a framework for your STAR web services development activities.

The Microsoft .NET Framework is a software component that can be added to or is included with Microsoft Windows operating system. It provides a large body of pre-coded solutions to common program requirements, and manages the execution of programs written specifically for the framework. The .NET Framework is a key Microsoft offering, and is intended to be used by most new applications created for the Windows platform. (wikipedia) This is the first release of the .NET Framework and is also part of the first release of Microsoft Visual Studio .NET.  The Microsoft .NET Framework is a software component that can be added to or is included with Microsoft Windows operating system. It provides a large body of pre-coded solutions to common program requirements, and manages the execution of programs written specifically for the framework. The pre-coded solutions that form the framework's class library cover a large range of programming needs in areas including: user interface, data access, database connectivity, cryptography, web application development, numeric algorithms, and network communications. The functions of the class library are used by programmers who combine them with their own code to produce applications.

Web Service Enhancements (WSE) is a Visual Studio.Net and .Net Framework add-on created by Microsoft to support .Net development teams in the development of web services implementing protocols pertaining to WS-Specifications. WSE version releases are triggered by changes in WS-Specifications and are independent of .Net Framework releases.  The first two versions are compatible with .Net Framework 1.0/1.1 while the latest version can be deployed with .Net Framework 2.0 and Visual Studio 2005. WSE 3.0 supports specifications such WS-Security 1.0/1.1, WS-Trust, WS-Secure Conversation, WS-Policy, WS-Addressing, WS-Reliable Messaging and MTOM, SOAP 1.1 and 1.2. It also includes capabilities to host web service outside IIS including console applications, windows services and forms and COM+ applications. WSE Configuration Editor (WSE Settings 3.0 Tool) is a graphical user interface supported in Visual Studio 2005. It enables user to specify WSE settings such as security, routing, policy, token issuing, diagnostics and messaging rather than editing configuration file directly.

Java is an extremely prolific language and there are a number of web services frameworks to choose from.   Each framework fits a particular need for implementing web services. The wide variety of frameworks is both an advantage and a disadvantage for those trying to choose what framework to use. The advantage is that the developer has a large selection of frameworks and features from which to choose. The disadvantage is that it can be difficult to determine which framework fits a project’s particular needs. This section will briefly describe the most popular frameworks, and where one can find more detailed information regarding each.

The Java Web Services Developer's Pack (JWSDP) is a framework stack maintained at the Sun Developer's Network (Sun).  Its purpose is to provide the necessary tools and frameworks for implementing secure and reliable web services using the java runtime.  The frameworks included are: JAX-WS – Implements the base Web Services specifications, such as, SOAP, WS-I Basic Profile 1.1, WS-I Attachments Profile 1.0, WS-I Simple SOAP Binding Profile 1.0, and WS-Addressing 1.0 JAXB – This is a data binding framework for XML.  It creates Java class objects for reading and writing XML files. WSIT – Extends the JAX-WS framework, so that it web services created with JAX-WS can interoperability with the Windows Communication Framework.  It uses both JAXB and JAX-WS. JAXP – A standardized API implemented by many XML parsers used for reading and writing XML files using either SAX or W3C DOM. XWSS - XML and Web Services Security is a framework for implementing the various WS-Security specifications. This includes SAML, X509a, and Username and Password. Unlike the Apache Axis 2 framework which allows for plugging in your own data banding framework, the Web Services Developer pack only directly supports the JAXB framework.  It may be possible to get the other frameworks to work with it but that is beyond the scope of this document.

Apache Axis 1.4 is the redesign and re-implementation of the Apache SOAP framework.  It is widely used and provides support for both a wide variety of SOAP design patterns.   Its sole goal is to implement support for the World Wide Web Consortium's SOAP specification.    It is still widely used but is also limited in its support for more current Web Services specifications.

Apache Axis 2 is a redesign of the Apache Axis 1.4 framework.  It has been redesigned to allow a plug-in architecture to support many of the new web services specifications.   Apache Axis 2 also allows you to choose and implement a variety of XML Data Binding frameworks instead of being locked into one particular framework.    The following are some of the plug-ins that extend Apache Axis 2: Apache Sandesha2 – Implements the WS-ReliableMessaging specification. Apache Kandula2 – Implements the WS-Coordination specification. Apache Rampart – Implements the WS-Security specification including the WS-SecurityPolicy specification.  Like the XWSS framework, this implements support for XML Security, Username and Password, and XML Signature. WS- Addressing support is built into the Apache Axis 2. Apache WSS4J – Implements the OASIS Web Services Security Specification. Apache Axis 2 is where the new development is heading at the Apache Foundation for web services.  Its plug-in architecture allows it to easily evolve and adapt to the changing web services specifications (apache).

XML RPC was one of the first specifications implemented.  Both Sun and Apache have implementations of the specification, and XML RPC is supported on a wide variety of platforms.   However, even though XML RPC is still widely used, it is not recommended for STAR implementations as it doesn't have support for many of the security related features STAR Web Services require.   The specification can be found at the XML RPC homepage (xmlrpc).

This is the first release of the .NET Framework and is also part of the first release of Microsoft Visual Studio .NET.  The Microsoft .NET Framework is a software component that can be added to or is included with Microsoft Windows operating system. It provides a large body of pre-coded solutions to common program requirements, and manages the execution of programs written specifically for the framework. The pre-coded solutions that form the framework's class library cover a large range of programming needs in areas including: user interface, data access, database connectivity, cryptography, web application development, numeric algorithms, and network communications. The functions of the class library are used by programmers who combine them with their own code to produce applications. Probably the most widely used Microsoft.Net tool is the Microsoft Visual Studio.Net development software (IDE).  The IDE provides specific goal oriented project types and visual functionality, which allow the developer to take full advantage of the .Net Framework.  Example project types include ASP.Net Web Service, ASP.Net Web Application, and Windows Application.  The ASP.Net Web Service project type provides basic skeleton code of a web service, so the developer need only fill in the details.  The Windows Application and ASP.Net Web Application project types provide graphical functionality for the developer to (for instance) set a “web reference” to a web service, which automatically creates a proxy of the target web service.  This allows the developer to quickly write code to access and communicate with the target web service.

In addition to the various frameworks for Java Web Service development, Java also has many development environments implementing these frameworks.   These tools range from open source to commercially available tools.  Each has its advantages and disadvantages, the tool one chooses depends on many factors and in particular the environment in which one is targeting their web service implementation. The Eclipse Foundation's Web Tools Project includes a wide variety of added functionality for working with Web Services implementations.   It includes built in support for working with Apache Axis 1.4 and Apache Axis 2 frameworks.   It also includes a basic set of tools for working with XML, XSD, and WSDL files.    In addition, it includes a Web Services Explorer for testing and debugging Web Services either developed with the tool or hosted on another system.    The Eclipse Web Tools Platform is a free set of plug-ins available from the eclipse website (eclipse).    Additional functionality such as UML, BPEL and other tools can be downloaded from the Eclipse website. Netbeans is one of the first Java IDEs on the market is developed with Sun Microsystems as an open source project.  The Enterprise Pack add-in includes support for working with the Java Web Services Developer's Pack.   It also includes several base XML, XSD, and WSDL editing tools.   It also includes a BPEL designer and UML modeling tools. IBM has built Rational Software Architect on top of the Eclipse Platform and it includes the Eclipse Web Tools Platform as well.  In addition, IBM has included tools specific for working with its IBM Websphere application server, and UML Modeling tools. BEA has migrated their Weblogic Worshop IDE to the Eclipse platform and the Eclipse Web Tools Platform plug-ins.   In addition, they have extended this base platform to include tools for working with XML Beans, enhanced support for a variety of web services frameworks, and the BEA Weblogic application server. J-Builder 2007 is CodeGear's, formerly Borland, Java IDE.  It has been migrated to using the Eclipse Platform and Eclipse Web Tools Platform.  It also has extended the functionality by including both an EJB and Web Services visual designer.

XMLSpy 2007 by Altova supports development in a wide variety of Web services platforms including Microsoft .Net, J2EE, and Eclipse.   Stylus Studio 2007 XML Enterprise Suite, Release 2 by DataDirect Technologies utilizes an open Web service framework architecture that fully supports frameworks such as Microsoft SOAP, Microsoft .Net and the open source Web service framework, Apache Axis.   Liquid XML Data Binder is a multi-platform data binding framework for use with XML Schema. It will generate data objects for C#, VB.NET, JAVA, VB6, and C+. It supports both DTD and W3C XML Schemas. Source code is available for the libraries, allowing for recompiling the base application on almost any platform.   Liquid XML Data Binder is a product of Liquid Technologies.

Most toolsets and integrated development environments include some basic testing for the web services that are developed.  Typically this includes a tool that can read an existing WSDL, and communicate to a server that has already been established.  Other tools allow for the complete testing of a web service from both the server side and the client side.  The tools that follow are only a few of the tools that are available to users, and are a few that STAR members are using to develop and test their Web Services.

SOAPUI is a java based tool for testing and working with any type of Web Service.  All that is needed is a WSDL file whether stored locally or remotely.  The program will read the WSDL and generate some mock code that can emulate a server or act as a client.   SOAPUI comes in two versions.   An open source version that is free, and provides most of the features one will need for testing Web Services.  It also comes in a Professional version which extends the testing suite ability and provides some further advanced features for running test suites.

OxygenXML is a full featured XML Integrated Development Environment for working with a wide variety of XML related technologies.   It includes a set of programs for working with and testing WSDL files.   The WSDL Analyzer allows you to use an existing WSDL as a client application, and test against a Server instance.   The basic soap envelope and payloads are generated, and available for editing.  The corresponding results received back from the service are available for editing and viewing later.   OxygenXML is a commercial application, but is available for a 30 day trial.

XML Spy Enterprise Edition 2008 includes a WSDL Graphical Editor, as well as a SOAP Client and SOAP Debugger.   The latter two allow for interactive debugging of the SOAP messages sent and received from a web service.  It has the ability to step through the service, set break points, and set conditional break points based on an XPATH expression.

This section will provide the reader with STAR web service implementation examples for a number of the development frameworks.  The implementation examples have been contributed by the STAR members that are currently implementing the web services.  Currently there are only a few implementation examples available.  As STAR receives examples for additional development frameworks, they will be added to future releases of the STAR Web Services Quick-Start guide. The STAR WSDLs can be found in the STAR Schema Repository. The zip file containing the latest released version of the repository can be downloaded from the XML Schemas area on the STAR website. The zip file is named STARSchemaRepository_RevXXX.zip, where XXX represents the current revision number. Milestone and Draft releases of the STAR Schema Repository can also be downloaded from the STAR Portal Site. They are located in the XML and DTS Workgroup section of the Documents repository on the portal.The WSDL files are located in the "STAR\RevX.X.X\WSDL\Templates" subdirectory of the repository zip file (where "X.X.X" represents the release revision number).

The scope of this section is the construction of a basic asp.net web service generated from the STAR WSDL.   A windows client application will be created to simulate a user calling and receiving response from the web service using the ProcessMessage web method.   Microsoft WSE related implementations of WS-Security and WS-Addressing and other STAR requirements and/or recommendations are not implemented in this guide.

Create an ASP.Net Web Service based on a class generated from the STAR WSDL. Create a windows form application that calls the web service. Client application will call the Web Service’s ProcessMessage function. Web service will return the payload to the client with a different ContentID to simulate processing.

A copy of the WSDL from the Star Schema Repository (Schema Version 4.2.4 is used for this example). Installation of Microsoft Visual Studio.Net 2003. .Net Framework 1.1 7Zip or similar program able to handle zip files.

Retrieve WSDL from Star Schema Repository and extract the StarTransport_2005.wsdl file.

Open Visual Studio 2003 command prompt.

Run wsdl.exe against the extracted WSDL file.  By default WSDL generated codes are generated in C# language. You can optionally specify the target language to ‘VB’ (Visual Basic) by using the /language parameter. Make sure to execute this command where you have extracted the STAR WSDL. wsdl startransport_2005.wsdl /language:VB Open up the Visual Studio .Net 2003 and create a new ASP.Net Web Service Project.

Rename the Service1.asmx file to StarWebService.asmx.

Copy contents of generated GenericWebService.vb to the code behind of your new web service page. Rename the Class name to StarWebService

Set the URL in the class constructor to the actual URL of the web service.

Add a WebMethod attribute for each of the STAR WebMethods.

Replace the ProcessMessage function’s code with the following line:

Insert the following function anywhere inside the class code.

Modify the ASMX file to refence the StarWebService Class.

Compile the code and run.  You should now have a web service that has all three STAR Methods.

In this section, we will be creating a windows form application that calls the Web Service’s ProcessMessage method. Create a new windows application project.

Create a Windows form that has the following layout:

Add a web reference to the star web service you’ve previously created.

Create a function that would process the request BOD.

Recompile the Client Code. Run the windows application code and copy any STAR BOD examples from the Repository's example folder to the Input BOD text box.

Click on the Submit button and examine the output BOD and Content IDs in the Diagnostic Textbox.

This example uses Sun’s JAX-WS implementation to create a Web Service and client. The JAX-WS implementation is part of the Metro Web Service framework, a subset of Sun’s Project GlassFish and a continuation of the work Sun packaged as the Java Web Services Developer Pack (JWSDP). The homepage for Metro is https://metro.dev.java.net/ . The target runtime for the service is the Apache Tomcat Server. The client will be a standalone application. This example was created using the JDK 5.0 Update 14, JAX-WS 2.1.2, and Tomcat 5.5. While some of the screen shots will show Eclipse 3.3, Eclipse is not required for this example. Eclipse was primarily used to give a visual representation of the WAR, but it was used in some instances for source editing.

JAX-WS can be downloaded from the JAX-WS homepage at https://jax-ws.dev.java.net/ Since our target runtime is Tomcat, refer to the Tomcat homepage ( http://tomcat.apache.org/ ) for download and installation instructions. Both service and client will be generated using the wsimport tool included with JAX-WS. This tool can be found in <JAX-WS Install Directory>\jaxws-ri\bin\wsimport.bat. A document describing the tool is available at <JAX-WS Install Directory>\jaxws-ri\docs\wsimport.html.

If the WSDL was retrieved from STAR repository, the service information in the WSDL is incomplete. It must be changed to reflect your Web Service implementation. An unmodified WSDL will have an XML comment beginning with “Note to implementors…” along with an example of what the address information should look like. The example below is based off of the ProcessRetailDeliveryReporting.wsdl in Rev5.2.1. Assuming you are running a local instance of Tomcat, with 8080 as your HTTP port, the service information will look like the following: <wsdl:service name="ProcessRetailDeliveryReportingWebService"> <wsdl:port name="ProcessRetailDeliveryReportingStarTransport" binding="starbindings:starTransport"> <soap:address location="http://localhost:8080/StarQuickStartService/StarTransport/"/> </wsdl:port> </wsdl:service> Once the WSDL has been edited with the address information, it can be used by wsimport to produce source for the service and client, as well as classes for JAXB marshalling and unmarshalling. At a windows command prompt, move to the <JAX-WS Install Directory>\jaxws-ri\bin directory. Execute the wsimport script. Be sure to set the output location for the source (-s) since the default behavior is to produce compiled code. This location must already exist since the script will not create the directory for you. It will give an error, “directory not found…” if the directory does not exist. Also, if you run into memory errors, edit the wsimport.bat script to increase the Java heap size. For this example the initial and maximum values were increased to 512MB, so the launch section of the wsimport.bat script looked like this (edited section in bold): %JAVA% %WSIMPORT_OPTS% -Xms512M -Xmx512M -jar "%JAXWS_HOME%\lib\jaxws-tools.jar" %* wsimport -d classes -s src -verbose C:\JAX-WS\jaxws-ri\bin\STAR\Rev5.1.2\WSDL\ProcessRetailDeliveryReporting.wsdl > results.txt Import the generated source into a WAR, adding the necessary jar files from <JAX-WS Install Directory>\jaxws-ri\lib

Create the Web Service implementation class. This class can implement the StarTransportPortTypes interface that was created by wsimport. It is not required that it implement the interface, though it may help if using an IDE since the IDE can generate the inherited abstract methods. For this example, I called my class ProcessRetailDeliveryReportingWebServiceImpl. Once this class is created, add an annotation above the class declaration to refer to the endpointInterface: @javax.jws.WebService (endpointInterface="org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes") For now, only add print statements to the implementation class so you can tell when you have called the method via the client that we will soon create. Below is how your ProcessRetailDeliverWebServiceImpl class should currently look: package org.starstandards.webservices._2005._10.transport.bindings; import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingPayload; import org.starstandards.webservices._2005._10.transport.ProcessRetailDeliveryReportingPayload; @javax.jws.WebService (endpointInterface="org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes") public class ProcessRetailDeliveryReportingWebServiceImpl implements                 StarTransportPortTypes {         public AcknowledgeRetailDeliveryReportingPayload processMessage(                         ProcessRetailDeliveryReportingPayload payload) {                 System.out.println("Called processMessage");                 return null;         }         @SuppressWarnings("unchecked")         public AcknowledgeRetailDeliveryReportingPayload pullMessage()     {             System.out.println("Called pullMessage!");             return null;     }         public void putMessage(ProcessRetailDeliveryReportingPayload payload) {                 System.out.println("Called putMessage");         } } Before our service is complete, we need to configure the application so that a Web Service call will be routed to the implementation class we just created. This is done by editing the web.xml and creating a JAX-WS configuration file, sun-jaxws.xml. Three items need to be added to the web.xml: A listener reference to the JAX-WS WSServletContextListener A servlet reference to the JAX-WS WSServlet servlet A servlet-mapping reference for the above servlet For this example, here are those following items: <listener>   <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class> </listener> <servlet>   <servlet-name>StarTransportPort</servlet-name>   <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>   <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping>   <servlet-name>StarTransportPort</servlet-name>   <url-pattern>/StarTransport</url-pattern> </servlet-mapping> Now it’s time to create the sun-jaxws.xml. This file resides in the same location as the web.xml, the WEB-INF folder. Below is the content of the file for this example: <?xml version="1.0" encoding="UTF-8"?> <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime" version="2.0">   <endpoint         name="starTransportPortTypes"         interface="org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes"         implementation="org.starstandards.webservices._2005._10.transport.bindings.ProcessRetailDeliveryReportingWebServiceImpl"         url-pattern="/StarTransport" /> </endpoints> Note that the endpoint name is the same as the name that you see on the Java annotation from the StarTransportPortTypes class. Also, the interface and implementation classes are provided. The url-pattern provided must match what is in the web.xml file. The service is now ready to deploy. Deploy the WAR to Tomcat or the application server you are working with. You can confirm installation by accessing the service’s URL. For this example, the service can be accessed at http://localhost:8080/StarQuickStartServiceJAXWS/StarTransport in a browser. The following should be returned:

Now it is time to create the client. Since the client uses the same source files generated by wsimport that were used for the service, the only item to create is a new class and method that will use the generated code to call the service. Below is an example of a test client that calls the PullMessage method. Since there is currently no implementation code in our service, we will at least see the print statement (“Called pullMessage”) from the service printed to the standard output of the application server. Until implementation code is added to the service to return a valid response, this client will throw an exception. package org.star.quickstart.client; import org.openapplications.oagis._9.unqualifieddatatypes._1.IdentifierType; import org.starstandard.star._5.AcknowledgeRetailDeliveryReportingType; import org.starstandard.star._5.ApplicationAreaType; import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingContent; import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingPayload; import org.starstandards.webservices._2005._10.transport.bindings.ProcessRetailDeliveryReportingWebService; import org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes; public class TestClient {     public static void main(String[] args)     {       ProcessRetailDeliveryReportingWebService stub = new ProcessRetailDeliveryReportingWebService();       StarTransportPortTypes port = stub.getProcessRetailDeliveryReportingStarTransport();           ((javax.xml.ws.BindingProvider)port).getRequestContext() .put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/StarQuickStartServiceJAXWS/StarTransport");       AcknowledgeRetailDeliveryReportingPayload payload = port.pullMessage();       AcknowledgeRetailDeliveryReportingContent content = payload.getContent().get(0);       AcknowledgeRetailDeliveryReportingType bod = content.getAcknowledgeRetailDeliveryReporting();       ApplicationAreaType applicationArea = bod.getApplicationArea();       IdentifierType BODID = applicationArea.getBODID();       System.out.println("BODID returned: " + BODID.getValue());     } } Once you have created the TestClient class, execute the main method and verify that “pullMessage” has been written to the application server logs by the service. Now that we have verified that the client can communicate to the service, we can add some JAXB unmarshalling code to service to simulate producing a valid response. Similarly, we can add marshalling code to the client to print out the AcknowledgeRetailDeliveryReporting BOD returned from the service. Below is the code added to the pullMessage method of the service implementation class. In this example, the BOD is being read straight from the “examples” directory of a STAR repository. Using the JAXB unmarshaller, the xml data from the file is placed into the Java objects reference by the AcknowledgeRetailDeliveryReportingType class. @SuppressWarnings("unchecked")     public AcknowledgeRetailDeliveryReportingPayload pullMessage()     {         System.out.println("Called pullMessage!");         AcknowledgeRetailDeliveryReportingPayload response = new AcknowledgeRetailDeliveryReportingPayload();         AcknowledgeRetailDeliveryReportingContent content = new AcknowledgeRetailDeliveryReportingContent();         try         {             JAXBContext jaxbContext = JAXBContext.newInstance("org.starstandard.star._5");             Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();             JAXBElement<AcknowledgeRetailDeliveryReportingType> bod =            (JAXBElement<AcknowledgeRetailDeliveryReportingType>) unmarshaller .unmarshal(new File("C:\\jaxws-ri\\bin\\STAR\\Rev5.2.1\\BODExamples\\AcknowledgeRetailDeliveryReporting.xml"));             content.setAcknowledgeRetailDeliveryReporting(bod.getValue());         }           catch(Exception e)           {               e.printStackTrace();           }         response.getContent().add(content);         return response; } Before adding the marshalling code to the client, deploy the service again with the updated implementation code from above. Invoke the service with the TestClient created earlier. If successful, the BOD Id will be printed. Below is the code added to the TestClient to take the results from the PullMessage call and print the resulting XML to the standard output stream. The JAXB marshaller is used to get the XML content from the Java object. package org.star.quickstart.client; import java.io.StringWriter; import javax.xml.bind.JAXBContext; import javax.xml.bind.JAXBElement; import javax.xml.bind.Marshaller; import org.starstandard.star._5.AcknowledgeRetailDeliveryReportingType; import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingContent; import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingPayload; import org.starstandards.webservices._2005._10.transport.bindings.ProcessRetailDeliveryReportingWebService; import org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes; public class TestClient {     public static void main(String[] args)     {       ProcessRetailDeliveryReportingWebService stub = new ProcessRetailDeliveryReportingWebService();       StarTransportPortTypes port = stub.getProcessRetailDeliveryReportingStarTransport();           ((javax.xml.ws.BindingProvider)port).getRequestContext() .put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/StarQuickStartServiceJAXWS/StarTransport");       AcknowledgeRetailDeliveryReportingPayload payload = port.pullMessage();       AcknowledgeRetailDeliveryReportingContent content = payload.getContent().get(0);       AcknowledgeRetailDeliveryReportingType bod = content.getAcknowledgeRetailDeliveryReporting();       try       {           JAXBContext jaxbContext = JAXBContext.newInstance("org.starstandard.star._5");           Marshaller marshaller = jaxbContext.createMarshaller();           JAXBElement<AcknowledgeRetailDeliveryReportingType> processRetailDeliveryReportingElement =                (new org.starstandard.star._5.ObjectFactory()).createAcknowledgeRetailDeliveryReporting(bod);          marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);           StringWriter writer = new StringWriter();          marshaller.marshal( processRetailDeliveryReportingElement, writer );          String xmlStr = writer.toString();           System.out.println(xmlStr);       }       catch(Exception e)       {           e.printStackTrace();       } } } After adding this code to the TestClient class, run the main method again. Now the entire AcknowledgeRetailDeliveryReporting BOD will be printed.

In this example we will use the Apache Axis2 framework to generate a simple Web Service and client. The homepage for Axis2 is http://ws.apache.org/axis2/ . The target runtime for the service is the Apache Tomcat server. The client will be a standalone application. This example was created using the JDK 5.0 Update 14, Apache Ant 1.6.5, Apache Axis2 release 1.3, and Tomcat 5.5.

Prerequisites: Follow the instructions on downloading and installing the Axis2 binary distribution ( http://ws.apache.org/axis2/1_3/installationguide.html#standalone1 ). Since our target runtime is Tomcat, refer to the Tomcat homepage ( http://tomcat.apache.org/ ) for download and installation instructions. Once Tomcat is installed, follow the instructions to install Axis2 ( http://ws.apache.org/axis2/1_3/installationguide.html#servlet_container ). Both service and client will be generated using the “WSDL2Java” script included with the Axis2 binary distribution. This script takes a WSDL file as input and generates the appropriate Java classes as output. The “Axis2 Reference Guide” ( http://ws.apache.org/axis2/1_3/reference.html ) lists the parameters for the script and shows example usage.

If the WSDL was retrieved from the “STAR Web Services Specifications” document, it is missing a crucial section in order for the script to properly generate the code. This is the service section, which contains information specific to your Web Service implementation, including the address of the Web Service. Assuming you will be running a local instance of Tomcat for this example, the following information can be added to the STAR WSDL: <wsdl:service name="StarQuickStartServiceAxis2">   <wsdl:port name="StarTransport" binding="starbindings:starTransport">      <soap:address location="http://localhost:8080/StarQuickStartServiceAxis2/StarTransport"/>   </wsdl:port> </wsdl:service> Generating server code: Using the aforementioned WSDL2Java script, generate the Java code for the service. At a windows command prompt, move to the bin directory of your Axis2 installation. Execute the WSDL2Java script with the -uri option to specify the location of the STAR WSDL, the -ss and -sd options to generate the server code and service descriptor, and the -o option to specify the output location. By default the script generates client code. This is why the options are needed for the service artifacts.  

The script will create a src folder for the source code, a resources folder for the services.xml and a generated wsdl, and an ant build script. These are all the files needed for a simple service implementation. Note that the generated wsdl is identical to the one specified as input to the script, though formatting changes have been made. Modify Service Skeleton with Implementation Code: One of the Java classes generated by WSDL2Java is a “skeleton” for the code you will eventually implement to handle Web Service calls. If you modified the WSDL with the service information from above, this class will be named “StarQuickStartServiceAxis2Skeleton.” Add code to this class to indicate the service is being invoked. If you do not modify this class, the methods will throw an UnsupportedOperationException when called since this is what has been generated by default.

Generate Axis Archive (*.aar) for the Web Service Once the skeleton class has been modified, the Web Service is ready to be packaged as an Axis Archive. Using the ant build file generated by WSDL2Java, execute the “jar.server” target.

 Once the script is complete, StarQuickStartServiceAxis2.aar will be in the build/lib folder. The service is ready to be deployed to the application server using the Axis2 Web application you installed as a part of the prerequisites. If you are using defaults, this application can be accessed at http://localhost:8080/axis2/ . The page will look similar to the screenshot below.

Click on the “Administration” link. When prompted to login, the initial username/password is admin/axis2. Refer to the “Apache Axis2 Web Administrator’s Guide” (http://ws.apache.org/axis2/1_3/webadminguide.html) for instructions on how to change the default login as well as other information regarding the application. Below is a screenshot of the administration console.

Use the “Available Services” link to check the deployment of the Web Service. You should see the “StarQuickStartServiceAxis2” listed:

Using the WSDL2Java script again, generate the Java code for the client. Follow the same steps used to generate the service, but exclude the -ss and -sd options that were used to generate the service-specific code. You can also change the output location in order to separate your service and client code.

Use Generated Stub to call Web Service. The output of WSDL2Java generating a client will be a “Stub” class that will be used to call the Web Service. For this example, we will use the Stub class to transmit a ProcessPartsOrder BOD via a PutMessage call. Below is an example of a main method using the StarQuickStartServiceAxis2Stub generated by WSDL2Java. This code reads the BOD from a file. package org.star.quickstart.client; import java.io.*; import javax.xml.stream.*; import org.apache.axiom.om.*; import org.apache.axiom.om.impl.builder.*; import org.apache.axis2.*; import org.apache.axis2.databinding.types.*; import org.starstandards.www.webservices._2005._10.transport.bindings.*; import org.starstandards.www.webservices._2005._10.transport.bindings.StarQuickStartServiceAxis2Stub.*; public class TestClient {   public static void main(String[] args) {       try {         String endpoint = "http://localhost:8080/axis2/services/StarQuickStartServiceAxis2";         StarQuickStartServiceAxis2Stub stub = new StarQuickStartServiceAxis2Stub(endpoint);         //Create Payload Manifest         PayloadManifest0 payloadManifest0 = new PayloadManifest0();       PayloadManifest payloadManifest = new PayloadManifest();         Manifest manifest = new Manifest();         manifest.setContentID(new IDRef("Content0"));         manifest.setElement("ProcessPartsOrder");         manifest.setNamespaceURI(new URI("http://www.starstandard.org/STAR/5"));         manifest.setVersion("5.2.1");         Manifest[] manifestAry = new Manifest[] { manifest };         payloadManifest.setManifest(manifestAry);       payloadManifest0.setPayloadManifest(payloadManifest);         PutMessage putMessage = new PutMessage();         Payload payload = new Payload();       //Create Content         Content content = new Content();         content.setId(new Id("Content0"));         //Read in Process Parts Order BOD         XMLStreamReader parser = XMLInputFactory.newInstance()           .createXMLStreamReader( new FileInputStream("C:\\axis2-1.3\\bin\\STAR\\Rev5.2.1\\BODExamples\\ProcessPartsOrder.xml"));         StAXOMBuilder builder = new StAXOMBuilder(parser);         OMElement documentElement = builder.getDocumentElement();         content.setExtraElement(documentElement);         payload.addContent(content);         putMessage.setPayload(payload);         //Call PutMessage operation         stub.PutMessage(putMessage, payloadManifest0);     } catch (Exception e) {         e.printStackTrace();     }   } } Once this class is complete, it can be used to call the Web Service deployed to Tomcat. If you added a println statement to the PutMessage method of your skeleton, you should now see the message in the Tomcat stdout log. The client may receive an error on the response from the service; this is because additional work is necessary to complete the Web Service and client.

The STAR WCF (Windows Communication Foundation) transport was designed to provide a platform for secure and reliable delivery of any type of content in a standardized manner for distributed computing, interoperability and service orientation. The chosen architecture neither precludes nor requires attachments outside the body of the SOAP message for transportation of content.

The WCF programming model supports several different programming paradigms including ASP.NET web services, .NET framework remoting and Enterprise Services. WCF provides integration and interoperability with existing .NET framework distributed systems technologies such as MSMQ, COM+, ASP.NET web services and WSE. WCF built applications interoperate well with non-WCF applications. Interoperability with non-SOAP based XML formats using only HTTP as the transport and application protocol.

The Microsoft .NET Framework is a software component that can be added to or is included with Microsoft Windows operating system. It provides a large body of pre-coded solutions to common program requirements, and manages the execution of programs written specifically for the framework. The pre-coded solutions that form the framework's class library cover a large range of programming needs in areas including: user interface, data access, database connectivity, cryptography, web application development, numeric algorithms, and network communications. The functions of the class library are used by programmers who combine them with their own code to produce applications. Typically, developers use Visual Studio as their IDE in order to utilize the .NET framework to construct applications.

The service contract outlines the operations that will be available on the service. The service contract is defined by decorating the service class or interface with the ServiceContract attribute. Arguments to the attribute should include the name of the configuration which links it to the settings in the configuration file, as well as the SessionMode argument enabling session-ful conversations. Allowing session in the service contract is required for Reliable Messaging since the conversation must maintain state over many requests. In the following example, the configuration name is set to starTransportPortTypes and the SessionMode is set to Allowed in the ServiceContractAttribute to enable session-ful reliable messaging conversations. The svcutil.exe utility which comes with Visual Studio 2008 will create the service contract and supporting types for you automatically based on the STAR WSDL and XSD schema files. However, the contract will have to be modified to remove the Action qualifiers and other attributes which interfere with the WS-Addressing implementation. Failure to remove these will result in the service showing no operations available. One can use Visual Studio 2008’s WCF service project type to quickly create a skeleton WCF project.

The example contract below (modified from the standard svcutil output) should work for any basic STAR service in WCF. The types ProcessMessageRequest, ProcessMessageResponse, PutMessageRequest, and etc. can be used as-is from the svcutil.exe output. [System.ServiceModel.ServiceContractAttribute( ConfigurationName="starTransportPortTypes", SessionMode=System.ServiceModel.SessionMode.Allowed)] public interface starTransportPortTypes { [System.ServiceModel.OperationContractAttribute()] [System.ServiceModel.XmlSerializerFormatAttribute()] ProcessMessageResponse ProcessMessage(ProcessMessageRequest request); [System.ServiceModel.OperationContractAttribute()] [System.ServiceModel.XmlSerializerFormatAttribute()] PutMessageResponse PutMessage(PutMessageRequest request); [System.ServiceModel.OperationContractAttribute()] [System.ServiceModel.XmlSerializerFormatAttribute()] PullMessageResponse PullMessage(PullMessageRequest request); } To use this contract, simply open up the file IService1.cs that was auto-generated by Visual Studio and replace its contract with the one above. The service configuration sets up the behaviors available in the web service and configures the endpoints that will be available. Note that the endpoint address MUST match the address that the public will use to access the site for the default WS-Addressing to work properly. The “mex” endpoint provides the mechanism by which the WSDL can be retrieved with the “?WSDL” query string. Removing this endpoint prevents retrieval of the WSDL in this fashion. The “WCF Service Configuration Editor” tool in Visual Studio 2008 (SvcConfigEditor.exe) is an easy way to set up the configuration file. It can also be used to enable diagnostics for tracing messages and viewing SOAP headers to examine the operation of the service.

To use the configuration above, simply open the file called web.config that was auto-generated by Visual Studio 2008 and replace its code with the code above.

With the service contract defined, the implementation must be created. Note the use of the ServiceBehavior class attribute, which allows incoming request contexts to retain a constant session while the Reliable Messaging conversation takes place. The code below can replace the default code that was auto-generated in the file Service1.svc. [System.ServiceModel.ServiceContractAttribute( ConfigurationName="starTransportPortTypes", SessionMode=System.ServiceModel.SessionMode.Allowed)] public interface starTransportPortTypes { [System.ServiceModel.OperationContractAttribute()] [System.ServiceModel.XmlSerializerFormatAttribute()] ProcessMessageResponse ProcessMessage(ProcessMessageRequest request); [System.ServiceModel.OperationContractAttribute()] [System.ServiceModel.XmlSerializerFormatAttribute()] PutMessageResponse PutMessage(PutMessageRequest request); [System.ServiceModel.OperationContractAttribute()] [System.ServiceModel.XmlSerializerFormatAttribute()] PullMessageResponse PullMessage(PullMessageRequest request); }

To create a client which will talk to our service, we create a service proxy with svcutil.exe or the tool of your choice. Just like we have on the server side, the client must configure the endpoint behaviors in the configuration file and enable reliable sessions.

If you are a current STAR member you will have access to the various web services discussion groups available within the STAR online collaboration tool.  The discussion groups contain valuable information contributed by STAR and its members regarding the development and implementation of the STAR web services. If you are a current member and you do not yet have access to the online collaboration tool, please contact David Carver at dcarver@starstandard.org to request a user account and login instructions. STAR Architecture SIG: Contains the latest STAR Transport Package STAR XML Schema: Contains the latest STAR Schema Repository OASIS: Contains numerous web services specifications. WS-I.org: Interoperability profiles for web services. Microsoft MSDN Developer Library Sun Java JAXB: A data binding framework for XML and java. Apache Axis 2: A data binding framework for XML, java, and C maintained by the Apache Software Foundation. .NET Framework Developer Center March 2009 Apache Software Foundation Dec. 2007 Apache Software Foundation Dec. 2007 Dec. 2007 Apache Software Foundation Dec. 2007 Dec. 2007 Apache Software Foundation Dec. 2007 March 2009 Eclipse Foundation 20 Jan. 2008 15 Nov. 2007 Wikipedia Dec. 2007 java.sun.com Dec. 2007 Dec. 2007 Sun Microsystems Dec. 2007 March 2009 DataDirect Dec 2007 Oct 2007 XMLRPC.com March 2009 Altova 20. Jan. 2008 2010 Microsoft Corporation April 2010 Wikipedia Asynchronous In the context of STAR Transport, Asynchronous means that a specific thread of execution sending a message does NOT wait for an application level reply before continuing on to other processing or completing execution. For example, when a STAR message is sent asynchronously over HTTP, the thread of   execution waits only for an HTTP reply or HTTP error before continuing, it does not wait for a transport level Acknowledgment or a business level Acknowledgment before continuing; the environment executing the thread may expect a Transport level and or Business level reply to be received later as in inbound message in a completely separate and unrelated HTTP session. European Committee for Standardization /  Information Society Standardization System (CEN/ISSS) CEN/ISSS “CEN/ISSS provides market players with a comprehensive and integrated range of standardization services and products, in order to contribute to the success of the Information Society in Europe.” (CEN) Digital Certificate A digital certificate is an electronic attachment issued by a certification authority containing credentials such as “name, a serial number, expiration dates, a copy of the certificate holder's public key (used for encrypting messages and digital signatures), and the digital signature of the certificate-issuing authority so that a recipient can verify that the certificate is real.” ( SearchSecurity.com ) Digital Signatures A digital signature (not to be confused with a digital certificate) is an electronic signature that can be used to authenticate the identity of the signer of a document, and to ensure that the original content of the message is unchanged. The ability to prove that an original signed message arrived infers that the sender cannot easily repudiate it later.   Extensible Markup Language XML Extensible Markup Language (XML) is a standard way of representing data in human-readable structures to be exchanged between business partners.  XML was developed by the W3C. Encryption Processing and altering data so only the intended recipient can read or use it. The recipient of the encrypted data must have the proper decryption key and algorithms to decipher the data back to its original form. Organization for the Advancement of Structured Information Standards OASIS “Organization for the Advancement of Structured Information Standards (OASIS) is a not-for-profit consortium that drives the development, convergence and adoption of open standards for the global information society.” (OASIS) Payload Payload is the data that is being transmitted within a message. Synchronous In the context of STAR Transport, Synchronous means that the specific thread of execution that sent a message waits for an application level reply before continuing on to other processing or finishing execution. Web Services Web Services are a set of standards and protocols for exchanging xml-based data between Web-based applications or systems. Web Service Description Language WSDL The Web Services Description Language (WSDL) is an XML-based language used for describing Web services. ( Wikipedia 2) WS-I “WS-I is an open industry organization chartered to promote Web services interoperability across platforms, operating systems, and programming languages.” (WS-I)