Download Create stand-alone Web services applications with Eclipse and Java

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
5.
developerWorks®
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®
4.
ibm.com/developerWorks
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. First, create a new Ant file called build.xml:
1.
Right-click the project and select New > File.
2.
Enter the name build.xml when prompted, then click Finish (see
Figure 9).
3.
Make sure this file opens with the Ant Editor by right-clicking it and
selecting Open With > Ant Editor. From now on, whenever you
double-click this file, it opens with the Ant Editor.
Figure 9. Creating an Ant file
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 13 of 27
developerWorks®
4.
ibm.com/developerWorks
Enter the Ant project shown in Listing 2.
Listing 2. Ant script
<project default="wsgen">
<target name="wsgen" >
<exec executable="wsgen">
<arg line="-cp ./bin -keep -s ./src -d ./bin
com.myfirst.wsServer.SayHello"/>
</exec>
</target>
The Web service server application
Page 14 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
developerWorks®
</project>
5.
To run the Ant build.xml file, right-click Run As and select Ant Build,
which executes the Ant file.
6.
Make sure that this results in a BUILD SUCCESSFUL message in the
Eclipse Console window, as shown in Figure 10.
Figure 10. Ant build success
7.
Return to the Eclipse project and refresh the project by right-clicking
wsServerExample and selecting Refresh. You should now see the
generated code to run the Web service created under the new package
called com.myfirst.wsServer.jaxws (see Figure 11).
Figure 11. Generated code
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 15 of 27
developerWorks®
ibm.com/developerWorks
Section 5. Publish the Web service
After you've generated the code for the Web service's server, you need to publish it
so you can start using it:
1.
Create a new class under the com.myfirst.wsServer package you created,
and call it something like RunService.
2.
Right-click the package and select New > Class, but this time select the
option to create the main method stub.
3.
Write the code to publish your Web service, as shown in Listing 3.
Listing 3. Publishing code
package com.myfirst.wsServer;
import Javax.xml.ws.Endpoint;
public class RunService {
/**
* @param args
*/
public static void main(String[] args) {
System.out.println("SayHello Web Service started.");
Endpoint.publish("http://localhost:8080/wsServerExample",
new SayHello());
}
}
Java SE 6 provides new support for publishing Web services. The
Endpoint API simply publishes the Web service endpoint, which
generates the WSDL at run time at a URL.
4.
Run this class by right-clicking it and selecting Run As > Java
Application. The Eclipse IDE Console window should display. If it
doesn't, select Window > Show View > Console. You should see an
indication that the Web server has started, as shown in Figure 12.
Figure 12. Console with the service running
The Web service server application
Page 16 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
developerWorks®
Section 6. View the WSDL
Now that the server is up and running, you should test it to make sure it's working as
expected:
1.
Open the internal Web browser in Eclipse by selecting Window > Show
View > Other > General > Internal Web Browser.
2.
type the URL, such as
http://localhost:8080/wsServerExample?wsdl, which should
display the Web service's WSDL text, as shown in Figure 13.
Figure 13. Console with the internal Web browser
3.
When you're finished, you can stop the Web service by clicking the red
square in the Eclipse Console view. However, to continue the tutorial the
Web service needs to remain running.
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 17 of 27
developerWorks®
ibm.com/developerWorks
Section 7. Test the server
Next you use the Eclipse Web Services Explorer tool to invoke the operations of a
Web service via native WSDL and SOAP to test the getGreeting method of the
Web service you just created.
1.
You may need to change to the Java EE perspective. Click Window >
Open Perspective > Other.
2.
When the window appears, select Java EE.
3.
Select Run > Launch the Web Services Explorer. Maximize the view by
double-clicking its tab. You should see the screen shown in Figure 14.
Figure 14. The Web Services Explorer
4.
Click the icon indicated by the red circle. This displays the WSDL page,
as shown in Figure 15.
Figure 15. WSDL page
The Web service server application
Page 18 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
developerWorks®
5.
In the Navigator pane, click WSDL Main. The Actions pane is updated, as
shown in Figure 16.
6.
Enter the WSDL URL, in this case
http://localhost:8080/wsServerExample?wsdl, then click the
Go button.
Figure 16. Entering WSDL URL
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 19 of 27
developerWorks®
7.
ibm.com/developerWorks
The WSDL should successfully open, and you should see a screen
similar to Figure 17.
Figure 17. Successfully opened WSDL
The Web service server application
Page 20 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
8.
developerWorks®
Next you invoke an operation by clicking getGreeting under Operations
(shown in Figure 17). This results in a screen similar to Figure 18.
Figure 18. Invoking an operation
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 21 of 27
developerWorks®
9.
ibm.com/developerWorks
Under getGreeting in the Body section, click the Add link (as shown in
Figure 18) to add a new row to the values table.
10. Enter a name (here, Fiona), and click the Go button.
11. In the Status section, getGreetingResponse displays the result. You
should see a You should see a result like return (string): Hello
Fiona (see Figure 19) in the Status section. You might need to scroll or
drag the views to see the result.
Figure 19. Result of the operation
The Web service server application
Page 22 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
developerWorks®
Section 8. Summary
Creating, generating, and publishing a Web service server is as simple as using
Eclipse and, of course, Java SE 6. Stay tuned for Part 2 of this tutorial series where
you'll build the stand-alone client to use with this stand-alone Web service server.
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 23 of 27
developerWorks®
ibm.com/developerWorks
Section 9. Appendix: A brief overview of Web services
terms and acronyms
Web service
According to W3C, a Web service is the "software system designed to support
interoperable Machine to Machine interaction over a network." In other words, Web
services are programmatic interfaces used for application-to-application
communication. Typically, they are used as Web applications that enable the
communication between computers over a network, such as the Internet.
Clients and servers communicate using XML messages that follow the SOAP
standard. That is, Web services use XML to code and decode data and SOAP to
transport it using open protocols. Two of the basic elements of Web services
platforms are SOAP and WSDL.
XML
Extensible Markup Language (XML) lets users define their own elements. It's a
general purpose specification facilitating the sharing of structured data across
different information systems, typically across a network. XML is designed to carry
information and not to display it. In other words, XML does not actually do anything
other than to structure, store, and transport information; it's just plain text.
SOAP
SOAP used to stand for Simple Object Access Protocol, but this was dropped in
version 1.2 because it was believed to be too misleading. It's a lightweight
communication protocol that lets applications exchange information over networks
using XML, or more simply, for accessing a Web service. SOAP allows applications
to communicate with each other regardless of which operating system they're
running on and what programming language they were written in.
WSDL
A WSDL is an application-readable Web Services Description Language. It's used to
describe the Web service's features and how it should be called by the client
The Web service server application
Page 24 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
developerWorks®
application. That is, it describes all the methods and its signatures, the namespaces,
plus the handling Uniform Resource Identifier (URI) for the Web service in an XML
document. The URI names a resource on a network.
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 25 of 27
developerWorks®
ibm.com/developerWorks
Resources
Learn
• Start here for more Eclipse IDE project resources.
• Visit the W3C site.
• In the Architecture area on developerWorks, get the resources you need to
advance your skills in the architecture arena.
• Discover the new Java SE 6 features.
• The SOA and Web services zone on IBM developerWorks hosts hundreds of
informative articles and introductory, intermediate, and advanced tutorials on
how to develop Web services applications.
• Play in the IBM SOA Sandbox! Increase your SOA skills through practical,
hands-on experience with the IBM SOA entry points.
• The IBM SOA Web site offers an overview of SOA and how IBM can help you
get there.
• Stay current with developerWorks technical events and webcasts.
• Browse for books on these and other technical topics at the Safari bookstore.
• Check out a quick Web services on demand demo.
Get products and technologies
• Download the Eclipse IDE for Java EE developers.
• Download Java SE 6.
• Download IBM product evaluation versions and get your hands on application
development tools and middleware products from DB2®, Lotus®, Rational®,
Tivoli®, and WebSphere®.
Discuss
• Participate in the discussion forum for this content.
• Get involved in the developerWorks community by participating in
developerWorks blogs.
About the authors
Fiona Lam
Fiona Lam is a software engineer and works for the Australian Development
The Web service server application
Page 26 of 27
© Copyright IBM Corporation 2008. All rights reserved.
ibm.com/developerWorks
developerWorks®
Laboratory as part of IBM Tivoli Security Development.
John Robertson
John Robertson is a staff software engineer and also works for the Australian
Development Laboratory as part of IBM Tivoli Security Development.
Trademarks
IBM, the IBM logo, ibm.com, DB2, developerWorks, Lotus, Rational, Tivoli, and
WebSphere are trademarks or registered trademarks of International Business
Machines Corporation in the United States, other countries, or both. These and other
IBM trademarked terms are marked on their first occurrence in this information with
the appropriate symbol (® or ™), indicating US registered or common law
trademarks owned by IBM at the time this information was published. Such
trademarks may also be registered or common law trademarks in other countries.
See the current list of IBM trademarks.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
and/or other countries.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States,
other countries, or both.
The Web service server application
© Copyright IBM Corporation 2008. All rights reserved.
Page 27 of 27