A.4. Web Services (webservices.xml)SOAP web services are implemented in J2EE using JAX-RPC, and service implementations can take the form of a basic Java bean deployed as a web component or a stateless session EJB component. In either case, a webservices.xml deployment descriptor is used within the component archive (the war file or ejb-jar.xml file) to declare and configure the web services implemented by the components in the archive. Figure A-15 shows the overall XML schema structure used in webservices.xml files. Example A-15 shows sample web service declarations, annotated with descriptive comments. Figure A-15. Web service declarationsExample A-15. Annotated web service declarations<?xml version="1.0" encoding="UTF-8"?> <webservices xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/j2ee_web_services_1_1.xsd" version="1.1"> <description>Web services contained in my application</description> <display-name>Web services</display-name> <icon> <small-icon>icons/my-small-ws-icon.jpg</small-icon> <large-icon>icons/my-large-ws-icon.jpg</large-icon> </icon> <!-- Each webservice-description element defines a full web service implemented somewhere in the surrounding component archive (web or EJB). Each service specifies a WSDL file and a JAX-RPC mapping file contained in the archive and one or more ports that can be invoked by clients. Each port is described here, in terms of the WSDL port element that it implements, the Java entities that implement it, and optional runtime settings. --> <webservice-description> <description>This service...</description> <display-name>A service</display-name> <icon> <small-icon>icons/small-ws1-icon.jpg</small-icon> <large-icon>icons/large-ws1-icon.jpg</large-icon> </icon> <!-- A unique name for this service definition. This name must be unique within the surrounding archive. --> <webservice-description-name >MyWebService</webservice-description-name> <!-- Indicate the location of the WSDL file that describes this service. The location is specified as a relative path from the root of the surrounding archive. In web archives, the WSDL file is typically placed in the WEB-INF directory. In EJB archives, it is placed in the META-INF directory. --> <wsdl-file>WEB-INF/myservice.wsdl</wsdl-file> <!-- Indicate the location of the JAX-RPC mapping file for this service. The location is specified as a relative path from the root of the surrounding archive. This XML file describes how to map between SOAP XML and Java entities. The mapping file is typically placed in the WEB-INF directory in web archives and in the META-INF directory in EJB archives. See Section X for a full reference on JAX-RPC mapping files. --> <jaxrpc-mapping-file >WEB-INF/myservice-mapping.xml</jaxrpc-mapping-file> <!-- Each port on the service is declared with a port-component element. --> <port-component> <description>A port provided by this service...</description> <display-name>Service port X</display-name> <icon> <small-icon>icons/my-small-port-icon.jpg</small-icon> <large-icon>icons/my-large-port-icon.jpg</large-icon> </icon> <!-- A unique name, within the surrounding archive, for this port component. This name can be used in web and EJB descriptors within service-ref entries, as the value of a port-component-link. --> <port-component-name>MyServicePort</port-component-name> <!-- The qualified name (QName) of the port within the service's WSDL description. --> <wsdl-port>MyServicePort</wsdl-port> <!-- The Java interface that is used in the Java binding of the port. --> <service-endpoint-interface>com.my.service.interface </service-endpoint-interface> <!-- Specify the component within this archive or application that implements this port. The service-impl-bean element can either point to the servlet-name of a web component, by using the servlet-link element, or it can point to the ejb-name of an EJB component, by using an ejb-link element. --> <service-impl-bean> <servlet-link>MyServiceWebComponent</servlet-link> </service-impl-bean> <!-- The handler element is used to specify custom SOAP message handlers that should be put in place for this port in the service. Handlers can be triggered for any message targeted at the port, or they can handle specific messages based on their header entries. --> <handler> <!-- A name for the handler. --> <handler-name>MySOAPHandler</handler-name> <!-- The full class name of the handler. The class must implement the javax.xml.rpc.handler.Handler interface. --> <handler-class>com.my.soap.handler</handler-class> <!-- Specify initialization parameters, passed into the handler's init( ) method as part of the HandlerInfo. --> <init-param> <!-- Name of the parameter. --> <param-name>param1</param-name> <!-- Value of the parameter. --> <param-value>value1</param-value> </init-param> <!-- The qualified name (QName) of a SOAP header to be processed by the handler. --> <soap-header>com.partner-header1</soap-header> <!-- A SOAP actor role that the handler should play as it processes the SOAP request. --> <soap-role>urn:my-service</soap-role> </handler> </port-component> </webservice-description> </webservices> |