The Web Service and Web Service Client Creation Framework
JST Web Services Design Documents
Credits
 
Enhancements 108595
105325
105336
Version 1.0 Draft
Last Updated 2005.10.04
Target Release WTP 1.0
Target Milestone M9
Contributors Gilbert Andrews
Chris Brealey
Kathy Chan
Joan Haggarty
Rupam Kuehner
Peter Moogk
Seng Phung-Lu
Index
 
  1. Overview
  2. Requirements
    1. R1 - End to End Web Service and Web Service Client Creation
    2. R2 - Web Service Discovery Extensibility
    3. R3 - Web Service Runtime Extensibility
    4. R4 - Web Service and Web Service Client Implementation Extensibility
    5. R5 - Web Service Test Extensibility
    6. R6 - Web Service Publication extensibility
  3. Conceptual Design
  4. Detailed Design
1.0 - Overview
 

The Web service tools in the Web Tools Platform Project (WTP) provide extensible means for end users to create Web services and Web service clients. The goal of this document is to present a high level design of this extensible Web service and Web service client creation framework (called framework from here on) that is consistent with the proposed ProjectFacets framework, the J2EE API, the Sever Tools API, and is as much as possible not affected by the parallel effort to merge the Web Services and J2EE command / operation frameworks.

2.0 - Requirements
R1 - End to End Web Service and Web Service Client Creation
 

End users of WTP can discover Web services and develop, assemble, deploy, install, run, test, and announce Web services and Web service clients. End users can optionally bypass the latter five phases of deploy, install, run, test, and announce.

R2 - Web Service Discovery Extensibility
 

Extenders of WTP can contribute graphical user interface facilities to discover Web services. The framework will respect the end user's preferred discovery facility.

R3 - Web Service Runtime Extensibility
 

Extenders of WTP can contribute Web service runtimes (e.g. Apache Axis 1.2) to the framework, and in doing so provide all the tasks needed to develop, assemble, deploy, install, run, and announce Web services and Web service clients. The extender can specify the scenarios (e.g. bottom-up, top-down) and implementation types (e.g. Java bean, EJB) supported by the Web service runtime, along with the project facets (e.g. web, ejb) required on projects that will contain Web services or Web service clients created by this Web service runtime. Container specific project facets can be used by extenders to target a Web service runtime to a particular container.

R4 - Web Service and Web Service Client Implementation Extensibility
 

Extenders of WTP can contribute Web service and Web service client implementation types to the framework along with graphical user interface widgets to aid the user in locating artifacts of that implementation type

R5 - Web Service Test Extensibility
 

Extenders of WTP can contribute Web service and Web service client test facilities.

R6 - Web Service Publication Extensibility
 

Extenders of WTP can contribute Web service publication facilities.

3.0 - Conceptual Design
 

The Web service and Web service client creation framework divides the process of creating Web services and Web service clients into nine phases: discover a Web service (if needed), develop, assemble, deploy, install, run, test, publish, and announce. The activities performed in each of these phases can be further divided into those that are common to all Web service runtimes (common activities) and those that are specific to each Web service runtime (specific activities). The framework performs the common activities and delegates to the Web service runtime extension to perform the specific activities. Outlined below is a brief description of each of the nine phases and examples of common and specific activities.

  • Discover:
    In top-down Web service creation or Web service client creation, locate a Web service described via a WSDL service element. The framework provides a GUI mechanism to to enter a URL or browse for WSDL files in the workspace. Extenders can contribute more sophisticated discovery facilities. Bottom-up Web service creation does not require discovery of Web services but rather, selection of the implementation artifact, such as a Java bean or stateless session EJB. Extenders can contribute the kinds of available artifacts as well the GUI widgets needed to locate them.


  • Develop:
    Develop the WSDL definition and implementation of the Web service. Common activities include the creation of modules which will contain the generated code. Web service runtime extensions should provide the develop tasks specific to the extension.


  • Assemble:
    Depending on the target server, assembly may or may not be required. If required, assemble and configure modules into a module, such as an EAR, that is compatible with the target server type. Common activities include the association of modules to EARs. Extenders should perform tasks specific to the Web service runtime, such as any additional modules that need to the created and configured and any module dependencies that need to be established.


  • Deploy:
    Generate the deploy artifacts. Framework delegates entirely to the Web service runtime extension.


  • Install:
    Install and configure the module on the target server. Installing the module on the server is a common activity. Web service runtime specific install tasks might include modifying the server configuration.


  • Run:
    Start the Web service or Web service client by starting the server, which is a common activity. Any additional tasks extenders would like to perform on the started server can be done here.


  • Test:
    Test the Web service or Web service client. The framework allows the user to choose from an extensible list of test facilities. Existing examples are the Web services explorer and the Generated JSPs. Future examples include Junit tests.


  • Publish:
    Publish the Web service. Framework allows the user to choose from an extensible list of publication facilities (e.g. Web services explorer).




3.1 WebServiceRuntime Extension Point

A Web service runtime can be loosely defined as an engine which manages Web services and Web service clients and also prescribes the manner in which they are to be created (from the develop phase to the run phase). Web service runtime characteristics can vary widely in terms of their supported specification levels (e.g. Servlet, J2EE), Web servers (e.g. Tomcat, JBoss), implementations (e.g. Java bean, EJB) and scenarios (e.g. bottom-up, top-down, client). An extender of WTP can contribute new Web service implementations and runtimes to the framework with the following XML (Please note: Element and attribute names are not final. They are for descriptive purposes only.)

  • org.eclipse.wst.ws.serviceImplementationTypes - extend to contribute implementation types of Web services.

    Extension XML for the Java Bean implementation type:

    <extension point="org.eclipse.wst.ws.serviceImplementationTypes">
      <serviceImplementationType
        id="org.eclipse.jst.ws.wsImpl.java"
        bottomUpLabel="%WEBSERVICETYPE_NAME_JAVA_BU"
        bottomUpIcon="./icons/BottomUpJavaBean.gif"
        bottomUpDescription="%WEBSERVICE_DESC_JAVA_BU"
        topDownLabel="%WEBSERVICETYPE_NAME_JAVA_TD"
        topDownIcon="./icons/TopDownJavaBean.gif"
        topDownDescription="WEBSERVICE_DESC_JAVA_TD">
        <filter
          objectClass="org.eclipse.core.resources.IFile"
          nameFilter="*.java *.class">
        </filter>
        <filter
          objectClass="org.eclipse.jdt.core.IJavaElement">
        </filter>   
      </serviceImplementationType>
    </extension>
    
    • id: a unique identifier used to reference this Web service implementation type
    • bottomUpLabel: a translatable label which will be displayed to the user
    • bottomUpIcon: a relative path of an icon that can be displayed with the bottomUpLabel
    • bottomUpDescription: a short translatable description
    • topDownLabel: a translatable label which will be displayed to the user
    • topDownIcon: a relative path of an icon that can be displayed with the topDownLabel
    • topDownDescription: a short translatable description
    • filter: optional sub-element(s) that can be used by the framework to evaluate whether an Object represents an artifact of this implementation type. This can be used by the framework to intelligently default the implementation type based on the end user's initial selection.
      • objectClass: the fully qualified name of the class or interface that Objects representing artifacts of this type may subclass or implement
      • nameFilter: an optional wild card filter for the name that can be used as a further constraint. The framework will respect this if objectClass implements or extends org.eclipse.core.resources.IResource.

  • org.eclipse.wst.ws.clientImplementationTypes - extend to contribute implementation types of Web service clients.

    Extension XML for the Java Bean Proxy type:

    <extension point="org.eclipse.wst.ws.clientImplementationTypes">
      <clientImplementationType
        id="org.eclipse.jst.ws.client.type.java"
        label="%WEBSERVICECLIENTTYPE_JAVA"
        icon="./icons/JavaClient.gif"
        description="%WEBSERVICECLIENTTYPE_JAVA_DESC"
      />
    </extension>
    
    • id: unique identifier used to reference this Web service client implementation type
    • label: a translatable label which will be displayed to the user
    • icon: a relative path of an icon that can be displayed with the label
    • description: a short translatable description

  • org.eclipse.wst.ws.runtime - extend to contribute a Web service runtime

    Extension XML for the Axis Category and Axis 1.2 Web service runtime:

    <extension point="org.eclipse.wst.ws.runtimes">
      <category
        id="org.eclipse.jst.ws.axis.category"
        label="%WEBSERVICERUNTIME_AXIS"
      />
    </extension>
    
    <extension point="org.eclipse.wst.ws.runtimes">
      <runtime
        id="org.eclipse.jst.ws.axis.axis12"
        label="%WEBSERVICERUNTIME_AXIS12"
        icon="./icons/axis12.gif"
        description="%WEBSERVICERUNTIME_AXIS12_DESC"
        category="org.eclipse.jst.ws.axis.category"
      />
    </extension>
    
    • category
      • id: a unique identifier used to reference this category
      • label: a translatable label which will be displayed to the user
      • parentCategory: a slash delimited path ("/") of category ids to another category if this category should be added as a child.
    • runtime
      • id: a unique identifier used to reference this Web service runtime
      • label: a translatable label which will be displayed to the user
      • icon: a relative path of an icon that can be displayed with the label
      • description: a short translatable description
      • category: a slash delimited path ("/") of category ids. Each token in the path must represent a valid category id.

  • org.eclipse.wst.ws.serviceRuntime Extend to declare support for a combination of Web service implementation type, runtime, and project facets.

    Extension XML to declare that the Axis 1.2 Web service runtime supports creation of a Java bean Web service bottom-up and top-down:

    <extension point="org.eclipse.wst.ws.serviceRuntimes">
      <serviceRuntime
        id="org.eclipse.jst.ws.java.axis12"
        serviceImplementationTypeId="org.eclipse.jst.ws.wsImpl.java"
        runtimeId="org.eclipse.jst.ws.axis.axis12"
        bottomUp="true"
        topDown="true"
        class="org.eclipse.jst.axis.axis12.Axis12WebServiceRuntime">
        
        <required-facet-version facet="org.eclipse.jst.ws.axis.web.facet" version="1.2"/>
    
      </serviceRuntime>
    </extension>
    
    <extension point="org.eclipse.wst.common.project.facet.core.facets">
      <project-facet id="org.eclipse.jst.ws.axis.web.facet">
        <label>%LABEL_AXIS_WEB_FACET</label>
        <description>%DESC_AXIS_WEB_FACET</description>
        <icon>icons/axis-web.gif</icon>
      </project-facet>
      <project-facet-version facet="org.eclipse.jst.ws.axis.web.facet" version="1.2">
        <delegate type="install" class="org.eclipse.jst.ws.axis.AxisWebInstallDelegate"/>
        <constraint>
          <requires facet="java" version="1.3" allow-newer="true"/>    
          <requires facet="web" version="2.3" allow-newer="true"/>    
        </constraint>
      </project-facet-version>
    </extension>
    
    • id: a unique identifier used to reference this serviceRuntime
    • serviceImplementationTypeId: id of the Web service implementation type
    • runtimeId: id of the Web service runtime
    • bottomUp: a flag that indicates if this serviceRuntime supports bottom-up web service creation. False if omitted.
    • topDown: a flag that indicates if this serviceRuntime supports top-down web service creation. False if omitted.
    • class: fully qualifed name of a class which extends AbstractWebServiceRuntime
    • required-facet-version (0 or more): a facet that this serviceRuntime requires on any module into which it will create a Web service. The framework will add the facet or update the version of the existing facet if needed.
      • facet: the id of the required projectFacet
      • version: the version of the required projectFacet
      • allow-newer: true if a later version of the projectFacet is acceptable. (optional - defaults to false)

    Based on the Web service implementation type, Web service runtime, and module/module type selected by the user, the framework will activate the corresponding serviceRuntime extension by constructing the provided class. It will obtain an IWebService from this class, on which it can call the various Web service life-cycle methods (e.g. develop, assemble, deploy, etc.) to get the set of operations that need to be run for each of the phases. Web service specific data can be flow between framework and the extender's operations via the WebServiceDescriptor. Other data can flow from the framework to the extender via a data model that the framework will set on the extender's operations prior to executing them. This includes data such as:
    • Context:
      • Which phases of Web service creation the user has opted to complete (e.g. develop, assemble, deploy, etc.)
      • The selected scenario (e.g. bottomUp or topDown)
      • Resource context information (e.g. overwite files, create folders, etc)
    • Initial selection, if available
    • An EAR selection, if available
    The relationships are illustrated in a diagram at the end of this section.


  • org.eclipse.wst.ws.clientRuntime Extend to declare support for a combination of Web service client implementation type, runtime, and grouping of projectFacets.

    Extension XML to declare that the Axis 1.2 Web service runtime supports creation of a Java Web service client:

    <extension point="org.eclipse.wst.ws.clientRuntimes">
      <clientRuntime
        id="org.eclipse.jst.ws.client.type.java.axis12"
        clientImplementationTypeId="org.eclipse.jst.ws.client.type.java"
        runtimeId="org.eclipse.jst.ws.axis.axis12"
        class="org.eclipse.jst.axis.axis12.Axis12WebServiceClientRuntime">
    
        <required-facet-version facet="org.eclipse.jst.ws.axis.facet" version="1.2"/>
    
      </clientRuntime>
    </extension>
    
    <extension point="org.eclipse.wst.common.project.facet.core.facets">
      <project-facet id="org.eclipse.jst.ws.axis.facet">
        <label>%LABEL_AXIS_FACET</label>
        <description>%DESC_AXIS_FACET</description>
        <icon>icons/axis.gif</icon>
      </project-facet>
      <project-facet-version facet="org.eclipse.jst.ws.axis.facet" version="1.2">
        <delegate type="install" class="org.eclipse.jst.ws.axis.AxisInstallDelegate"/>
        <constraint>
          <requires facet="java" version="1.3" allow-newer="true"/>    
        </constraint>
      </project-facet-version>
    </extension>
    
    • id: a unique identifier used to reference this clientRuntime
    • clientImplementationTypeId: id of the Web service client implementation type
    • runtimeId: id of the Web service runtime
    • class: fully qualifed name of a class which extends AbstractWebServiceClientRuntime
    • required-facet-version (0 or more): a facet that this clientRuntime requires on any module into which it will create a Web service client. The framework will add the facet or update the version of the existing facet if needed.
      • facet: the id of the required facet
      • version: the version of the required facet
      • allow-newer: true if a later version of the projectFacet is acceptable. (optional - defaults to false)

    Based on the Web service client implementation type, Web service runtime, and module/moduleType selected by the user, the framework will activate the corresponding clientRuntime extension by constructing the provided class. It will obtain an IWebServiceClient from this class, on which it can call the various Web service client life-cycle methods. The class hierarchy, relationships, and data flow parallel what is described for IWebSerivceRuntime/IWebService.







3.2 Object Selection Extension Point for Bottom-Up Web Service Creation

In bottom-up Web service creation, once the user has chosen the implementation type, the framework requires them to select a suitable artifact to begin creation of the Web service. Extenders can contribute new Web service implementation types through the org.eclipse.wst.ws.serviceImplementationTypes extension point. The org.eclipse.wst.ws.ui.objectSelectionWidgets extension point allows the contribution of GUI mechanisms to locate artifacts of a particular Web service implementation type.

Extension XML for Java Bean Selection:

<extension point="org.eclipse.wst.ws.ui.objectSelectionWidgets">
  <objectSelectionWidget
    id="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.JavaBeanSelectionWidget"
    serviceImplementationTypeId="org.eclipse.jst.ws.wsImpl.java"
    class="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.JavaBeanSelectionWidget"
    transformer="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.JavaBeanSelectionTransformer"
  />
</extension>

  • id: a unique identifier used to reference this selection widget
  • serviceImplementationTypeId: id of the Web service implementation type this selection widget facilitates the selection of
  • class: the fully qualified name of a class which extends AbstractObjectSelectionWidget (see class diagram below for deatils)
  • transformer: the fully qualified name of a class which implements Transformer. Extenders can use this to transform the user's selection into an IStructuredSelection containing a String representation of the selection. The framework sets the implURL on WebServiceDescriptor to the value of this String.






3.3 Discovery Extension Point for Top-Down Web Service and Web Service Client Creation

In top-down Web service creation or Web service client creation, the framework requires the user to discover and select a Web serivce described via a WSDL service element. Extenders can contribute new Web service discovery facilities through the org.eclipse.wst.ws.ui.discoveryWidgets extension point. The framework will display the user's preferred discovery facility.

Extension XML for the WSDLSelectionWidget discovery facility:

<extension point="org.eclipse.wst.ws.ui.discoveryWidgets">
  <discoveryWidget
    id="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.WSDLSelectionWidget"
    label="%LABEL_WSDL_SELECTION_WIDGET"
    icon="./icons/WsdlSelectionWidget.gif"
    description="%DESC_WSDL_SELECTION_WIDGET"
    class="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.WSDLSelectionWidget"
    transformer="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.WSDLSelectionTransformer"
  />
</extension>

  • id: a unique identifier used to reference this selection widget
  • label: a translatable label which will be displayed to the user
  • class: the fully qualified name of a class which extends AbstractObjectSelectionWidget (see class diagram below for deatils)
  • transformer: the fully qualified name of a class which implements Transformer. Extenders can use this to transform the user's selection into an IStructuredSelection containing a String representation of the selection. The framework sets the implURL on WebServiceInfo to the value of this String.



3.4 Test Extension point

See the Web service test framework design document.

3.5 Publish Extension point

See the Web service publication framework design document.

4.0 - Detailed Design