As mentioned above, the Web Service Creation Wizard automatically performs a number of tasks, greatly simplifying the creation of Web Services from Nucleus components. The wizard enables you to simply create Web Services and begin using them, without needing to understand all of their underpinnings. However, in some cases you may need to troubleshoot or make changes to your Web Services, so it is helpful to have some familiarity with their form and packaging. This section discusses the various pieces that make up a Web Service, including:

Note that the business logic of the Web Service is actually contained in the method of the Nucleus component that is being exposed. The Web Service handles only the RPC infrastructure, and passes the actual processing to the Nucleus component.

Service Endpoint Interface and Implementation Class

The service endpoint interface (SEI) is a Java interface class that defines the methods to be exposed as a Web Service. This interface must extend the java.rmi.Remote interface and each method must throw java.rmi.RemoteException. The SEI for any Web Service generated by the Oracle ATG Web Commerce platform has a single method, corresponding to the Nucleus method being exposed.

The service implementation class (also referred to as the service bean) implements the service endpoint interface and handles the actual servicing of incoming SOAP requests. In addition, service implementation classes generated by the Oracle ATG Web Commerce platform implement the interface javax.xml.rpc.server.ServiceLifecyle, and extend the atg.webservice.ManagedComponentProperties class, which registers services with the Oracle ATG Web Commerce platform Web Service Registry. The Web Service Registry is discussed in the Managing Web Services section.

The service endpoint interface and implementation class are generated by the /atg/webservice/WebServiceGenerator component. The names for these classes are based on the name of the Nucleus method being exposed. For instance, if the Nucleus method is getOrderStatus, the service endpoint interface is named GetOrderStatusSEI, and the implementation class is named GetOrderStatusSEIImpl.

WSDL Document

Web Services Description Language (WSDL) is an XML language for describing Web Services in a platform-independent way. A WSDL document describes a Web Service’s methods by specifying the locations of the resources they use and defining the methods’ inputs and outputs. (A WSDL document for a Web Service generated by the Oracle ATG Web Commerce platform always describes one method, because each Web Service can expose only one Nucleus method.)

There must be a separate WSDL document for each Web Service. The WSDL document is generated by the /atg/webservice/WSDLGenerator component, which is of class atg.webservice.WSDLGeneratorImpl. This document is used for two key purposes:

When the Web Service’s input and output values are primitive types, they are defined in the primary WSDL document. For example:

<message name="getOrderStatusInput">
 <part name="in0" type="xsd:string">

Each non-primitive input or output requires its own WSDL document that is imported by the primary WSDL document. Import statements similar to the following are included in the primary WSDL document when the Web Service is created using the Dynamo Administration UI:

<import location="atg.commerce.order.status.wsdl"

The location specified is relative to the primary WSDL document. Some Web Service clients are able to interpret relative locations, but others require fully qualified URLs. To work with these clients, when the Oracle ATG Web Commerce platform receives a request for a WSDL document, it uses the servlet class atg.webservice.WSDLFinderServlet and the filter class atg.webservice.WSDLImportFilter to translate the location value into a fully qualified URL:

The WSDLFinderServlet and WSDLImportFilter classes are declared in the web.xml file for the Web application that the Web Service is a part of, as discussed in the next section. For more information about request handling, see the ATG Platform Programming Guide.

web.xml File

The web.xml file is the standard deployment descriptor for the Web application that the Web Service is a part of. It declares the filters and servlets used by the service.

On the Oracle ATG Web Commerce platform, the servlet that listens for the SOAP request is com.sun.xml.rpc.server.http.JAXRPCServlet. This servlet is part of the JAX-RPC reference implementation, and is responsible for receiving the incoming SOAP request and determining how to dispatch the call. For example, if you create a Web Service called getOrderStatus, the entry for it in the web.xml file looks something like this:


When a call to the getOrderStatus Web Service is sent to the Oracle ATG Web Commerce platform, the JAXRPCServlet receives the request and dispatches it based on the information in the file that the configuration.file parameter points to. This configuration file is included in the WAR file, and looks similar to this:


Note that the port0.servant property is set to the name of the service implementation class. This property designates the class that JAXRPCServlet dispatches the SOAP request to.

Handling Imported WSDL Documents in web.xml

As discussed in the WSDL Document section, there are two resources that assist in handling WSDL requests. These resources are declared in the web.xml file:

For example:

 <description>Used to lookup imported wsdl files.</description>
Web Service Registrar in web.xml

To register Web Services with the Web Services Registry, the web.xml file declares the WebServiceRegistrar servlet, and sets it to load on startup:

 <description>ATG WebServiceRegistrar for registering servlet

For more information about the Web Services Registry, see Managing Web Services.

Other Elements of web.xml

The web.xml file may declare certain additional elements:

JAX-RPC Deployment Descriptor and Mapping Files

The JAX-RPC deployment descriptor, webservices.xml, provides metadata (such as names and descriptions of the SEIs, service beans, and WSDL documents) about all of the Web Services in a given Web application.

The mapping file defines the association between a WSDL file and an ISEI and implementation class, by mapping namespaces to Java packages. This mapping is used when serializing and deserializing XML files. There is a separate JAX-RPC mapping file for each Web Service, and the name of each file reflects the method the service is based on. For example, if the method is getOrderStatus, the mapping file for the Web Services is named getOrderStatusMapping.xml.

Runtime Classes

The runtime classes are generated using the Oracle JAX-RPC reference implementation. These classes include:

JSR 109 Compliant EAR File

The JSR 109 Java specification includes information about how a Web Service should be packaged within an EAR file. The wizard combines all the generated files (class files, web.xml, WSDL document, webservices.xml, and JAX-RPC mapping file) into a WAR file, which is then added to a JSR 109 compliant EAR file.

Copyright © 1997, 2013 Oracle and/or its affiliates. All rights reserved. Legal Notices