Developing XFire Web Services & Clients Tutorial

Outline

1. Preface

This document was written using Sun Java 5, Eclipse 3.2 and MyEclipse 5.0.0. All screenshots are based upon the default user interface settings for Eclipse, MyEclipse, and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.

2. Requirements

Following are the basic MyEclipse Web Services prerequisites:

• MyEclipse Web Services requires a Standard level, MyEclipse Subscription
• Java 5 compatibility (requires your Java project compiler compatibility to be set for Java5 or greater)

3. Introduction

This tutorial introduces the process for using MyEclipse web services feature-set to quickly develop and testing a HelloWorld web service using a "code-first" web service development strategy. The code-first strategy concentrates development priorities and effort towards developing application business logic prior to addressing the web service interfacing requirements of the service. Typcially code-first projects will design and implement the Java beans (POJOs) responsible for the core business use-cases. Once satisfied with the POJO implementation, the web service interface will be designed and implemented to expose the public POJO services. This approach is considered ad-hoc by many and is best utilized for prototyping or small standalone system of services.

What is covered in this tutorial?

• An overview of MyEclipse Web Services development concepts
  
• Creation of a MyEclipse web services project
• Creation of a simple HelloWorld web service
  
• Deployment of a web service into a web container such as Tomcat 5
• Testing of a deployed web services using the Web Services Explorer

3.1 XFire Java SOAP Framework Overview

MyEclipse web service features are built on top of the XFire Java SOAP framework and tools. XFire was adopted because of its growing list of basic and advanced features, high performance runtime, rapidly growing community of adopters, and its generous open source license. Some of its key features include:

• Multiple Java-XML binding strategies: JAXB, XMLBeans, Aegis (default)
• Multiple transport support: HTTP, JMS, XMPP, In-memory
  
• Support for Java 5
• JSF-181 annotation support
• JAX-WS support
• Java Business Integration (JBI)
  
• Integrates directly with Spring
  

To view a full list of XFire features visit the XFire site.

4. Creating a Web Service Project

MyEclipse 5.0 introduces a new type of project know as a Web Services Project. This type of project extends the MyEclipse Web Project to support additional web services configuration, development and deployment concerns. This section demonstrates how to use the MyEclipse Web Services Project wizard to create and configure new web service projects.

The Web Service Wizard performs the following actions:

• Creates a MyEclipse J2EE Web Project
  
• Configures the XFire Servlet in the project's web.xml file
• Creates a XFire services.xml configuration file
• Adds the MyEclipse-XFire libraries to the project build path
• Adds a special MyEclipse web project builder to the .project file that deploys the services.xml file to its appropriate deployment location, i.e., <webroot>/WEB-INF/classes/META-INF/xfire/

1.   Launching the Web Services Project Wizard.
   
2. 1. Create a simple Web Service Project by selecting Web Service Project from the new toolbar menu:

2. Complete the Web Project details on page-1 of the wizard and select Next to proceed

3. On page-2 of the wizard enter the XFire servlet and service.xml configuration details. The default values are provided to allow the page to be completed without additional user input.
   

4. On page-3 of the wizard select the libraries to add to the project's build path and deployment profile. The XFire Core Library is required and should always be checked unless you are manually managing the XFire libraries within the project. If you plan to develop a client application in the project include the XFire HTTP Client Libraries as well.
   

5. Select Finish to complete the wizard and initiate the web service creation process.  
   

5. Creating a Web Service - Code-first Strategy

This section demonstrates use of the MyEclipse Web Service Wizard to create an example HelloWorldService using the code-first strategy. Note that we will take advantage of the XFire's built in Aegis Java-XML binding framework. This Java-XML binding strategy is convenient for handling simple type conversion. In cases where a web service operation must accept or return complex structured information additional work maybe required. Please review the Aegis binding documentation for use of Aegis class mapping files.

1. Launch the Web Service Wizard. There are two methods for launching the MyEclipse Web Service Wizard:

1. From the workbench menubar select File>New>Other>MyEclipse>Web Service.
   

Figure-6: Launching Web Service Wizard

2. On page-1 of the wizard, select the HelloWorld web service project and choose the Create web service from Java bean creation scenario as shown in Figure X.
3. Select Next to advance to page 2.
   

4. Enter HelloWorldService for the web service name.
5. Select the Java source folder or Select the New button to create a new source folder
6. In the Java package field, enter an existing Java package name (code-assist is available) or choose the Browse button to select from a list of existing packages. Choose the New button to create a new Java package.
   

7. Select Next to initiate the web service creation process.

6. Deploying a Web Service Project

Before you can interact with you web service it must be deployed to an application server. The MyEclipse web service project is an extended version of the MyEclipse web project. This fact enables a web service to be deployed to any J2EE application server supported by MyEclipse. This section demonstrates the tools and steps to deploy the HelloWorld project to a Tomcat 5 web container.

6.1 Configuring the Application Server Connector

The setup and configuration of the Tomcat 5 application server connector is defined in the Working with Application Server Connectors Tutorial. If you already have a configured application server connector please proceed to the next section.

6.2 Deploying the HelloWorld Web Service Project

Figure-10 below provides a visual outline of the 3 steps required to deploy the HelloWorld application using the MyEclipse J2EE Application Deployer.

1. From the Server Manager select the Deployer button (step-1)
2. In the Server Deployments dialog select Add to create a new deployment (step-2)
   
3. In the New Deployment dialog select the HelloWorld project and the Exploded Archive option.
4. Select Finish in the New Deployment dialog to create and stage the HelloWorld web project as an exploded WAR to the Tomcat 5 server's automatic deployment location
   
5. Select OK in the Server Deployments dialog

Figure-10: Three-step deployment process

The new HelloWorld WAR deployment will appear under the Tomcat 5 node in the Server Manager view (see Figure 11).

7. Starting the Tomcat Server

8. Testing a Web Service with the Web Service Explorer

1. Launch the Web Services Explorer by selecting the toolbar button available in the MyEclipse perspective.

2. Select the WSDL Mode (See Figure-16)
   
3. In the Action panel enter the URL to the HelloWorldService WSDL document: http://localhost:8080/HelloWorld/services/HelloWorldService?WSDL. The Web Services Explorer will download the auto-generated WSDL document created by the XFire framework and create a list of operations that can be invoked on the service. If you are deploying to a different server on be sure to adjust the URL with the proper addr:host information.
   
4. Select the example operation in the Actions panel and enter helloworld in the in0 field.
5. Select the Go button to invoke the example operation on our deployed HelloWorldService. The results are presented in the Status panel.
   

To test other online web services with the Web Services Explorer visit the XMethods repository. The UDDI endpoint is found at http://uddi.xmethods.net/inquire .

9. Creating a Java Test Client

XFire provides a dynamic proxy framework that will read a WSDL document and create the underlying messaging services to enable a Java class to execute actions on a web service. This section provides quick outline of what is required to develop a Java web service client to the HelloWorld web service.

9.1 Additional XFire Library Configuration

For our example client we will create the class in the HelloWorld project. If you have not done so already you need to add the XFire HTTP Client Libraries to the build-path of the project that will contain your Java test client.

1. In the Package Explore view right-click on HelloWorld project and select Build Path>Add Library from the context-menu
   
2. Choose MyEclipse Libraries
   
3. Check the XFire HTTP Client Libraries

Select Finish

9.2 Create the HelloWorldClient Class

Launch the Java class wizard and create the class HelloWorldClient.

  
  public static void main(String[] args) {  
    Service srvcModel = new  
    ObjectServiceFactory().create(IHelloWorldService.class);  
    XFireProxyFactory factory =   
       new XFireProxyFactory(XFireFactory.newInstance().getXFire());  
    String helloWorldURL =  
       "http://localhost:8080/HelloWorld/services/HelloWorldService";  
    try {  
       IHelloWorldService srvc = (IHelloWorldService)factory.create(srvcModel, helloWorldURL);  
       String result = srvc.example("hello world");  
       System.out.print(result);  
    } catch (MalformedURLException e) {  
       e.printStackTrace();  
    } 
  } 
 
						

Launch and execute this class using the right-click Run As>Java Application or Debug As>JavaApplication context-menu actions.

10. FAQ

Q1: Does XFire support WS-1 basic profile? 
A1: Yes, this is the default XFire configuration.

Q2: What is the default XFire WISDL-SOAP binding style and encoding use mode?
A2: The default XFire binding style and encoding mode is document literal wrapped.
See Resources for more information.

Q3: I'm using the default Aegis Java-XML binding and experience a runtime exception when I pass a complex Java object and return a list of complex Java objects to a Java bean exposed as a web service. How do I do this?
A3: Aegis provides a default mapping support for Java-XML binding. But it in cases where a parameter or return value is a complex type (e.g., an aggregate object) or ambiguous (e.g., a Java Collection) you must provide Aegis additional mapping information. Please see the XFire Aegis Binding documentation for more information.

11. References

1. XFire Java SOAP Framework,  XFire home.
2. "Which style of WSDL should I use", Developerworks article 
3. XFire Aegis Java-XML, Binding information.

12. User Feedback

If you have comments or suggestions regarding this document please submit them to the If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum.