Xfire Tutorial

MyEclipse Learning Center > Web Services Development > Getting Started

MyEclipse Code-First Web Services Tutorial

Outline

1. Preface
2. Requirements
3. Introduction
   1. XFire Java SOAP Framework Overview
4. Creating a Web Service Project
   
   1. Running the Web Service Project Wizard
5. Creating a Web Service: Code-First Strategy
6. Deploying a Web Service Project
   1. Configure the Application Server Connector
   2. Deploy the HelloWorld Project
7. Launching the Tomcat Server
8. Testing a Web Service using the Web Service Explorer
9. Creating a Java Test Client
   1. Additional XFire Library Configuration
   2. Creating the HelloWorldClient Class
10. FAQ
11. References
12. User Feedback

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/

Begin by launching the Web Service Project wizard.  This wizard consists of three pages. Page-1 collects Web Project configuration details. Page-2 collects the XFire configuration details. And page-3 configures the XFire libraries on the new project's build path.

1.   Launching the Web Services Project Wizard.
   
2. 1. Select File>New>Other.
   2. Expand the MyEclipse category followed by the J2EE Projects category.
   3. Select Web Services Project followed by Next.  This will launch the MyEclipse Web Services Project Wizard shown below.
      

Figure-1: New Project Wizard Launcher

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

Figure-2: Page-2, Collecting web configuration details

1. 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.
   

Figure-3: XFire servlet and services.xml configuration

1. 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.
   

Upon completion of the wizard the Libraries will be added to project's build path. No Jar files are copied to the project folder.


Figure-4: Selecting XFire libraries to add to new web service project buildpath

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

Figure-5, illustrates the structure of the newly created HelloWorld web service project.  Note the similarity of a web service project to a standard MyEclipse web project. The additional XFire web service configuration elements are shown in red.

 
Figure-5: Web services artifacts of a new web service project

5.0 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:

Method-1: Launch wizard from MyEclipse perspective toolbar

Choose the New Web Service button on the workbench to open the Web Service Wizard.

Method-2: Launch wizard from workbench menubar

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

Figure-6: Launching Web Service Wizard

With the Web Service Wizard launched proceed as follows:

1. 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.
2. Select Next to advance to page 2.
   

Figure-7: Page-1 of new web service wizard

1. Enter HelloWorldService for the web service name.
2. Select the Java source folder or Select the New button to create a new source folder
3. 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.
   

Note that default values for the Service interface and the Service implementation class are generated based on the name entered in the web service name field. Figure X illustrates the default details

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

Figure-8: Page-2 of new web service wizard.

The wizard generates the IHelloWorldService Java interface and the HelloWorldServiceImpl Java class, and creates a <service> entry in the project's services.xml configuration file, (see Figure-9 below). Note that the example(String message) method was generated in the interface and class to serve as a simple testing operation for when the web service is deployed. This method is not essential to the operation of the web service and should be removed.


Figure-9: Newly created HelloWorld interface and implementation class

6.0 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).

Figure-11: Servers Manager View depicting deployed HelloWorld web service project

7. Starting the Tomcat Server

With the HelloWorld project deployed to Tomcat, we need to launch Tomcat if it is not already running. If the server is running the HelloWorld webapp will be automatically loaded and made accessible. To launch Tomcat choose either the debug launch-mode button or the run launch-mode button (see highlighted buttons in Figure-12). We recommend that you use the debug mode as it enables you to dynamically set breakpoints and hot-swap debug the Java implementation of your web service.



Figure-12: Server Manager before Tomcat 5 launch

A Tomcat starts up can monitor its start up progress in the Eclipse console view.


Figure-13: Eclipse console view depicting real-time Tomcat 5 status info

Once Tomcat is launched and fully initialized the Server Manager will update to reflect the server's execution status and mode.

Figure-14: Server Manager showing active status of Tomcat 5

8. Testing a Web Service with the Web Service Explorer

MyEclipse provides a Web Services Explorer for testing a web service. The Web Services Explorer enables you to interface with any web service given a WSDL document that describes the service.

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

Figure-15: Web Services Explorer launch button on workbench toolbar

1. Select the WSDL Mode (See Figure-16)
   
2. 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.
   
3. Select the example operation in the Actions panel and enter helloworld in the in0 field.
4. Select the Go button to invoke the example operation on our deployed HelloWorldService. The results are presented in the Status panel.
   

Figure-16: Web Services Explorer testing HelloWorldService

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

Figure-17: Choosing the XFire HTTP Client Libraries

Select Finish

9.2 Create the HelloWorldClient Class

Launch the Java class wizard and create the class HelloWorldClient.


Figure-18: HelloWorldClient defined in New Java Class Wizard.

The code segment below defines the process for creating an XFire web service proxy that supports the POJO IHelloWorldService interface. Once the proxy has been constructed and cast to the IHelloWorldService it can be used like a standard Java class.

  
  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.