The requested Web Service Implementation Class or the requested Provider Implementation Class is discovered from the Web Service client using the JAX-WS engine on the Web Service. This is called discovery.

In discovery, the processing for mapping the appropriate Web Service Implementation Class is performed from the URL requested in the SOAP request message. This point describes the mapping when the following URL is requested:

http://example.org/fromwsdl/TestJaxWsService

If the context root is assumed to be fromwsdl, /TestJaxWsService after the context root (underlined part) indicates the path information. The Web Service Implementation Class or the requested Provider Implementation Class is mapped on the basis of this path information.

The following figure shows an example of mapping between the path information and the Web Service Implementation Class:

Figure 10-5 Discovery of the Web Service Implementation Class (POJO Web Service)

Figure 10-6 Discovery of the Web Service Implementation Class (EJB Web Service)

Among the deployed Web Service Implementation Classes or Provider Implementation Classes, the JAX-WS engine on the Web Service invokes the class corresponding to the path information. In POJO Web Services, the serviceName attribute of the javax.jws.WebService or the javax.xml.ws.WebServiceProvider annotation invokes the string matching the one with / (forward slash) at the beginning removed from the path information.

In EJB Web Services, the serviceName attribute of the javax.jws.WebService annotation invokes the string matching the one between the / (forward slash) at the beginning and the second / (forward slash) in the path information, and the name attribute value of the javax.jws.WebService annotation invokes the string matching the one after the second / (forward slash) in the path information.

You can omit the serviceName attribute of the javax.jws.WebService annotation and javax.xml.ws.WebServiceProvider annotation. If you omit the serviceName attribute, based on the JSR-181 specifications, a string with Service added as a suffix to the class name (simple name) of the Web Service Implementation Class or the Provider Implementation Class is considered as the value of the serviceName attribute. Also, you can omit the name attribute of the javax.jws.WebService annotation. If you omit the name attribute, based on JSR-181 specifications, the class name (simple name) of the Web Service Implementation Class is considered as the value of the name attribute.

The following is the correspondence between the path information in POJO Web Service example and the invoked Web Service Implementation Class:

• If the path information is Sample1Service
  The Web Service Implementation Class A (org.foo.Test1.java) is invoked.
  
• If the path information is Sample2Service
  The Web Service Implementation Class B (org.foo.Test2.java) is invoked.
  
• If the path information is Test3Service
  The Web Service Implementation Class C (org.foo.Test3.java) is invoked.
  

The following is the correspondence between the path information in the EJB Web Service example and the invoked Web Service Implementation Class:

• If the path information is/Sample1Service/Sample1
  The EJB 1 (org.foo.Test1.java) is invoked.
  
• If the path information is /Sample2Service/Test2
  The EJB 2 (org.foo.Test2.java) is invoked.
  
• If the path information is /Test3Service/Test3
  The EJB 3 (org.foo.Test3.java) is invoked.
  

You can customize this mapping by coding cosminexus-jaxws.xml. The following is the customization of mapping with the coding example of cosminexus-jaxws.xml:

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'>
 <endpoint
 name="test1"
 implementation="org.foo.Test1"
 url-pattern="/test1"
 />
 <endpoint
 name="test2"
 implementation="org.foo.Test2"
 url-pattern="/test2"
 />
 <endpoint
 name="test3"
 implementation="org.foo.Test3"
 url-pattern="/test3"
 />
</endpoints>

The following is the correspondence between the path information in this example and the invoked Web Service Implementation Class:

• If the path information is test1
  The Web Service Implementation Class A (org.foo.Test1.java) is invoked.
  
• If the path information is test2
  The Web Service Implementation Class B(org.foo.Test2.java) is invoked.
  
• If the path information is test3
  The Web Service Implementation Class C(org.foo.Test3.java) is invoked.
  

However, the url-pattern attribute of cosminexus-jaxws.xml and the url-pattern element of web.xml must have one to one correspondence. Therefore, if you customize the mapping in this example, you must also change the coding in web.xml. The following is a coding example of web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
 ...
 <servlet-mapping>
 <servlet-name>CosminexusJaxwsServlet</servlet-name>
 <url-pattern>/test1</url-pattern>
 <url-pattern>/test2</url-pattern>
 <url-pattern>/test3</url-pattern>
 </servlet-mapping>
 ...
</web-app>

For customizing cosminexus-jaxws.xml, see 10.3 Customization using cosminexus-jaxws.xml.

With the JAX-WS engine at the Web Service machine, if the discovered target is a Web Service Implementation Class, a method corresponding to the operation is invoked and executed in accordance with the contents of the received SOAP Message. If the discovered target is a Provider Implementation Class, the unmarshalled SOAP Message is converted to the object specified by the Provider Implementation Class, and the invoke() method is invoked.

This is called dispatch of SOAP Messages.

A SOAP Message must conform to any of the following specifications^# having WS-I Basic Profile 1.1 and Attachments Profile 1.0:

• SOAP 1.1 specifications
• SOAP 1.2 specifications
• SwA specifications (when using an attachment in wsi:swaRef format)
• MTOM/XOP specifications (when using attachments in the MTOM/XOP specification format).

The following is an example of a SOAP Message for the SOAP 1.1 specifications. Note that this is the example of the SOAP Message without attachment. For the SOAP Messages with attachments, see the section 28.4 SOAP Messages with attachments (wsi:swaRef format).

POST http://sample.org/fromjava/AddNumbersImplService HTTP/1.1
SOAPAction: ""
Content-Type: text/xml;charset="utf-8"
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
 
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
 <ns2:add xmlns:ns2="http://sample.com/">
 <arg0>256</arg0>
 <arg1>103</arg1>
 </ns2:add>
 </S:Body>
</S:Envelope>

At the beginning of the message are the HTTP request line (POST line) followed by the HTTP request header fields (SOAPAction, Content-Type, and Accept lines). After this, keep a blank line and then enter the SOAP Message. Based on the contents of this SOAP Message, appropriate SEI is invoked and processed.

In the header field of the HTTP request, a SOAPAction header is required, and the value of the header must be set as a null character (""). Even if a value is set in the SOAPAction header, the value is ignored by the JAX-WS engine. If a value of a SOAPAction header is not enclosed within quotation marks ["], an error message (KDJW3022-W) is displayed. Also, the operations when the SOAPAction header is not included in the HTTP request differ according to the settings in the action definition file. For the settings in the action definition file, see the section 10.1 Action definition file.

The following is an example of a SOAP Message for the SOAP 1.2 specifications. Note that this is the example of the SOAP Message without attachment. For the SOAP Messages with attachments, see the section 28.4 SOAP Messages with attachments (wsi:swaRef format).

POST http://sample.org/fromjava/AddNumbersImplService HTTP/1.1
Content-Type: application/soap+xml;charset="utf-8";action=""
Accept: application/soap+xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
 
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:add xmlns:ns2="http://sample.com/">
      <arg0>256</arg0>
      <arg1>103</arg1>
    </ns2:add>
  </S:Body>
</S:Envelope>

In the case of the SOAP 1.2 specifications, the SOAPAction header is ignored even if the SOAPAction header appears in the header field of the HTTP request. Also, you can omit the action parameter.