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:
Service endpoint interface and implementation class
WSDL document
web.xmlfileJAX-RPC deployment descriptor (
webservices.xml) and mapping fileRuntime classes
JSR 109 compliant EAR file
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">
</message>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"
namespace="http://www.atg.com/atg.commerce.order.status"/>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:
At runtime,
JAXRPCServletupdates the SOAP address in the WSDL document to include the domain host name and port number.When
WSDLFinderServletdetects a WSDL request,WSDLImportFilterappends the domain name and port number (from the SOAP address provided byJAXRPCServlet) and the context path (by callingrequest.getContextPath()on the Dynamo request) to thelocationvalue in theimportstatement. The resultingimportstatement looks similar to this:<import location=
"http://myhost:7881/catalog/atg.commerce.order.status.wsdl"
namespace="http://www.atg.com/atg.commerce.order.status"/>
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:
<servlet> <servlet-name>getOrderStatus</servlet-name> <display-name>getOrderStatus</display-name> <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class> <init-param> <param-name>configuration.file</param-name> <param-value>WEB-INF/wsconfig/getOrderStatus_Config.properties</param-value> </init-param> </servlet> ... <servlet-mapping> <servlet-name>getOrderStatus</servlet-name> <url-pattern>/getOrderStatus/*</url-pattern> </servlet-mapping>
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:
port0.wsdl.serviceName=GetOrderStatusSEIService port0.tie=webservices.GetOrderStatusSEI_Tie wsdl.transform=true port0.name=getOrderStatus portcount=1 wsdl.location=WEB-INF/getOrderStatus.wsdl port0.servant=webservices.GetOrderStatusSEIImpl port0.wsdl.targetNamespace=http\://www.atg.com/webservices port0.wsdl.portName=GetOrderStatusSEIPort
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:
WSDLImportFilter, which is a filter of classatg.webservice.WSDLImportFilter, is mapped to a parent directory that has subdirectories holding WSDL documentsWSDLFinder, which is a servlet of classatg.webservice.WSDLFinderServlet, should be defined and mapped to each path that will lead to a WSDL document
For example:
<filter> <filter-name>WSDLImportFilter</filter-name> <filter-class>atg.webservice.WSDLImportFilter</filter-class> </filter> ... <filter-mapping> <filter-name>WSDLImportFilter</filter-name> <url-pattern>/getOrderStatus/*</url-pattern> </filter-mapping> ... <servlet> <servlet-name>WSDLFinder</servlet-name> <display-name>WSDLFinder</display-name> <description>Used to lookup imported wsdl files.</description> <servlet-class>atg.webservice.WSDLFinderServlet</servlet-class> </servlet> ... <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.order.status.wsdl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.security.wsdl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.wsdl</url-pattern> </servlet-mapping>
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:
<servlet> <servlet-name>WebServiceRegistrar</servlet-name> <display-name>WebServiceRegistrar</display-name> <description>ATG WebServiceRegistrar for registering servlet web-services.</description> <servlet-class>atg.webservice.WebServiceRegistrar</servlet-class> <load-on-startup>1</load-on-startup> </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:
The servlet
atg.nucleus.servlet.NucleusServlet, which runs Nucleus as a servlet within a Web applicationThe filter
atg.filter.dspjsp.PageFilter, which invokes the DAF request-handling pipelineThe context parameter
atg.session.parentContextName; its value is set to/dyn, which enables the Web Services to share information with theatg_bootstrap.warapplication
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:
The tie class that
JAXRPCServletinvokes the method on, and which in turn invokes the method on the service implementation classClasses for handling serializing and deserializing SOAP requests and responses
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.
