Use cases for Axis2 Integration in WTP

Use cases for Axis2 Integration in WTP

There are a number of use cases for integrating Apache Axis2 Web services runtime into WTP.

Install and Configure an Apache Axis2 Web service runtime

In order to let users create or consume Axis2 Web service components in an Eclipse workspace, the Web service development tools need to have access to the Axis2 jars to copy them to the Web project containing the Web service component. Currently, the latest Axis2 version available is Axis2 1.1. If WTP includes a copy of the Axis2 jars in a plugin, similar to the current implementation of the tools for Axis 1.3, WTP will need to keep updating the plugin with newer releases of Axis2 as they become available. Not only is this extra work for the development team and the legal team, but it may inconvenience those users who have invested in an earlier release of Axis2 and do not want to be forced to move up to the latest version. Similarly to the relationship between Server Tools and Apache Tomcat, the preferred approach is for the user to download the version of Axis2 they want and then point the Axis2 Web service tools to the location of the download (in zip or unzipped form).

Detailed steps

1. In the Preference page, select Web Services -> Axis2 -> Installed Web service runtimes.
2. Expand the Axis2 tree and select Axis2 1.1.
3. Click the Browse button to specify the location of the Axis2 zip or home directory.
4. If the expected Axis2 jars are not found under the specified location, an error message is shown.
5. Click Finish.

The above approach is similar to installing a server runtime for Apache Tomcat. The various Axis2 versions are hard-coded (e.g. Axis2 1.0, 1.1, 1.2, etc.) if the various JARs that are needed to run Axis2 1.x Web service stays the same, it could be just presented as Axis2 1.x. However, if down the road when there are more Axis2 versions available and the JARs are different, the Web service runtime adapter for Axis2 would have to be updated to include the newer Axis2 versions explicitely.

Another approach is to add a 'Don't see your Web service runtime listed? Click here.' link in the Install Web Service Runtime page similar to the 'Don't see your server listed? Click here.' link in the Install Server Runtime. This is how Geronimo 1.0 and 1.1 servers can be dynamically discovered and loaded. With this approach, new Web service runtimes (such as different versions of Axis2) can be dynamically discovered and installed.

Add the Axis2 Facet

To develop an Axis2 Web service or client, the Axis2 jars need to be available to the Web project that will contain the Web service or client. These jars can be copied from the Axis2 Web service runtime location during the wizard (similar to Axis 1.x), or they can be installed into the Web project through a new Axis2 facet. A benefit of using a facet is it affords users the option of equipping a project for development of Axis2 components without necessarily having to use the Web service wizards.

Detailed steps

1. When creating a dynamic Web project, select Next.
2. Axis2 facet is one of the available facets to add to the project.
3. Different versions of Axis2 can be selected by using the drop-down combo.
4. The selected version of Axis2 jars will be copied to the WEB-INF/lib directory of the destination project when the user clicks Finish.

Create an Axis2 Web Service or Client

Axis2 is another Web service runtime similar to Axis 1.x, and would be available via the wizards, popup dialogs and Ant tasks. Tools for the Axis2 Web service runtime will extend WTP's Web service/client framework with logic to handle the develop, assemble, deploy, install, start and test phases of creating a Axis2 Web service component.

Detailed steps

1. Visit Preferences -> Web Services -> Axis2 -> Code Generation to review or change preferences for the creation of Axis2 services or clients.
2. Select the Web service wizard or the Web service popup action.
3. On the first page of the Web service wizard,
   1. Select the Web service type (bottom-up Java bean Web service or top-down Java bean Web service).
   2. Select the service implementation (Java bean) or sevice definition (WSDL URI).
   3. Use the scale to choose to develop, assemble, deploy, install, start or test.
   4. Click the Web service runtime hyperlink to change the Web service runtime to Axis2.
   5. Click the Server hyperlink to select a server supporting the Axis2 runtime.
   6. Click the Project link to select a project. If the project does not yet exist, it will be created. If an exsiting project does not already have the Axis2 facet installed, it will be added.
   7. Make similar choices for the client as desired.
4. Click Next to get to the wizard pages contributed by the Axis2 extension.
5. In the Axis2 contributed wizard pages, make choices relevant to the Axis2 Java2WSDL and WSDL2Java code generators.
   • The wizard pages are simple with most commonly used controls exposed and more advanced controls hidden under sections/buttons or optional pages (similar to custom mapping checkbox in the Axis 1.x wizard pages). The controls are defaulted based on the Axis2 preference page (similar to Axis 1.x emitter preference page).
   • Various WSDL, Java and deployment artifacts (such as services.xml) are generated by the Axis2 code generators.
   • The Axis2 code generator effectively reads from and writes to resources in the Eclipse workspace with no manual refreshing required by the user. Web service resource management preferences (file overwrite, folder creation, automatic checkout) are respected.
   • If the Web project already contains an existing Axis2 exploded Web service archive (aar), the services.xml file generated for the service is merged with the services.xml file in the archive.
   • The services.xml also can be edited. Add/remove valid services within the service gruop, change the scope of the service group or change the MessageReceiver class.
   • The generated artifacts will be organized into an exploded aar for deployment to the server without the need for an explicit builder to produce a ".aar" file.
6. When Next is clicked, the user proceeds to the other Web service wizard pages as defined by the Web services creation framework. This may include starting the server (if it is not already started) and testing the Web service using the Web Services Explorer.

Note: Similar steps are expected for Web service client creation.

Edit a Deployed Web Services

After a Web service is created and started, the user can alter it in a couple of ways:

1. Hot Deployment: Edit and save the Java implementation file. The updates are reflected immediately into the deployed service without restarting the server or module.
2. Hot Update: Change the services.xml or the service directory structure (e.g. change the parameters in services.xml). The updates are reflected into the deployed service after a time interval.

Detailed Steps

1. Open a service implementation ".java" file in the editor.
2. Change the implementation and save.
3. Reinvoke the changed operation via the Web Services Explorer.

Or

1. Open the services.xml file in the XML Editor.
2. Alter the xml file (Can add/remove another valid service to the service group).
3. Reinvoke the changed operation via the Web Services Explorer.

Export an AAR

Axis2 archives (aar) exist only in exploded form in the workspace. Users can choose File -> Export -> Axis2 Archive to export a ".aar" file to the file system (similar to WAR export).

Detailed steps

1. Select Export -> Web services -> Axis2 Archive (AAR)
2. Select the project to export by entering the name or using a Browse button.
3. Select the destination for the export.
4. Click Finish.

Import an AAR

Users can choose File -> Import -> Axis2 Archive to import a ".aar" file to the file system (similar to WAR import). After the AAR import, the Axis2 archives exist in exploded form in the workspace.

Detailed steps

1. Select Import -> Web services -> Axis2 Archive (AAR)
2. Browse to select the AAR file from the file system.
3. Select the project in the workspace to import to AAR to
4. Click Finish.
5. The services.xml in the imported AAR would be validated while being imported.

Explore Axis2 Web services in the Project Explorer

After Axis2 Web services are created, they should show up in the Project Explorer view, either:

• beside the JSR-109 Web Services folder, in a new Axis2 Web Services folder, or
• under a general Web Services, folder with at least 2 sub-folders called JSR-109 Web Services and Axis2 Web Services.

Either way, the user will be able to navigate to the various Axis2 Web service and client artifacts in the Project Explorer view.

Detailed steps

1. After creating an Axis2 Web serivce or a Web service client to an Axis2 Web service, go to the Project Explorer view of the J2EE Perspective.
2. Expand the Axis2 Web Services folder.
3. The Axis2 Web services in the workspace is listed.

Discovery and testing of Axis2 Web services via the Web Services Explorer

The Web Services Explorer (WSE) can be used to discover Web services in the workspace and then used to test it. Axis2 Web services would be listed under it's own category similar to Axis 1.x Web services listed under it's own category.

Detailed steps

1. Clicks Browse to bring up the WSDL Browser dialog in the WSDL Main page of the WSE.
2. Selects Apache Axis2 components in the drop-down combo and then select a Axis2 Web service from a list of WSDL URLs.
3. Clicks Go to exit the WSDL Browser dialog.
4. Clicks Go again to test the Axis2 Web services using the WSE.

Using the Axis2 generated JUnits to test Axis2 Web services

When creating Web services clients using Axis2 Web service runtime, the user could use the Axis2 generated JUnits to test the Axis2 Web services.

Detailed steps

1. Brings up the Web service wizard or Web service client wizard. Select Axis2 Web service runtime.
2. Move client scale slider to test.
3. The Axis2 JUnit is among the test facility that could be chosen to test the Axis2 Web service client.

Using the Web service sample JSP to test Axis2 Web services

When creating Web services clients using Axis2 Web service runtime, the user could use the familiar Web services sample JSP to test the Axis2 Web service.

Detailed steps

1. Brings up the Web service wizard or Web service client wizard. Select Axis2 Web service runtime.
2. Move client scale slider to test.
3. The Web service sample JSP is among the test facility that could be chosen to test the Axis2 Web service client.

Create handler for Axis2 Web services

The user could use handler configuration wizard or services.xml editor to add service or client handler to Axis2 Web services.

Detailed steps

1. In the Project Explorer in the J2EE perspective, right-click on an Axis2 Web service or an Axis2 Web service client.
2. Select Handler Configuration from the context menu.
3. Select the handler class and optionally generate handler skeleton file.
4. Click Finish to add handler to the Web service or Web service client.

Add and configure Quality of Service to Axis2 Web services

Quality of Service (QoS) functionalities (such as WS Policy, WS Security and WS Reliable Messaging)can be added to enhance Axis2 Web services.

JAX-WS module support for Axis2 Web services

Provide JAX-WS module support for Axis2 Web services.

WSDL 2.0 support for Axis2 Web services

The user could use Axis2 Web service runtime to create skeleton Web service or Web service client to WSDL 2.0 files. The user should also have access to WSDL 2.0 editor and validator similar to the current support for WSDL 1.1.