Version 4

    This document provides some refences and directions on the migration from JBossWS 3.x to 4.x.

     

    References

    JBossWS Documentation - https://docs.jboss.org/author/display/JBWS/JBoss+Web+Services+Documentation

    JBossWS 4.0.x & AS 7.x FAQ - http://community.jboss.org/wiki/JBossWS-AS7FAQ

    Generic JBossWS FAQ - http://community.jboss.org/wiki/JBossWS-FAQ

    Apache CXF 2.4.x Migration guide - http://cxf.apache.org/docs/24-migration-guide.html

     

    Dependencies

    JBossWS 4.0.x main focus is on JBoss AS 7.x and Apache CXF 2.4.x.

     

    Since JBossWS 4.0.x is based on Apache CXF 2.4.x series, you might want to have a look at the Apache CXF 2.4.x series migration guide:

     

    http://cxf.apache.org/docs/24-migration-guide.html

     

    The fundamental change in JBoss AS 7 is its new class loading approach based on JBoss Modules.

    Since AS 7 is it possible to use e.g. multiple versions of Xalan in different deployments.

    Because of this feature, all non standard dependencies have to be specified explicitely

    in user deployments. Please refer to the JBoss-Modules page of the WS documentation and to the JBossWS AS7 FAQ for details.

     

     

    JBossWS API project changes

    JBossWS 4.0.x differs from JBossWS 3.4.x in the following way.

     

    JBossWS SPI and Common components have been refactored to properly isolate user interfaces (JBossWS API), JBoss internal integration interfaces (JBossWS SPI) and common utilities (JBossWS Common). Two additional components are also now part of project, JBossWS Shared Testuite (containing the shared stack independent testsuite) and JBossWS Common Tools (with the jaxws tools related utilities).

    The net result is that final users are to expect API in JBossWS API and can rely on JBossWS Common Tools for the tools.

     

    Here is a list of the package changes that came with the refactoring and that can affect final users:

     

    [JBossWS SPI]    org.jboss.wsf.spi.annotation.*                        -> [JBossWS API] org.jboss.ws.api.annotation.*

    [JBossWS SPI]    org.jboss.wsf.spi.binding.*                             -> [JBossWS API] org.jboss.ws.api.binding.*

    [JBossWS SPI]    org.jboss.wsf.spi.management.recording.*      -> [JBossWS API] org.jboss.ws.api.monitoring.*

    [JBossWS SPI]    org.jboss.wsf.spi.tools.*                                -> [JBossWS API] org.jboss.ws.api.tools.*

    [JBossWS SPI]    org.jboss.wsf.spi.tools.ant.*                           -> [JBossWS Common Tools] org.jboss.ws.tools.ant.*

    [JBossWS SPI]    org.jboss.wsf.spi.tools.cmd.*                         -> [JBossWS Common Tools] org.jboss.ws.tools.cmd.*

    [JBossWS SPI]    org.jboss.wsf.spi.util.ServiceLoader                -> [JBossWS API] org.jboss.ws.api.util.ServiceLoader

    [JBossWS Common] org.jboss.wsf.common.*                           -> [JBossWS Common] org.jboss.ws.common.*

    [JBossWS Common] org.jboss.wsf.common.handler.*                -> [JBossWS API] org.jboss.ws.api.handler.*

    [JBossWS Common] org.jboss.wsf.common.addressing.*           -> [JBossWS API] org.jboss.ws.api.addressing.*

    [JBossWS Common] org.jboss.wsf.common.DOMUtils               -> [JBossWS API] org.jboss.ws.api.util.DOMUtils

    [JBossWS Native] org.jboss.ws.annotation.EndpointConfig          -> [JBossWS API] org.jboss.ws.api.annotation.EndpointConfig

     

     

    @WebContext annotation

    In JBossWS 3.4.x there used to be org.jboss.wsf.spi.annotation.WebContext annotation in JBossWS SPI project.

    Since JBossWS 4.0.x this annotation was moved to org.jboss.ws.api.annotation.WebContext in JBossWS API project.

    Thus user deployments that have been using this feature, need to rename the dependency package in their source

    code and compile it against new JBossWS API jar. There's also one non backward compatible change in that annotation.

    The 'String[] virtualHosts' attribute was changed to 'String virtualHost'. In other words since JBoss AS7 it's

    possible to specify only one virtual host per deployment. If there are multiple webservices using @WebContext

    annotation and specifying virtualHost there, this virtualHost value must be identical for all endpoints

    defined in the deployment archive.

     

    EndpointConfig

    JBossWS 3.x used to have the Endpoint Configuration and Client configuration concepts; those were JBossWS specific configuration sets users could leverage to assign their ws endpoints / clients to a given pre-defined configuration (for instance, a ws-security enabled configuration).

    In JBossWS 4, that concept has been extended to the CXF based stack endpoints, becoming a stack agnostic configuration mechanism:

    • the JBoss AS 7 domain model includes pre-defined endpoint configurations (endpoint-config) in the webservices subsystem section
    • users can add their own endpoint-config to the model and have it managed together with the rest of the AS7 model
    • the schema for the endpoint-config is contained in jbossws-jaxws-config_4_0.xsd and is a jaxws server side only minor extension of the former Native endpoint configuration
    • the @org.jboss.ws.api.annotation.EndpointConfig annotation is provided to reference a given endpoint configuration in user ws endpoints
    • endpoint configurations can still be specified through xml files bundled into user deployments, instead of referring to a AS7 domain provided configuration

    WS-Security support without Spring

    An example of @EndpointConfig usage is the suggested way of using WS-Security with JBossWS-CXF 4. In order for removing the need of using Spring just to set few properties required for configuring WS-SecurityPolicy enabled clients/endpoints, custom endpoint-config can be specified for user endpoints. Please refer to the WS-Security section of the documentation for further details.

     

    jboss-webservices.xml descriptor

    There was introduced new descriptor in JBossWS 4.0.x series.

    Its name is jboss-webservices.xml and it's a partial replacement

    for obsolete jboss.xml.

     

    The expected location of this descriptor is:

    * META-INF/jboss-webservices.xml for EJB webservice deployments

    * WEB-INF/jboss-webservices.xml for POJO webservice deployments EJB webservice endpoints bundled in .war

     

    The structure of that file is the following:

     

    <webservices>
      <context-root/>?
      <config-name/>?
      <config-file/>?
      <port-component>*
        <ejb-name/>
        <port-component-name/>
        <port-component-uri/>?
        <auth-method/>?
        <transport-guarantee/>?
        <secure-wsdl-access/>?
      </port-component>
      <webservice-description>*
        <webservice-description-name/>
        <wsdl-publish-location/>?
      </webservice-description>
    </webservices>
    

     

    <context-root> element

    Element <context-root> can be used to customize context root of webservices deployment.

    It is a replacement for jboss.xml webservices/context-root element. For example:

     

    In JBossAS 6.x series users used to provide jboss.xml with the following content:

     

    <jboss>
      <webservices>
        <context-root>foo</context-root>
      </webservices>
    </jboss>
    

     

    Since JBossAS 7.x users have to provide jboss-webservices.xml file instead with the following content:

     

    <webservices>
      <context-root>foo</context-root>
    </webservices>
    

     

    <config-name> and <config-file> elements

    Elements <config-name> and <config-file> can be used to associate legacy JBossWS Native configurations with user deployment.

     

    In JBossAS 6.x series users used to provide jboss.xml with the following content:

     

    <jboss>
      <webservices>
        <webservice-description>
          <webservice-description-name>TestService</webservice-description-name>
          <config-name>Standard WSSecurity Endpoint</config-name>
          <config-file>META-INF/custom.xml</config-file>
        </webservice-description>
      </webservices>
    </jboss>
    

     

    Since JBossAS 7.x users have to provide jboss-webservices.xml file instead with the following content:

     

    <webservices>
      <config-name>Standard WSSecurity Endpoint</config-name>
      <config-file>META-INF/custom.xml</config-file>
    </webservices>
    

     

    <port-component> element

    Element <port-component> can be used to customize EJB endpoint target URI or to configure security related properties.

     

    In JBossAS 6.x series users used to provide jboss.xml with the following content:

     

    <jboss>
      <enterprise-beans>
        <session>
          <ejb-name>TestService</ejb-name>
          <port-component>
            <port-component-name>TestServicePort</port-component-name>
            <port-component-uri>/*</port-component-uri>
            <auth-method>BASIC</auth-method>
            <transport-guarantee>NONE</transport-guarantee>
            <secure-wsdl-access>true</secure-wsdl-access>
          </port-component>
        </session>
      </enterprise-beans>
    </jboss>
    

     

    Since JBossAS 7.x users have to provide jboss-webservices.xml file instead with the following content:

     

    <webservices>
      <port-component>
        <ejb-name>TestService</ejb-name>
        <port-component-name>TestServicePort</port-component-name>
        <port-component-uri>/*</port-component-uri>
        <auth-method>BASIC</auth-method>
        <transport-guarantee>NONE</transport-guarantee>
        <secure-wsdl-access>true</secure-wsdl-access>
      </port-component>
    </webservices>
    

     

    <webservice-description> element

    Element <webservice-description> can be used to customize (override) webservice WSDL publish location.

     

    In JBossAS 6.x series users used to provide jboss.xml with the following content:

     

    <jboss>
      <webservices>
        <webservice-description>
          <webservice-description-name>TestService</webservice-description-name>
          <wsdl-publish-location>file:///bar/foo.wsdl</wsdl-publish-location>
        </webservice-description>
      </webservices>
    </jboss>
    

     

    Since JBossAS 7.x users have to provide jboss-webservices.xml file instead with the following content:

     

    <webservices>
      <webservice-description>
        <webservice-description-name>TestService</webservice-description-name>
        <wsdl-publish-location>file:///bar/foo.wsdl</wsdl-publish-location>
      </webservice-description>
    </webservices>