Contributing Web Service Runtime in WTP

 

Introduction:

 

The Web services tools in WTP provide a set of wizards for creating and consuming Web services.  The Web service runtime currently supported in WTP 1.5.2 is Axis 1.3.  New Web services runtimes can be added to the existing Web services wizards by extending the Web service creation framework.  This document describes what needs to be done to contribute Web service runtimes in WTP.  Refer to Contributing Web services runtime with UI for details on how to contribute UI pages for the Web service runtime.

 

Refer to the original Web service and Web service client creation framework (from here on called the framework) design document for some insight into the original design of the framework.  Please note that the design, as documented in the above design document, was not fully implemented in WTP 1.5.2.  Described below are the extension points and APIs for the framework that was implemented in WTP 1.5.2.  These APIs and extension points are currently internal APIs and are subjected to change.    Our intention is to make part, or all, of these into public APIs as the framework mature and more and more adopters use them.   

 

Repository info:

 

The Web service creation framework is in the Eclipse Web Tools project, you can have access to view the source using the following connection information:

Host: dev.eclipse.org

Repository path: /cvsroot/webtools

User id: anonymous (no password required)

The Web services plugins are under HEAD/jst/components/ws/plugins and HEAD/wst/components/ws/plugins

 

Overview:

 

The Web service and Web service client creation framework (from here on called the framework) divides the process of creating Web services and Web service clients into distinct phases of Web services lifecycle.  Extenders of WTP can contribute Web service runtimes to the framework, and in doing so, provide all the tasks needed to develop, assemble, deploy, install and run 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.

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 and publish. 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 phases and examples of common and specific activities.

 

Details:

 

An extender contributing a Web service runtime can contribute the following:

 

 

 

Based on the Web service implementation types, Web service runtime, and module/module type selected by the user (as indicated by the facets in the module/module type), the framework will activate the corresponding service runtime 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 WebServiceInfo object. Other data can flow from the framework to the extender via parameters that the framework will set on the extender's lifecycle operations prior to executing them. This includes data such as:

·         Environment

The environment to execute commands.

·         Context:

·         Initial selection, if available

·         Project

·         An EAR selection, if available

Extension points:

 

Here are some detail description of the Web services extension points using the Apache Axis 1.3 Web services runtime as an example:

        org.eclipse.jst.ws.consumption.ui.wsImpl

Example: This extension is for the Java bean Web service implementation type.

 

<extension point="org.eclipse.jst.ws.consumption.ui.wsImpl">

    <webServiceImpl

            id="org.eclipse.jst.ws.wsImpl.java"

            label="%WEBSERVICETYPE_NAME_JAVA"

            resourceTypeMetadata="File IResource CompilationUnit"

            extensionMetadata=".java .class"

          objectSelectionWidget="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.JavaBeanSelectionWidget">

    </webServiceImpl>

   </extension>   

 

        org.eclipse.jst.ws.consumption.ui.wsClientImpl

The WTP Web services platform defines the Java proxy client implementation type as shown in the example below. Extenders must not redefine this in their plugins.

Example: This is extension is for the Java proxy client implementation type.


<extension point="org.eclipse.jst.ws.consumption.ui.wsClientImpl">

<webServiceClientImpl

id="org.eclipse.jst.ws.client.type.java"

label="Java Proxy">

</webServiceClientImpl>

</extension>

 

        org.eclipse.jst.ws.consumption.ui.runtimes

This includes a label, id, and an optional serverRequired attribute (which is defaulted to true).

Example: This extension is for the Apache Axis Web service runtime (from the org.eclipse.jst.ws.axis.creation.ui plugin).

<extension point="org.eclipse.jst.ws.consumption.ui.runtimes">

<runtime

id="org.eclipse.jst.ws.axis.creation.axisWebServiceRT"

label="%LABEL_RUNTIME_AXIS_11"

serverRequired="false"/>

</extension>

 

 

        org.eclipse.jst.ws.consumption.ui.serviceRuntimes


Example: This extension is for Java bean Web service support on the Apache Axis Web service runtime (from the org.eclipse.jst.ws.axis.creation.ui plugin. Explanatory comments are in <!-- pink -->.)

<extension point="org.eclipse.jst.ws.consumption.ui.serviceRuntimes">

  <serviceRuntime

 

        <!-- id should be set to a unique id -->

        id="org.eclipse.jst.ws.axis.creation.java"

 

<!-- serviceImplementationTypeId points to the id of a org.eclipse.jst.ws.consumption.ui.wsImpl extension - see above -->

        serviceImplementationTypeId="org.eclipse.jst.ws.wsImpl.java"

 

<!-- runtimeId points to the id of a org.eclipse.jst.ws.consumption.ui.runtimes extension - see above -->

        runtimeId="org.eclipse.jst.ws.axis.creation.axisWebServiceRT"

 

 <!-- bottomUp can be set to "true" or "false" and declares support for creating the Web service beginning with the

implementation artifact(Java bean in this case). It is set to false if absent. -->

        bottomUp="true"

 

<!-- topDown can be set to "true" or "false" and declares support for creating the Web service beginning with the WSDL.

        It is set to false if absent -->

        topDown="true"

       

<!-- The class attribute must be the fully qualified name of a class that extends org.eclipse.wst.ws.internal.wsrt.AbstractWebServiceRuntime. The Web service wizard calls getWebService(..) on this class to get a concrete org.eclipse.wst.ws.internal.wsrt.IWebService. It then calls the various life-cycle methods (develop, assemble, deploy, install, and run) on the IWebService to get the commands that need to get run. See AxisWebServiceRuntime for an example. Wizard pages are not contributed through this, only commands. To contribute wizard pages, you need to provide an extension to the org.eclipse.wst.command.env.ui.widgetRegistry extension point, which lets you insert pages before specific commands. See below for an example.

        -->       

        class="org.eclipse.jst.ws.internal.axis.creation.ui.wsrt.AxisWebServiceRuntime">

 

<!-- The supported project types and servers are now inferred from the required-facet-version element(s). In this example, there is only one required-facet-version. Extenders can have multiple required-facet-version elements. When this is the case, and 'AND' relationship is assumed by the framework -->

        <required-facet-version facet="jst.web" version="2.3" allow-newer="true"/>

 

      </serviceRuntime>

    </extension>  

 

 

        org.eclipse.jst.ws.consumption.ui.clientRuntimes


Examples: These extensions are for Java proxy Web service client support on the Apache Axis Web service runtime (from the org.eclipse.jst.ws.axis.creation.ui plugin). Since Axis clients can be generated into simple Java projects as well as into Web projects, there are two extensions, each specifying a different required-facet-version. Explanatory comments are in <!-- pink -->.

 <!-- define support for Axis Java clients in Java projects -->

    <extension point="org.eclipse.jst.ws.consumption.ui.clientRuntimes">

      <clientRuntime

 

        <!-- id should be set to a unique id -->

        id="org.eclipse.jst.ws.axis.consumption.java"

 

<!-- clientImplementationTypeId points to the id of a org.eclipse.jst.ws.consumption.ui.wsClientImpl extension

         - see above -->

        clientImplementationTypeId="org.eclipse.jst.ws.client.type.java"

 

<!-- runtimeId points to the id of a org.eclipse.jst.ws.consumption.ui.runtimes extension - see above -->

        runtimeId="org.eclipse.jst.ws.axis.creation.axisWebServiceRT"

 

<!-- The class attribute must be the fully qualified name of a class that extends org.eclipse.wst.ws.internal.wsrt.AbstractWebServiceRuntime. The Web service wizard calls getWebServiceClient(..) on this class to get a concrete org.eclipse.wst.ws.internal.wsrt.IWebServiceClient. It then calls the various life-cycle methods (develop, assemble, deploy, install, and run) on the IWebServiceClient to get the commands that need to get run. See

AxisWebServiceRuntime for an example.  Wizard pages are not contributed through this, only commands. To contribute wizard pages, you need to provide an extension to the org.eclipse.wst.command.env.ui.widgetRegistry extension point, which lets you insert pages before specific commands. See below for an example.

 

        -->        

        class="org.eclipse.jst.ws.internal.axis.creation.ui.wsrt.AxisWebServiceRuntime">

 

<!-- The supported project types and servers are now inferred from these required facets. In this example, there is only one required-facet-version. Extenders can have multiple required-facet-version elements. When this

        is the case, and 'AND' relationship is assumed by the framework -->

        <required-facet-version facet="jst.utility" version="1.0" allow-newer="true"/>

 

      </clientRuntime>

    </extension>   

   

    <!-- define support for Axis Java clients in Web projects -->

    <extension point="org.eclipse.jst.ws.consumption.ui.clientRuntimes">

      <clientRuntime

        id="org.eclipse.jst.ws.axis.consumption.web"

        clientImplementationTypeId="org.eclipse.jst.ws.client.type.java"

        runtimeId="org.eclipse.jst.ws.axis.creation.axisWebServiceRT"

        class="org.eclipse.jst.ws.internal.axis.creation.ui.wsrt.AxisWebServiceRuntime">

        <required-facet-version facet="jst.web" version="2.3" allow-newer="true"/>

      </clientRuntime>

    </extension>        

 

        org.eclipse.wst.command.env.ui.widgetRegistry

This allows for the insertion of wizard pages before specific commands.

Example from the org.eclipse.jst.ws.axis.creation.ui plugin:

<extension point="org.eclipse.wst.command.env.ui.widgetRegistry">

       <widgetFactory  

             id="AxisBeanConfig"

        insertBeforeCommandId="org.eclipse.jst.ws.internal.axis.creation.ui.task.BUCheckAxisDeploymentDescriptors"

             class="org.eclipse.jst.ws.internal.axis.creation.ui.wsrt.AxisBeanConfigWidgetFactory"/>

    </extension>
   

    See Contributing Web services runtime with UI for details.

 

·          org.eclipse.jst.ws.consumption.ui.objectSelectionWidget

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 objectSelectionWidgets extension point allows the contribution of GUI mechanisms to locate artifacts of a particular Web service implementation type.

Example from the org.eclipse.jst.ws.consumption.ui plugin for Java bean selection:


<extension

         point="org.eclipse.jst.ws.consumption.ui.objectSelectionWidget">

      <objectSelectionWidget

            class="org.eclipse.jst.ws.internal.consumption.ui.widgets.JavaBeanSelectionLaunchable"

       external_modify="true"      

id= "org.eclipse.jst.ws.internal.consumption.ui.widgets.object.      JavaBeanSelectionWidget"               transformer="org.eclipse.jst.ws.internal.consumption.ui.widgets.object.JavaBeanSelectionTransformer">

      </objectSelectionWidget>

   </extension>


 

Java Classes:

 

The Java Classes extenders needs to extend for contributing a Web service runtime are in the org.eclipse.wst.ws under the org.eclipse.wst.ws.internal.wsrt package:

 

 

 

Examples of how the AbstractWebService and AbstractWebServiceClient classes are extended can be found in the AxisWebService and AxisWebServiceClient class in the org.eclipse.jst.ws.axis.creation.ui and  org.eclipse.jst.ws.axis.consumption.ui plugins respectively.