Apache Axis Live ERP 9780974884325, 0974884324

Citation preview

Apache Axis Live by James Goodwill Copyright © 2004 by SourceBeat, LLC. Cover Copyright © 2004 by SourceBeat, LLC. All rights reserved. Published by SourceBeat, LLC, Highlands Ranch, Colorado. Managing Editor: Technical Editor: Copy Editor: Layout Designer: Cover Designer:

James Goodwill Robert Reynolds Brent Barkley Amy Kesic Max Hays

ISBN: 0974884324

Many designations used by organizations to distinguish their products are claimed as trademarks. These trademarked names may appear in this book. We use the names in an editorial fashion only with no intention of infringing on the trademark; therefore you will not see the use of a trademark symbol with every occurrence of the trademarked name. As every precaution has been taken in writing this book, the author and publisher will in no way be held liable for any loss or damages resulting from the use of information contained in this book.

Table of Contents

Table of Contents iii

Dedication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Chapter 1: Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Installing and Configuring the Axis Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Using the Packaged Axis Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Manual Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Testing the Axis Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Deploying the Axis AdminServlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Path Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 2: Getting Started with the Apache Axis Project . . . . . . . . . . . . . . . 12 What is the Axis Project? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Assembling an Axis Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Creating and Deploying the Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Creating the Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Chapter 3: Custom Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Understanding a Web Service Deployment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Deploying the InventoryService Using WSDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Testing Your Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Undeploying the InventoryService Using WSDD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Apache Axis Live

Dedication

To my girls, Christy, Abby, and Emma

Apache Axis Live

Acknowledgments I would like to begin this text by thanking the people who made this book what it is today. They are the people who took my words and shaped them into something that I hope will help you use and develop Axis applications. Of these people, I would like to especially thank Jennifer Truitt, Amy Kesic, and Brent Barkley—they are the SourceBeat staff that made this title what it is today. I would also like to thank everyone else at SourceBeat for their attention to detail and never-ending desire to make a quality product. On a closer note, I would like to thank everyone at my company, Virtuas Solutions, LLC, for their support while I was completing this text. The entire “UNREAL” staff contributed by picking up my assignments when my plate was too full. Finally, the most important contributors to this book are my wife, Christy, and our daughters, Abby and Emma. They are the ones who really sacrificed during the development of this text, and they are the ones who deserve the credit for this book. Without their support, this text would be a collection of words that made very little sense, at least more than it currently does.

Apache Axis Live

About the Author James Goodwill is the Co-founder and Chief Technology Officer at Virtuas Solutions, LLC, located in Denver, Colorado. James leads Virtuas' Senior Internet Architects in the development of cutting-edge solutions designed for J2EE e-business acceleration. In addition to his professional experience, James is a member of the JSP 2.0 Expert Group (JSR-152.) He is the author of the best-selling Java titles Developing Java Servlets, Pure JavaServer Pages, Apache Jakarta Tomcat, and Mastering JSP Custom Tags and Tag Libraries. James is also a regular columnist on the Java community Web site, OnJava.com.

Apache Axis Live

Preface

Well, I have to tell you that this is one of the more exciting books that I have written. Over my writing career I have written books describing several different open-source topics, and while I really enjoyed writing about the topics themselves, I did not enjoy working on a title for 4 to 6 months, sending it to the publisher, waiting for them to bind and print the text, and then see it hit the bookshelves 3 months later completely out of date. I have had some books hit the bookshelves and, because of the lengthy printing process, the project changed and my examples were completely wrong. This progression was frustrating both to me and my readers. As I am sure you are aware (because you did purchase this title) this text is being published using a completely different publishing model—it is a subscription-based book. This gives me the ability to write on my topic and continually update it based upon changes in the Apache Axis world. I even have the ability to add additional content when I see a new way of doing things or just have a really cool idea that I would like to incorporate. To me this is going to be a lot of fun. You, my readers, will have timely material describing an open-source topic, and I will, for once in my writing career, feel good about the book that I am writing. OK, back to the topic at hand. This book covers everything you need to know about the Apache Axis project and its supporting technologies, including Web applications and the Jakarta-Tomcat JSP/servlet container. The goal of this text is to provide you with the foundation you need to design, build, and deploy Apache Axis applications. As I have stated with most of my book projects, there will be topics that I have not discussed that are of interest to individual readers. If you run across such an issue or just have a question, please feel free to contact me at [email protected] or go to the SourceBeat.com website to subscribe to a mailing list focused on this title and help me develop this uniquely dynamic title. Thanks and Good Luck, James Goodwill III

Apache Axis Live

Introduction The book you are about to begin is formatted as a tutorial describing the Apache Axis project. It is divided into a boundless collection of distinct chapters, beginning with an introduction on Installation and Configuration of the Axis Project, and continuing with discussions about each of the major Axis components: Chapter 1: Installation and Configuration prepares you for the remainder of this title. We begin with a discussion of how you install and configure Axis, both using the packaged axis/ web application and performing a manual installation. We will also cover topics including testing and administering your installation. Chapter 2: Getting Started with Axis lays the groundwork for the complete text. In this chapter, we introduce the Apache Axis project and discuss its purpose. We discuss the different types of SOAP messages including RPC, Message, Wrapped, and Document services. We conclude this chapter with a look at the step-by-step process of building an Axis application. Chapter 3: Explicit Deployment is where we start looking at different Axis deployment methods. We take a look at the Axis Web Service Deployment Descriptor (WSDD) file and its associated components. In this chapter we also describe the hierarchy of a WSDD file. Chapter 4: Axis Inputs and Outputs talks in detail about how you get data to and from an Axis web service. Explicitly, we talk about defining Axis return types, passing simple JavaBeans, using a Bean Mapping, and more complex objects using Axis Serializers and Deserializers. Chapter 5: Axis Clients provides you with a look at some of the different types of Java clients that can communicate with Axis web services. The clients that we will be discussing include Java Applications, Applets, and JSPs. Chapter 6: Securing Your Web Services discusses the different methods of securing your Axis web services. Some of the methods that we will talk about include SSL encryption, roles and privilege management, and how you modify your client to support the different security methods. Chapter 7: Error Handling introduces an often overlooked Axis topic, error handling. In this chapter we discuss Axis exceptions and return type and how these errors can be handled gracefully. Chapter 8: Web Services Description Language (WSDL) provides an introduction to the XML language used when describing web service endpoints. The goal of this chapter is to supply the reader with enough knowledge to understand how web services are described and to prepare them for the following two chapters. Chapter 9: Generating Java from WSDL describes how you can use the built-in WSDL2Java tool to generate client-side Java classes from an existing WSDL file. We will describe the WSDL2Java tool, how it is used, and how the generated classes can be assembled into a working client. Chapter 10: Generating WSDL from Java is the inverse of the previous chapter—it describes how you can use the built-in Java2WSDL tool to generate WSDL from an existing Java interface. We will describe the Java2WSDL tool, how it is used, and the exact steps involved when leveraging the tool.

Apache Axis Live

ix

Introduction

Chapter 11: Axis Monitoring Tools discusses the Axis TCPMonitor tool. In this chapter we will go through the process of configuring the monitoring tool and then move on to how it can be used to assist you in your Axis project development. Chapter 12: Debugging Axis takes you through the process of configuring the Eclipse IDE for debugging Axis applications. This chapter discusses both debugging your applications and stepping though the actual Axis framework. Chapter 13: Supporting Technologies is a supporting chapter focused on defining Java Web applications and explaining how to construct and use them. In addition, we will also examine the Jakarta-Tomcat Web application container, the container used for all our examples, and go though the steps involved when performing a basic Tomcat installation.

Apache Axis Live

Chapter

1

Installation and Configuration

This chapter focuses on the installation and configuration of all of the major Axis components. You will look at a simple installation (using the prepackaged axis web application) and a more complex manual installation. Then, you will cover the steps required to configure the Axis AdminServlet. This chapter closes with a short discussion about configuring your PATH and CLASSPATH settings.

Apache Axis Live

Installing and Configuring the Axis Project

2

Installing and Configuring the Axis Project There are two methods of installing the Axis project. One method is to simply use the Axis web application packaged with the Axis distribution, and the other method is to go through the manual process of moving and configuring each component required by the project. This section covers both methods. Prior to completing either one of these installation methods, you must acquire the Axis distribution. It is located at http://ws.apache.org/axis/index.html.

Figure 1.1: The Axis Project Homepage

For this version of Axis Live, you are going to work with Axis 1.2 alpha. Download both the source and binary distributions. You will work with the binary distribution for most of the examples, but you will utilize the source distribution when you go over some Axis debugging techniques covered in Chapter 12, Debugging Axis. Once you have the binary distribution, extract it to a local directory and peruse its contents.

Apache Axis Live

Installing and Configuring the Axis Project

3

Note: In this text, you will use the Jakarta Tomcat web application container for all of the examples. Specifically, you will use Tomcat 4.1.29. You can find the installation instructions for this version of Tomcat in Chapter 13, Supporting Technologies.

Using the Packaged Axis Web Application The packaged Axis web application is the simplest form of Axis installation. As mentioned earlier, this method is a simple process of finding and moving the packaged Axis web application into the appropriate directory of your web application container. Follow these simple steps: 1. Stop Tomcat. 2. Find the Axis web application in the webapps directory of the Axis binary distribution. 3. Copy this web application to the /webapps directory. 4. Restart Tomcat. That’s it! The Axis project is now running.

Manual Installation This section covers the required steps for installing the Axis project manually. These steps show exactly how the Axis project is configured and will also provide some insight into the components that make up the Axis project. The end result of this section will be an axis web application almost exactly like the preconfigured application discussed in the previous section. Creating the Axis Web Application

First, create a web application named Axis as described in Chapter 13, Supporting Technologies. Once the web application is in place, copy the following JAR files from the Axis distribution’s lib/ directory to the recently created axis/WEB-INF/lib directory: • axis-ant.jar • axis.jar • commons-discovery.jar • commons-logging.jar • jaxrpc.jar • log4j-1.2.8.jar • saaj.jar • wsdl4j.jar

Apache Axis Live

Installing and Configuring the Axis Project

4

Deploying the Axis Components

Deploy the Axis components that you will be using (the next few steps are focused on the configuration of these components). To begin this process, find the axis/WEB-INF/web.xml file and open it in your preferred text editor. 1. Adding the AxisHTTPSessionListener

The first component to deploy is the Axis HttpSessionListener. This class is an extension of the Servlet 2.3 HttpSessionListener, which is used to listen for session life-cycle events. This extension of the HttpSessionListener is used to clean up Axis session objects. While this listener may not seem important to you, it is extremely important to the management of Axis sessions. To deploy this component, add the following element to the beginning of your web.xml file:

org.apache.axis.transport.http.AxisHTTPSessionListener

2. Adding the AxisServlet

The AxisServlet is the most important component of the Axis project. It acts as the controller of all Axis web services. You can find the source for this class in the axis-1_2alpha/src/org/apache/axis/transport/http directory of the Axis src distribution. To deploy this component, add the following definition to the web.xml file:

AxisServlet Apache-Axis Servlet

org.apache.axis.transport.http.AxisServlet

As you can see, there is really nothing special about this entry. To actually make this definition useful, add the Servlet mappings that will map requests to it. Three patterns must be mapped to the AxisServlet, which are shown in the following code snippet. These mappings tell Tomcat to pass all requests, matching the described three patterns, to the AxisServlet. After you have had a chance to look over them, copy them into the web.xml file just after the AxisServlet definition.

Apache Axis Live

Installing and Configuring the Axis Project

5

AxisServlet /servlet/AxisServlet

AxisServlet *.jws

AxisServlet /services/*

3. Adding the MIME Mappings

Add the required MIME type mappings to the axis/ web.xml file. These entries simply tell Tomcat that requests with these extensions should be served up as text/html to the browsers. Add these mappings immediately after the previous entries.

wsdl text/xml

xsd text/xml

4. Adding the Welcome Files and Happy Axis

Finally, add the welcome file entries that you will use in your application to the axis/ web.xml file. This step is not required when deploying a production solution, but it will assist you in future chapters. Add the following entry to the end of your current web.xml file:

index.html

To complete this step, copy the index.html and happyaxis.jsp files from the axis/ web application packaged with the distribution into the root directory of your web application, also called axis.

Apache Axis Live

Installing and Configuring the Axis Project

Testing the Axis Installation After either installation method, you must test your installation. To do this, restart Tomcat and open your browser to the following URL: http://localhost:8080/axis/. You should now see a page similar to Figure 1.2.

Figure 1.2: The Axis Application’s Index.html

Apache Axis Live

6

Installing and Configuring the Axis Project

7

Now, select the Validate link or navigate to the happyaxis.jsp in a browser. This JSP validates your installation. If Axis is happy, you should see an image similar to Figure 1.3.

Figure 1.3: The happyaxis.jsp Validation Page

Apache Axis Live

8

Deploying the Axis AdminServlet

Deploying the Axis AdminServlet The next step concerning the AdminServlet looks like it belongs in the previous discussion, but it is separate from the other steps because of its optional nature. This servlet gives you the ability to manage your Axis deployment with predefined commands that allow you to do things like start and stop Axis, view the currently deployed web services, and get the WSDL describing these web services. It is often thought of as a security issue; you may not want to give someone the ability to manage your application using an HTTP interface. You are going to use the AdminServlet in this text and therefore need to deploy this component. The AdminServlet deployment process is just like the AxisServlet deployment and involves adding two new entries to the web.xml file. The first entry is a definition; add it to the section of the web.xml as shown in the code below.

AdminServlet Axis Admin Servlet

org.apache.axis.transport.http.AdminServlet

100

The second entry defines the ; add it to the section of the web.xml.

AdminServlet /servlet/AdminServlet

Note: If you skipped the manual installation and used the packaged axis web application, then you simply need to open the web.xml file and make sure these entries are uncommented.

To test the deployment of the AdminServlet, restart Tomcat, open your browser once more to http://locahost:8080/axis/, and select the View link.

Apache Axis Live

9

Deploying the Axis AdminServlet

If everything went well, you should now see a page similar to Figure 1.4: a list of the currently deployed web services.

Figure 1.4: The Currently Deployed Web Services

Apache Axis Live

10

Path Modifications

Path Modifications The final topic of this chapter is preparing your environment for development and client execution. There is really nothing special about this—you simply need to make sure that you have the Java executable in your system PATH and add the following JARs to your CLASSPATH: • axis-ant.jar • axis.jar • commons-discovery.jar • commons-logging.jar • jaxrpc.jar • log4j-1.2.8.jar • saaj.jar • wsdl4j.jar Once you have made these path changes, test the environment with the execution of the Axis AdminClient. This command-line tool is used to perform a lot of your client-side administration including deploying and undeploying web services, and listing the currently deployed web services. To test your installation, use the list command as follows: java org.apache.axis.client.AdminClient list

If your paths were set correctly, you will see a relatively long XML document (that you can ignore for now) containing all of your deployed web services and the server relevant data. Note:

If you see a log4j warning, just ignore it for now. This is an issue with the alpha version of Axis.

Apache Axis Live

11

Summary

Summary In this chapter, you focused on preparing the way for all of the subsequent chapters. You learned about Axis installation and configuration, using both the axis web application and the manual installation. Then, you followed the steps required to configure the Axis AdminServlet. Finally, you learned which path changes you need to make to prepare your development environment. In the next chapter, you’ll begin your first real look at the Axis project, including what it is and how it is used.

Apache Axis Live

Chapter

2

Getting Started with the Apache Axis Project

This chapter focuses on getting you started with the Axis Project. You will not be digging into anything with depth (saving the depth for later chapters); rather, you are going to focus solely on the basic components of an Axis Web Service and how these components are assembled in a basic web service.

Apache Axis Live

13

What is the Axis Project?

What is the Axis Project? At its core, the Axis Project is a third generation Simple Object Access Protocol (SOAP) engine. At the highest level, it is a complete framework for constructing and deploying interoperable XML transactions using SOAP. The Axis Project is an open-source Java implementation of SOAP v1.1.

What is SOAP? According to the W3C (the tenants of the SOAP specifications), “SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment.” In other words, SOAP is a relatively easy-to-use method of communicating over different Internet protocols, using XML as the message layer. It’s a wire protocol that leverages HTTP as its transport layer and XML as its data layer to execute remote methods, known as SOAP/Web services. Historically, SOAP was introduced by companies like Microsoft, IBM, and several others. The current specification is SOAP v1.1. However, as of this writing, the W3C has released a working draft of SOAP 1.2, which demystifies some of the more bewildering areas of the 1.1 specification. The Axis implementation of SOAP provides four methods of invoking SOAP services: • Remote Procedure Call (RPC) • Document • Wrapped • Message

Apache Axis Live

14

What is the Axis Project?

Remote Procedure Call (RPC) Services

The RPC method is a synchronous technique using a client server model to execute remote SOAP service. This model is defined by following sequence: 1. A client application builds an XML document containing the URI of the server that will service the request, the name of the method to execute on the server, and the parameters associated with the method. 2. The targeted server receives and unwinds the XML document. It then executes the named method. 3. After the named method has returned its results, Axis maps them into a response XML document and then sends them back to the calling client. 4. The client application receives the response and unwinds the results, which contain the response of the invocated method. Note:

You will be spending the majority of your time on the RPC flavor of Axis SOAP services.

Apache Axis Live

15

What is the Axis Project?

Document and Wrapped Services

Document and Wrapped services are very much alike and therefore can really be discussed within a single context. They both differ from an RPC service in that neither uses SOAP-style bindings in their data-layer representation; their associated data is packaged as simple XML schema data. Therefore, when you look at a Document or Wrapped message coming across the wire, you would see a “non-SOAPified” XML message. The Document and Wrapped services differ from each other only in the way they are processed by the actual implemented service. A Document service that has a schema similar to the following:







A Document service would invoke a service method with the following signature: public void methodName(Person person);

A Wrapped service would invoke a service method with the following “unwrapped” signature: public void methodName(String first, String last); Note: The names of the two previous methods are not important to this example. It is only important that you see the parameter lists.

Message Services

The final SOAP service method provided by the Axis project is the Message service. Use the Message service when you want to provide a service with direct access to the XML data, as opposed to letting Axis map your message into Java objects. As I stated earlier, you’re not going to see much about the type of service, but if you’re interested in seeing how a Message service is constructed, you can find a sample in the Axis archive. /samples/message/MessageService.java

Apache Axis Live

16

Assembling an Axis Web Service

Assembling an Axis Web Service Now that you have a basic understanding of SOAP and its services, look at how the Axis Project implements a service. Several components make up an Axis service. The goal of this section is to show you how to assemble and deploy a simple Axis web service. The steps that you will use to assemble your web service include: 1. Create the service implementation and its supporting classes. 2. Create a client application to execute your web service.

Creating and Deploying the Web Service This section demonstrates the actual web service implementation. This is the code that will be executed on the server-side of your SOAP applications. Creating an RPC-based SOAP service is a very simple process that can be broken down into two steps. The following two sections describe these steps.

Apache Axis Live

17

Assembling an Axis Web Service

Creating the Service Implementation

Creating a SOAP service is the simplest step of the entire "SOAPifying" process. A SOAP service can be just about any Java class that exposes public methods for invocation. The class does not need to know anything about SOAP or even that it is being executed as a SOAP service. The only restriction is that the method parameters must be serializable. Chapter 4, Axis Inputs and Outputs, describes method parameters in greater detail. For this example, create a web service that will act as a somewhat stupid inventory manager. It will contain three classes: the first is the web service itself (Listing 2.1), and the second and third classes contain the business logic used to support the service (Listings 2.2 and 2.3). import ch02.InventoryItem; public class InventoryService { public int addInventory(String sku, int quantity) { InventoryItem item = new InventoryItem(sku, quantity); System.out.println(item); return (ch02.Inventory.addInventory(item)).getQuantity(); } public int reduceInventory(String sku, int quantity) { return (ch02.Inventory.reduceInventory(sku, quantity)).getQuantity(); } public int getInventoryQuantity(String sku) { InventoryItem item = ch02.Inventory.getInventoryItem(sku); return item.getQuantity(); } } Listing 2.1:

InventoryService.java – The InventoryService Implemenation

This InventoryService is a simple Java class that contains three public methods: addInventory(), reduceInventory(), and getInventoryQuantity(). Each of these methods takes simple Java types in their associated method signatures. The InventoryItem used in this service is shown below in Listing 2.2:

Apache Axis Live

18

Assembling an Axis Web Service

package ch02; import java.io.Serializable; public class InventoryItem implements Serializable { public String sku = null; public int quantity = 0; public InventoryItem() { } public InventoryItem(String sku, int quantity) { this.sku = sku; this.quantity = quantity; } public String getSku() { return sku; } public void setSku(String sku) { this.sku = sku; } public int getQuantity() { return quantity; } public void setQuantity(int quantity) { this.quantity = quantity; } public String toString() { return ("SKU = " + sku + " QUANTITY = " + quantity); } } Listing 2.2:

InventoryItem.java – The InventoryItem Bean

This is a simple bean that represents a single piece of inventory.

Apache Axis Live

19

Assembling an Axis Web Service Note: Why pass Integers and Strings back and forth as opposed to using the InventoryItem directly? Axis requires additional configuration to pass non-native objects. Chapter 4 discusses how to pass userdefined objects in detail.

The final server-side class is a bit more complex, but hardly shocking. It actually encapsulates the business logic for your web service. The ch02.Inventory class contains a Hashtable of tag/value pairs representing an inventory SKU and InventoryItem, respectively, and the methods used to add, modify, and retrieve those values. package ch02; import java.util.Hashtable; public class Inventory { private static Hashtable inventory = new Hashtable(); public static InventoryItem addInventory(InventoryItem item) { System.out.println("ADDING : " + item); if ( inventory.containsKey(item.getSku()) ) { InventoryItem currentItem = (InventoryItem)inventory.get(item.getSku()); currentItem.setQuantity(currentItem.getQuantity() + item.getQuantity()); } else { inventory.put(item.getSku(), item); } return (InventoryItem)inventory.get(item.getSku()); } public static InventoryItem reduceInventory(InventoryItem item) { InventoryItem currentItem = null; if ( inventory.containsKey(item.getSku()) ) { currentItem = (InventoryItem)inventory.get(item.getSku()); currentItem.setQuantity(currentItem.getQuantity() – item.getQuantity()); } else {

Apache Axis Live

20

Assembling an Axis Web Service

// this is an error and will be handled in Chapter 5 } return currentItem; } public static InventoryItem getInventoryItem(String sku) { InventoryItem item = null; if ( inventory.containsKey(sku) ) { item = (InventoryItem)inventory.get(sku); } else { // this is an error and will be discussed in Chapter 5 } return item; } } Listing 2.3:

Inventory.java – The Inventory Business Object Implemenation

After you have had the opportunity to look over these classes, compile them so that you can move on to deployment.

Apache Axis Live

21

Assembling an Axis Web Service

Deploying the Web Service

This section describes the web service deployment process—with a caveat. You are actually going to look at an Axis deployment descriptor and then not use it. The standard method of deployment in Axis is to use something known as a Web Service Deployment Descriptor, or WSDD file. While this sounds like a complex file, it is actually a very simple XML file that is used to describe your web service and some of its associated properties. Here’s a sample that could be used to deploy a web service:





As you can see, the file is not very complex. It contains a couple of namespaces, which can be ignored for now, and then a element and two sub-elements used to describe the web service and how it is to be deployed. Don’t focus on this file for more than a couple of seconds; you are not going to use it for now. I just wanted you to see what the normal process is. You will be looking at an entire chapter on web service deployment and undeployment later in this text. For your current purposes, you’re going to use the simplest form of Axis deployment called automatic deployment. It is a simple process that can be broken into three steps: Note: This method of deploying web services is limited and not recommended. I only cover it to make these first examples simple and less confusing. The only time that you may want to use this deployment method is during development.

1. Change the extension of the service implementation source file from *.java to *.jws. InventoryService.java to InventoryService.jws Note: You only compiled this file earlier to make sure that it could be compiled. It really had nothing to do with this process.

2. Copy the newly renamed service file to the following directory of your hosting web application. /webapps/axis/ch02

Apache Axis Live

22

Assembling an Axis Web Service

3. Compile and move any dependant class files to the classes/ directory of your hosting web application. For your example, the classes are ch02/InventoryItem.class and ch02/Inventory.class, and the directory is: /webapps/axis/WEB-INF/classes/ch02

Now you have a complete web service that is implicitly deployed and can be executed by any web service client that is aware of it. Next, look at how this service is executed. Note: It may appear that the InventoryService is in the public package, while its supporting class, Inventory, is in the package ch02. However, that is not exactly true; by placing a *.jws file in a directory matching the ch02 package, you have placed the service into the same package. If you were to place the package statement in the class file, it would receive a java.io.FileNotFoundException.

Apache Axis Live

23

Creating the Client

Creating the Client Now write a client that will execute the service's methods. The Axis Project provides a client-side API that makes it relatively simple to create SOAP clients. An example client, which is used to execute the previously deployed methods, can be found in Listing 2.4. package ch02; import org.apache.axis.client.Call; import org.apache.axis.client.Service; import org.apache.axis.encoding.XMLType; import javax.xml.rpc.ParameterMode; public class InventoryClient { public Integer addInventory(String endpoint) throws Exception { String method = "addInventory"; String sku = new String("SKU456"); Integer quantity = new Integer(8); Service service = new Service(); Call call = (Call) service.createCall(); call.setTargetEndpointAddress(new java.net.URL(endpoint)); call.setOperationName(method); call.addParameter("sku", XMLType.XSD_STRING, ParameterMode.IN); call.addParameter("quantity", XMLType.XSD_INT, ParameterMode.IN); call.setReturnType(XMLType.XSD_INT); Object parameters[] = new Object[] {sku, quantity}; return (Integer)call.invoke(parameters); } public Integer reduceInventory(String endpoint) throws Exception { String method = "reduceInventory"; String sku = new String("SKU456"); Integer quantity = new Integer(2); Service service = new Service();

Apache Axis Live

24

Creating the Client

Call call = (Call) service.createCall(); call.setTargetEndpointAddress(new java.net.URL(endpoint)); call.setOperationName(method); call.addParameter("sku", XMLType.XSD_STRING, ParameterMode.IN); call.addParameter("quantity", XMLType.XSD_INT, ParameterMode.IN); call.setReturnType(XMLType.XSD_INT); Object parameters[] = new Object[] {sku, quantity}; return (Integer)call.invoke(parameters); } public Integer getInventoryQuantity(String endpoint) throws Exception { String method = "getInventoryQuantity"; String sku = new String("SKU456"); Service service = new Service(); Call call = (Call) service.createCall(); call.setTargetEndpointAddress(new java.net.URL(endpoint)); call.setOperationName(method); call.addParameter("sku", XMLType.XSD_STRING, ParameterMode.IN); call.setReturnType(XMLType.XSD_INT); Object parameters[] = new Object[] {sku}; return (Integer)call.invoke(parameters); } public static void main(String[] args) throws Exception { String endpoint = "http://localhost:8080/axis/ch02/InventoryService.jws"; InventoryClient client = new InventoryClient(); Integer ret = client.addInventory(endpoint); System.out.println("Adding Got result : " + ret); ret = client.reduceInventory(endpoint); System.out.println("Removing Got result : " + ret); ret = client.getInventoryQuantity(endpoint); System.out.println("Getting Got result : " + ret); Apache Axis Live

25

Creating the Client

} } Listing 2.4:

InventoryClient.java – The Inventory Client

The best place to begin the examination of this client is in the main() method. The first thing to notice is the String named endpoint. This String represents the location of your web service. The value of this String is a URL that points to the localhost on port 8080 and makes a request for the file InventoryService.jws located in the axis web application. You could ignore the localhost:8080 (it just points to your instance of Tomcat), but you do need to take a look at what it is requesting. This is the file that was renamed and moved into the Axis web application; it contains your web service. When the Axis web application receives a request for a file with a .jws extension, it recognizes it as a special extension because of the following element and passes the request to the AxisServlet for processing.

AxisServlet *.jws

Next, move on to one of the three methods defined by the InventoryClient. The method signatures of all the methods are the same; they all take a single parameter, a URL, to your targeted .jws. Now look at the previously listed InventoryClient.addInventory() method. The first line of the addInventory() method is simple; it creates a String set to the value of the addInventory. If you remember, this is the name of one of the methods found in the InventoryService. String method = "addInventory";

Then it creates the two objects that you will pass to the web service--sku and quantity--which all map to the key value pairs of your Inventory object. String sku = new String("SKU456"); Integer quantity = new Integer(8);

Apache Axis Live

26

Creating the Client

This is where you start using some of the Axis APIs. First, an instance of org.apache.axis.client.Service is created. The Service class is the factory that creates the org.apache.axis.client.Call, which is the object that actually invokes the web service. Service service = new Service(); Call call = (Call) service.createCall();

Once you have a Call instance, start setting the properties needed to invoke your web service. The first property set is the target address of the web service, which in this case is the String passed into this method, http:// localhost:8080/axis/InventoryService.jws. call.setTargetEndpointAddress(new java.net.URL(endpoint));

The next property sets the name of the method that will be invoked, addInventory. call.setOperationName(method);

The next section of code is a bit interesting: call.addParameter("sku", XMLType.XSD_STRING, ParameterMode.IN); call.addParameter("quantity", XMLType.XSD_INT, ParameterMode.IN);

Upon first glance, it appears that you’re adding the parameter names and values used by the web service, but in reality, you are telling Axis to expect two parameters, sku and quantity. Their values will be of type String and Integer, respectively. The real parameter values that will be bound to this request are not actually set until the Call.invoke() method is invoked, which you will see in just a moment. The final property set is the expected return type, which for this example is Integer. call.setReturnType(XMLType.XSD_INT); Note: In this example, the properties of the call object are set using each property’s explicit method. For instance, the call.setOperationName() method is used to set the name of the web service method that’s going to be invoked. The class org.apache.axis.client.Service provides alternative versions of the createCall() method that allows you to pass most of this information in the createCall() parameter list. I have chosen to use these methods to explicitly show each step of the process and describe each property being set.

Apache Axis Live

27

Creating the Client

Now all of the properties are set, and it’s time to invoke your web service. As discussed earlier, Axis has been told what to expect, but no parameter values have actually been passed to the Call instance. To do this, add all of the parameters to an array of objects and then pass the array o the Call.invoke() method, which is done below. Object parameters[] = new Object[] {sku, quantity}; return (Integer)call.invoke(parameters);

When this method is called, it will invoke the addInventory() method of the Inventory web service and pass it the two values for sku and quantity (SKU456 and 8). When it completes, it will return the Integer value result of the addInventory() operation. Note: As for the rest of this client, you don’t need to go over the remaining methods, remove() and getInventory(). They are very similar to the add() method and are just provided to round out the example.

Apache Axis Live

28

Creating the Client

Executing the Client

It is now time to see the results of your labors. To execute this client, complete the following steps: 1. Make sure that your CLASSPATH was set according to the directions provided in Chapter 1, Installation and Configuration. 2. Start Tomcat. 3. Test the results of your web service deployment by opening your browser to the following URL: http://localhost:8080/axis/ch02/InventoryService.jws?wsdl

If the previous section’s deployment was performed correctly, you should see an image similar to Figure 2.1. For now, you can ignore the generated WSDL, but make sure that you see something similar to the following image.

Figure 2.1:

The WSDL Defining Your Inventory Web Service

Apache Axis Live

29

Creating the Client

4. Compile the InventoryClient. 5. Execute the compiled InventoryClient. If everything went well, you should see output similar to the following: Adding Got result : 8 Removing Got result : 6 Getting Got result : 6

Apache Axis Live

30

Summary

Summary This chapter covered quite a bit of material. You began with a brief look at what Axis is and how it implements some of the SOAP services. You then moved on to actually create an Axis web service, deploy that web service, and then execute the deployed web service. The goal of this chapter was to provide you with an overview of what Axis is and how you can use it. At this point, you should feel comfortable with the basic components of an Axis project and how it is assembled. In the next chapter, you’ll see the Axis Web Services Deployment Descriptor (WSDD) and how it’s used to customize the deployment of your web services.

Apache Axis Live

Chapter

3

Custom Deployment

This chapter focuses on the custom deployment of simple Axis web services. In this chapter, you will be looking at Web Service Deployment Descriptors (WSDDs) and how they are used to deploy and undeploy web services. The goal of this chapter is to give you a basic understanding of how you perform custom web service deployment. It is not intended to be a complete guide to WSDD files—a complete WSDD reference is contained in Appendix A of this text.

Apache Axis Live

Understanding a Web Service Deployment Descriptor

32

Understanding a Web Service Deployment Descriptor You have seen an Axis web service, and how you can deploy this service using the .jws extension. Some problems are inherent with this method of deployment, two of which are listed below: • You must have the source code of the web service you are deploying. This means that you are unable to take an existing class file and deploy it as a web service. • Automatic deployment does not allow you to explicitly configure each of your web services. This is important when you are trying to secure your web services with roles and privileges, or when you would like to leverage some of Axis’s built-in handlers (handlers will be discussed in a later chapter), or any other custom configuration needs for a particular web service deployment. The solution to these problems is the Axis Web Service Deployment Descriptor (WSDD). A WSDD file is an XML file used to describe the properties of a particular Axis web service. Some of the configurable properties include servlet roles, method access modifiers, scope modifiers, and many others. Note: We will examine both types of WSDD files in this chapter: those used for web service deployment, and those used for web service undeployment.

The basic syntax of a WSDD file is shown in the following code snippet:





As you look over this XML document, you can see that it is not complex. It begins with the outermost element, , which tells Axis that you are going to be deploying an Axis web service. This element defines two namespaces: the standard Axis WSDD namespace and the Axis WSDD Java namespace. For the most part, you can ignore these namespace definitions; you should just know that they are necessary to prevent element collisions. Once you are past the element, you will start seeing the important parts of the deployment descriptor. The most important of these elements is ; all web services are defined using the element. This element defines the name of the service and the service type. In the example above, the element is telling Axis that the web service name is ExampleService and that should be deployed as an RPC web service.

Apache Axis Live

Understanding a Web Service Deployment Descriptor

33

Next, you will see a collection of sub-elements. These sub-elements are used to set the configurable properties of a web service. The two properties that are being used in this example are className and allowedMethods. ClassName defines the fully qualified class name of the web service being deployed. AllowedMethods identifies the public methods that are available for invocation. (The * signifies that all public methods are available for invocation.) Note: In this section, you have seen the most basic of WSDD files. The complete WSDD references are described later in this text.

Deploying the InventoryService Using WSDD Now that you have seen the basic syntax of a WSDD file, try using a couple of WSDD files. In this exercise, you are going to leverage the InventoryService from Chapter 2, Getting Started with the Axis Project, making some minor modifications to the web service itself and adding both deployment and undeployment WSDD files. To do this, you must complete the following steps: 1. Copy the InventoryService into the package, ch03. There is really nothing special about this step— simply copy the InventoryService.java file into the src/ch03 directory, add the following package statement to the first line of the source file, recompile the source file, and move the resulting class file to the /webapps/axis/WEB-INF/classes/ch03 directory: Note: In this section, you are using the InventoryService.java file as opposed to Chapter 2’s InventoryService.jws file.

2. Next, create the WSDD file that you will use to deploy the ch03.InventoryService. You can place this file just about anywhere you want, but it is often convenient when located with the service source file that it describes. This file is shown in Listing 3.1 below:



Listing 3.1:

deploy.wsdd – The InventoryService Web Service Deployment Descriptor

As you look over this file, you will see that it is deploying a web service named InventoryService. It is a RPC service, with a className of ch03.InventoryService, and allows for the invocation of all of its public methods.

Apache Axis Live

Understanding a Web Service Deployment Descriptor

34

3. Use the Axis AdminClient to register the InventoryService. To do this, pass the deployment descriptor to the AdminClient as a command line argument—the AdminClient will know that you are deploying the web service by the inclusion of the element. The following line shows the registration of the InventoryService: java org.apache.axis.client.AdminClient deploy.wsdd Note: If you are having trouble using the AdminClient, make sure that you have set your classpath using the steps in Chapter 1.

You now have deployed the web service. To verify this deployment, open your web browser to the following URL: http://localhost:8080/axis/servlet/AxisServlet. If everything went according to plan, then you should see a page similar to Figure 3-1.

Figure 3.1:

The AdminServlet’s List of Deployed Web Services

Apache Axis Live

Understanding a Web Service Deployment Descriptor

35

This page shows all of your currently deployed web services. You should see the InventoryService and its available methods included in this list. If for some reason you do not see the InventoryService, check the previous output of the AdminClient and make sure that you received the following results: Processing file deploy.wsdd Done processing Note: To see how a service was deployed, look at the server-config.xml file found in the axis/WEB-INF/ directory. In this file you will see the WSDD (along with other axis configuration definitions) describing the InventoryService. This file is used by Axis to describe its current configuration.

Testing Your Deployment Now it’s time to test the deployment. To do this, make the following changes to the InventoryClient. 1. Move the InventoryClient into the same package as the modified InventoryService, ch03. Just as with the move of the InventoryService, there is really nothing special about this step—simply move the InventoryClient.java file into the src/ch03 directory and change the package statement to the following: package ch03;

2. Change the URL that you request in the client source. This is a simple one-line modification that changes the following line from: String endpoint = "http://localhost:8080/axis/ch02/InventoryService.jws";

to: String endpoint = "http://localhost:8080/axis/services/InventoryService";

As you look over this change, you will see that there are a couple of differences. First, the extension .jws has been removed (because you are no longer requesting a file). Secondly is the addition of the services/ directory. This addition is necessary because you are no longer using the .jws extension to map to the AxisServlet—you are now telling the container that any resource requested from the services/ directory should be mapped to the AxisServlet. Note:

You saw the addition of this servlet mapping in Chapter 1, “Installation and Configuration.”

3. Now, compile your changes and run the client just as you did before, with only one change and that is the pre-pended ch03 as shown below: java ch03.InventoryClient Apache Axis Live

Understanding a Web Service Deployment Descriptor

36

Undeploying the InventoryService Using WSDD Undeployment is the process of removing a service from a collection of previously deployed web services. This process, just like deployment, is not complex and also uses a WSDD file—a WSDD file that will remove the ch03.InventoryService from the axis web application is show in Listing 3.2.

Listing 3.2:

undeploy.wsdd – The InventoryService Web Service Undeployment Descriptor

It is much like a regular deployment descriptor, except that the outermost element is now . This element tells the Axis application that you are removing the service as opposed to deploying a service. The only other thing worth noting is the element. In this instance, the element is used to define the name of the service that you intend to remove. To use this undeployment descriptor, simply execute the AdminClient as you did previously, passing it the undeploy.wsdd file instead of the deploy.wsdd file. java org.apache.axis.client.AdminClient undeploy.wsdd

Now, when you open your browser to the AdminServlet (as you did previously), you will see that the InventoryService has been removed. http://localhost:8080/axis/servlet/AxisServlet Note: You can also use the AdminClient, passing it the list command as opposed to a WSDD file, to view the currently deployed web services:

java org.apache.axis.client.AdminClient list. This will result in a relatively verbose XML file containing the list of deployed web services.

Apache Axis Live

37

Summary

Summary In this chapter, you took a high-level look at custom web service deployment using WSDD files. You also learned how you can both deploy and undeploy web services using the Axis AdminClient. The goal of this chapter was to provide you with a basic look at custom deployment. In the next chapter, you’ll see how Axis handles both its inputs and outputs.

Apache Axis Live