2.8. Deploying Metro endpoint

Before you deploy or publish your endpoint, you will need to package your endpoint application into a WAR file. The requirements when building a WAR:

  • All WSDLs, Schema files should be packaged under WEB-INF/wsdl dir. It is recommended not to package the WSDL if you are doing Java-first development.
  • WebService implementation class should contain @WebService annotation. Provider based endpoints should have @WebServiceProvider annotation.
  • wsdl, service, port attributes are mandatory for Provider based endpoints and can be specified in @WebServiceProvider annotation or deployment descriptor (sun-jaxws.xml).
  • Deployment descriptors, web.xml, web services deployment descriptor (sun-jaxws.xml or 109 or spring)

2.8.1. The WAR Contents

Typically, one creates the WAR file with a GUI development tool or with the ant war task from the generated artifacts from wsimport, wsgen, or apt tools.

For example, a sample WAR file starting from a WSDL file:

Sample WAR contents (WSDL First)

        WEB-INF/classes/hello/HelloIF.class SEI
        WEB-INF/classes/hello/HelloImpl.class Endpoint
        WEB-INF/sun-jaxws.xml JAX-WS RI deployment descriptor
        WEB-INF/web.xml Web deployment descriptor
        WEB-INF/wsdl/HelloService.wsdl WSDL
        WEB-INF/wsdl/schema.xsd WSDL imports this Schema
    

2.8.2. Using sun-jaxws.xml

Metro defines its own deployment descriptor, which is also known as JAX-WS RI deployment descriptor - sun-jaxws.xml.

Here is the schema for sun-jaxws.xml:


            <?xml version="1.0" encoding="UTF-8"?>

            <!--
             DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

             Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

             The contents of this file are subject to the terms of either the GNU
             General Public License Version 2 only ("GPL") or the Common Development
             and Distribution License("CDDL") (collectively, the "License").  You
             may not use this file except in compliance with the License. You can obtain
             a copy of the License at https://glassfish.java.net/public/CDDL+GPL.html
             or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
             language governing permissions and limitations under the License.

             When distributing the software, include this License Header Notice in each
             file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
             Sun designates this particular file as subject to the "Classpath" exception
             as provided by Sun in the GPL Version 2 section of the License file that
             accompanied this code.  If applicable, add the following below the License
             Header, with the fields enclosed by brackets [] replaced by your own
             identifying information: "Portions Copyrighted [year]
             [name of copyright owner]"

             Contributor(s):

             If you wish your version of this file to be governed by only the CDDL or
             only the GPL Version 2, indicate your decision by adding "[Contributor]
             elects to include this software in this distribution under the [CDDL or GPL
             Version 2] license."  If you don't indicate a single choice of license, a
             recipient has the option to distribute your version of this file under
             either the CDDL, the GPL Version 2 or to extend the choice of license to
             its licensees as provided above.  However, if you add GPL Version 2 code
             and therefore, elected the GPL Version 2 license, then the option applies
             only if the new code is made subject to such option by the copyright
             holder.
            -->

            <xsd:schema
              xmlns:xsd="http://www.w3.org/2001/XMLSchema"
              xmlns:tns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
              xmlns:javaee="http://java.sun.com/xml/ns/javaee"
              targetNamespace="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
              elementFormDefault="qualified"
              attributeFormDefault="unqualified"
              version="1.0">

              <xsd:import namespace="http://java.sun.com/xml/ns/javaee" schemaLocation="http://java.sun.com/xml/ns/javaee/javaee_web_services_1_2.xsd" />

              <xsd:element name="endpoints">
                <xsd:complexType>
                  <xsd:sequence>
                    <xsd:element name="endpoint" type="tns:endpointType" minOccurs="0" maxOccurs="unbounded"/>
                  </xsd:sequence>
                  <xsd:attribute name="version" type="xsd:string" use="required"/>
                </xsd:complexType>
              </xsd:element>

              <xsd:complexType name="endpointType">
                <xsd:annotation>
                  <xsd:documentation>
                    An endpoint definition has several attributes:
                       "name" - the endpoint name
                       "implementation" - the name of the endpoint implementation class
                       "wsdl" - the name of a resource corresponding to the WSDL document for the endpoint
                       "service" - the QName of the WSDL service that owns this endpoint;
                       "port" - the QName of the WSDL port for this endpoint;
                       "url-pattern" - the URL pattern this endpoint is mapped to.
                       "binding" - specify binding id for SOAP1.1 or SOAP1.2
                       "enable-mtom" - Enables MTOM optimization
                    "wsdl", "service", "port" attributes are required for provider based endpoints
                  </xsd:documentation>
                </xsd:annotation>

                <xsd:sequence>
                  <xsd:element ref="handler-chains" minOccurs="0"/>
                </xsd:sequence>
                <xsd:attribute name="name" type="xsd:string" use="required"/>
                <xsd:attribute name="implementation" type="xsd:string" use="required"/>
                <xsd:attribute name="wsdl" type="xsd:anyURI"/>
                <xsd:attribute name="service" type="xsd:anyURI"/>
                <xsd:attribute name="port" type="xsd:anyURI"/>
                <xsd:attribute name="url-pattern" type="xsd:anyURI" use="required"/>
                <xsd:attribute name="binding" type="xsd:string"/>
                <xsd:attribute name="enable-mtom" type="xsd:boolean"/>
              </xsd:complexType>

            </xsd:schema>

        

The <endpoints> element contain one or more <endpoint> elements. Each endpoint represents a port in the WSDL and it contains all information about implementation class, servlet url-pattern, binding, WSDL, service, port QNames. The following shows a sun-jaxws.xml file for a simple HelloWorld service. sun-jaxws.xml is the schema instance of sun-jaxws.xml.


    <?xml version="1.0" encoding="UTF-8"?>
    <endpoints
            xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
            version="2.0">
        <endpoint
                name="MyHello"
                implementation="hello.HelloImpl"
                url-pattern="/hello"/>
    </endpoints>
    
  • Endpoint attribute
Attribute Optional Use
name
N Name of the endpoint
wsdl
Y Primary wsdl file location in the WAR file. E.g. WEB-INF/wsdl/HelloService.wsdl. If this isn't specified, JAX-WS will generate and publish a new WSDL. When the service is developed from Java, it is recommended to omit this attribute.
service
Y QName of WSDL service. For e.g. {http://example.org/}HelloService. When the service is developed from java, it is recommended to omit this attribute.
port
Y QName of WSDL port. For e.g. {http://example.org/}HelloPort. When the service is developed from Java, it is recommended to omit this attribute.
implementation
N Endpoint implementation class name. For e.g: hello.HelloImpl. The class should have @WebService annotation. Provider based implementation class should have @WebServiceProvider annotation.
url-pattern
N Should match <url-pattern> in web.xml
binding
Y Binding id defined in the JAX-WS API. The possible values are:
"http://schemas.xmlsoap.org/wsdl/soap/http","http://www.w3.org/2003/05/soap/bindings/HTTP/"
If omitted, it is considered SOAP1.1 binding.
enable-mtom
Y Enables MTOM optimization. true or false. Default is false.
  • Specifying Handler Chains

  •         
            <?xml version="1.0" encoding="UTF-8"?>
            <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
                       version="2.0">
                <endpoint name="MyHello">
                    <handler-chain xmlns="http://java.sun.com/xml/ns/javaee">
                        <handler-chain-name>somename</handler-chain-name>
                        <handler>
                            <handler-name>MyHandler</handler-name>
                            <handler-class>hello.MyHandler</handler-class>
                        </handler>
                    </handler-chain>
                </endpoint>
            </endpoints>
            
        

    2.8.2.1. The web.xml File

    The following shows a web.xml file for a simple HelloWorld service. It shows the listener and servlet classes that need to be used when deploying Metro-based web services.


            <?xml version="1.0" encoding="UTF-8"?>
            <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
            "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

            <web-app>
                <listener>
                    <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
                </listener>
                <servlet>
                    <servlet-name>hello</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>hello</servlet-name>
                    <url-pattern>/hello</url-pattern>
                </servlet-mapping>
                <session-config>
                    <session-timeout>60</session-timeout>
                </session-config>
            </web-app>
            
        

    2.8.3. Using 109 Deployment Descriptor

    TODO

    2.8.4. Using Spring

    See Using Metro With Spring.


    Terms of Use; Privacy Policy; Copyright ©2013-2014 (revision 20140418.2d69abc)
     
     
    Close
    loading
    Please Confirm
    Close