Create stand-alone Web services applications with Eclipse and Java SE 6, Part 1: The Web service server application Skill Level: Intermediate Fiona Lam ([email protected]) Software Engineer IBM John Robertson ([email protected]) Staff Software Engineer IBM 13 Nov 2008 Use the Eclipse Integrated Development Environment (IDE) and Java™ Platform, Standard Edition (Java SE) 6 to create a stand-alone Web services application that can be run from the console. In this tutorial, the first in a series, start by getting familiar with the Eclipse IDE. Configure the environment; create projects, packages, and classes; then run the application from the command line. Section 1. Before you start About this series This tutorial series demonstrates how to create a stand-alone Web services server and client application that you can easily run from the command line with Java SE 6 rather than from within Web application server containers. Using a simple Hello World example, you'll leverage the Eclipse IDE, Java SE 6, and Apache Ant to easily create fully functioning Web services server and client applications. You'll also use the TCP/IP Monitor to examine the communication traffic between the server and client, and use the Eclipse Web Services Explorer tool to test the Web service. The Web service server application © Copyright IBM Corporation 2008. All rights reserved. Page 1 of 27 developerWorks® ibm.com/developerWorks About this tutorial This tutorial, Part 1 of the series, introduces you to publishing a Web service application using the Eclipse IDE, Java SE 6, and Ant. It lays the groundwork for Part 2, which describes the creation of the Web services client application. Objectives After completing this tutorial you should know: • What a Web service is and the standards it uses in relation to a browser being used from within Eclipse to view the published Web Services Description Language (WSDL) file. • How to create the server side of a Web service, including how to install and configure the Eclipse IDE and the Java Development Kit (JDK) so that they perform together to generate the code that's compiled using Java SE 6. • How to use the Ant Java-based build tool within the Eclipse IDE to run a special Java command to generate some of the code. Prerequisites This tutorial includes simple steps written for beginning- to intermediate-level Java programmers with some working knowledge of the Java language and Ant builds. Novice to more advanced Java developers will gain some knowledge of how to build, deploy, and run stand-alone Web services servers and distributed clients to provide firewall-friendly remote communications and applications processing. System requirements To follow the examples, you need to download: • Eclipse IDE for Java Developers • Java SE 6 You don't have to download Ant, as its functionality is bundled with Eclipse. This tutorial uses the Ganymede Package for the Eclipse IDE for Java EE Developers. The Web service server application Page 2 of 27 © Copyright IBM Corporation 2008. All rights reserved. ibm.com/developerWorks developerWorks® Section 2. Set up your development environment Install Java SE 6 1. Download and install the latest Java SE 6 JDK. Java SE 6 has many new features, including Web services APIs. 2. Double-click the executable file and follow the installation instructions. We recommend you perform the typical installation and maintain all default settings, such as location. 3. When asked, select whether you want to install the Java runtime environment as the system JVM and whether you want any browsers to be associated with the Java plug-in. 4. Click Finish to install. 5. Close any browser windows that are open. 6. When complete, you should be presented with a thank-you message confirming successful installation. Click OK to close. Note: Installing the Java Runtime Environment (JRE) as the system Java Virtual Machine (JVM) means that it replaces any JVM found in the Microsoft® Windows® directory or places a new copy in there if one is not found. Associating any browsers with the Java plug-in means that this new version of Java will be used for applets. Install Eclipse Eclipse is an open source, extensible development platform, which can be installed on almost all operating systems. (Learn more about Eclipse.) Installing Eclipse is fairly straightforward because there's no installation process: • Download the Eclipse IDE for Java EE Developers. • Extract the file to the desired location on your computer. You should then see a folder named eclipse. It's a good idea to create a shortcut to the eclipse.exe file on your desktop for convenience. The Web service server application © Copyright IBM Corporation 2008. All rights reserved. Page 3 of 27 developerWorks® ibm.com/developerWorks Configure Eclipse When you first run Eclipse, the Welcome page is displayed, as shown in Figure 1. If you don't want to read the Overview and other offerings, simply close that page and come back to it later by selecting Help > Welcome. Figure 1. Welcome screen Configure Eclipse to use the Java SE 6 JDK you installed earlier; you want to associate your project with this version of Java: 1. Select Window > Preferences > Java > Installed JREs, and click the Add button. 2. Enter a name, such as Java SE 6, to easily identify what version it is. 3. Click the Browse button and locate the directory where JRE 60 was installed. 4. Click OK (see Figure 2). Figure 2. Adding a new JRE The Web service server application Page 4 of 27 © Copyright IBM Corporation 2008. All rights reserved. ibm.com/developerWorks developerWorks® The new JRE should now appear in the list of installed JREs, as shown in Figure 3. 5. Select the Java SE 6 check box, then click OK. Figure 3. Selecting the new JRE The Web service server application © Copyright IBM Corporation 2008. All rights reserved. Page 5 of 27 developerWorks® ibm.com/developerWorks 6. To set compliance to the installed version of Java, select Window > Preferences > Java > Compiler. 7. Select 1.6 from the Compiler compliance level drop-down list, as shown in Figure 4. Figure 4. Setting compliance The Web service server application Page 6 of 27 © Copyright IBM Corporation 2008. All rights reserved. ibm.com/developerWorks developerWorks® Create a project Next you create a project to construct your Web services server. A project contains the source code and other related files, and it lets you use the project as the source container or to set up folders inside the project to organize files. 1. Select File > New > Project. 2. Expand the Java folder and click Java Project (see Figure 5). Figure 5. Creating a project in Eclipse The Web service server application © Copyright IBM Corporation 2008. All rights reserved. Page 7 of 27 developerWorks® ibm.com/developerWorks 3. Click Next. 4. Enter a project name, such as wsServerExample, when prompted, as shown in Figure 6. Figure 6. Entering project details in Eclipse The Web service server application Page 8 of 27 © Copyright IBM Corporation 2008. All rights reserved. ibm.com/developerWorks developerWorks® 5. Select the Use default JRE radio button if it was previously selected by default; otherwise select the Use a project specific JRE radio button, ensuring that it's Java SE 6. The Web service server application © Copyright IBM Corporation 2008. All rights reserved. Page 9 of 27 developerWorks® ibm.com/developerWorks 6. Click Finish to associate your project with the Java JDK you installed earlier. 7. If you're prompted to switch Java perspective, click Yes. Section 3. Create the server First you need to create a Java package to house your Java classes: 1. Select File > New > Package. 2. When the New Java Package window opens, enter a name for the package, such as com.myfirst.wsServer, as shown in Figure 7. Figure 7. Creating a package The Web service server application Page 10 of 27 © Copyright IBM Corporation 2008. All rights reserved. ibm.com/developerWorks developerWorks® Next you need to create a class for the server code: 3. Right-click the package name you just created, then select New > Class. Configure it as shown in Figure 8. Figure 8. Creating a class The Web service server application © Copyright IBM Corporation 2008. All rights reserved. Page 11 of 27 developerWorks® ibm.com/developerWorks 4. Create your class as public with no main method stub. Now that you've provided your package with a class, you can write the code for the server, as shown in Listing 1. Listing 1. Server code package com.myfirst.wsServer; import javax.jws.WebService; The Web service server application Page 12 of 27 © Copyright IBM Corporation 2008. All rights reserved. ibm.com/developerWorks developerWorks® @WebService public class SayHello { private static final String SALUTATION = "Hello"; public String getGreeting( String name ) { return SALUTATION + " " + name; } } Note the text in bold in Listing 1. This is called an annotation, or metadata, which is used by the Web Services Metadata Specification introduced in Java SE 5. Developers define their classes and methods before applying annotations to them to indicate to the runtime engine how to enable the class and its methods as a Web service and Web service operations. Java SE 6 comes bundled with such an engine. The @WebService annotation marks the SayHello class as implementing a Web service, which results in a deployable Web service being produced. This particular annotation is a WSDL mapping annotation and associates the Java source code to the WSDL elements that represent the Web service. (See Resources for more information about other annotations in Java SE 6.) Section 4. Generate the server code with Ant After you've written the server application, you need to generate the Web service-supporting code.