Build an RPC service and client using JAX-RPC Using the Java APIs for building RPC-based Web services Skill Level: Introductory Brett McLaughlin ([email protected]) Author/editor O'Reilly Media 15 Jul 2008 Remote procedure calls (RPCs) are the precursors to modern Web services that are based on the Simple Object Access Protocol (SOAP) or Representational State Transfer (REST). Because all of the Java™ platform's Web service APIs are built on the concepts introduced in RPC, understanding the Java APIs for XML-Based RPC (JAX-RPC) is an almost mandatory step for writing efficient and effective Web services in the Java language. This tutorial takes you through getting and installing JAX-RPC, configuring it, and building a server-side RPC receiver and a simple client-side application. Section 1. Before you start About this tutorial This tutorial is a complete guide to installing, configuring, building, and exercising (running) Web services that are based on remote procedure calls (RPCs). You'll download and install an implementation of the Java APIs for XML-Based RPC (JAX-RPC), learn how JAX-RPC is represented in Java classes and packages, and build both a client and server to allow for RPC-based interactions. Configuration options are covered, and you'll become comfortable deploying your own RPC-based applications. Build an RPC service and client using JAX-RPC © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 47 developerWorks® ibm.com/developerWorks Objectives This tutorial walks you through the construction of JAX-RPC Web services, from start to finish. More important, you'll see how all Web services are constructed. This tutorial covers the basics of client-server interactions in a service-based architecture and explores RPC simply as one implementation of those principles. You'll also gain a thorough understanding of the JAX-RPC APIs, all in the context of practical use. Although you won't use every method of every class, you'll know which classes and methods are essential in a real-world context, and why some methods are not useful. All of these concepts are presented in the context of building one working RPC-based client and server. Because service-based architectures are less direct — and somewhat harder to manage — than a typical client-server Web interaction (such as an HTML front-end making POST requests to a Java servlet), they're harder to implement well. This tutorial explores some of the best practices for building Web services, as well as common mistakes. You'll also: • Understand the basics of JAX-RPC as they relate to the wider scope of Web services • See how RPC-based services are different from SOAP- and REST-based services • Understand when RPC services are still a good choice, despite some of the more "modern" approaches to Web services Prerequisites This tutorial is written for Java programmers. You should be comfortable coding Java applications and working with standard and third-party Java APIs and toolkits. You'll also need a Web server that's capable of hosting server-side Java applications (servlets). You can use any Java-capable Web servlet container, application server, or hosting provider. One of the most popular solutions is Apache Tomcat, which is both free and well-documented. It's also up to you whether you test out your programs on a remote server (at your company or an ISP), or on your local machine. You just need to have the server installed and running on an accessible machine. Details about how to configure JAX-RPC on those servers are included in the tutorial, so you don't need to understand the relationship between JAX-RPC's servlets and your Web server yet. Build an RPC service and client using JAX-RPC Page 2 of 47 © Copyright IBM Corporation 1994, 2008. All rights reserved. ibm.com/developerWorks developerWorks® Knowledge of Java servlets and Apache Tomcat (particularly the servlet-hosting facilities and the web.xml deployment descriptor file) is helpful, although not strictly required. See Resources for pointers to additional information on these topics. This tutorial focuses on JAX-RPC and the Apache Axis open source implementation of JAX-RPC, but no previous knowledge of RPC, JAX-RPC, or Apache Axis is required. Details regarding their download, installation, and configuration are covered in the tutorial. Section 2. Download and install Apache Axis Because JAX-RPC isn't part of a standard Java distribution, you'll need to do a little work to get it installed and configured. (As I'll explain in a moment, you won't actually install JAX-RPC itself; rather, you'll install a particular JAX-RPC implementation.) Don't worry now about what RPCs are; you'll know a lot more than just the basics of RPC before you get much further. For now, just follow these instructions to make JAX-RPC usable, so you can learn as you experiment with both the API and programs that use the API. Check your servlet engine Confirm that you've got a servlet engine running and accessible, and that you know both the hostname and port for accessing that server via a Web browser. If you've installed Apache Tomcat on your local machine, you can access the server's Web page at http://localhost:8080, and you should see something like Figure 1: Figure 1. Confirming a working Tomcat installation Build an RPC service and client using JAX-RPC © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 3 of 47 developerWorks® ibm.com/developerWorks Obviously, you'll see something different if you've installed a different servlet engine or if you've got content set up in Tomcat already. Still, as long as you have a servlet engine that you can get to, you're ready to proceed. You don't need to install JAX-RPC Like the Java API for XML Binding (JAXB) or the Java API for XML Processing (JAXP), and even standard APIs like JDBC, JAX-RPC is really an API specification. Build an RPC service and client using JAX-RPC Page 4 of 47 © Copyright IBM Corporation 1994, 2008. All rights reserved. ibm.com/developerWorks developerWorks® In other words, it is as much a document as it is a set of Java classes and interfaces. That document describes how JAX-RPC classes and interfaces behave; it doesn't describe how to build a JAX-RPC application, but it does detail the components involved and how they're represented by Java constructs. The API also includes a set of classes and interfaces, also referred to as JAX-RPC. (It's a little confusing that several things are referred to colloquially as "JAX-RPC.") These classes and interfaces are sometimes called language bindings (especially when XML specifications are involved), but in short, they're just the constructs defined by the specification. There's no sample class, no example code, no dummy services to test things out. The classes and interfaces included with JAX-RPC are all in the javax.xml.rpc package and several subpackages: • javax.xml.rpc.encoding • javax.xml.rpc.handler • javax.xml.rpc.handler.soap • javax.xml.rpc.holders • javax.xml.rpc.server • javax.xml.rpc.soap Three interfaces in the base javax.xml.rpc package are its core components: • javax.xml.rpc.Call • javax.xml.rpc.Service • javax.xml.rpc.Stub You'll learn more about each of these interfaces and the other JAX-RPC packages throughout this tutorial. For now, notice that the three core components are interfaces, and not classes. In fact, the core JAX-RPC package includes only a few concrete classes, and two of them — NamespaceConstants and ParameterMode — are really utility classes. So where are the classes, the code to instantiate with new? JAX-RPC separates API from implementation The designers of JAX-RPC defined a specification and then wrote lots of interfaces. These interfaces define class names and behavior, but they don't implement that behavior. Instead, vendors can write their own APIs that implement JAX-RPC's standardized interfaces. Build an RPC service and client using JAX-RPC © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 5 of 47 developerWorks® ibm.com/developerWorks For you, this boils down to one simple fact: JAX-RPC, on its own, isn't very useful. It's lots of methods and interfaces, without anything to support and implement them. As a result, there's really no such thing as "installing JAX-RPC." What you want, instead, is an implementation of JAX-RPC. Conveniently, all the available implementations come with the JAX-RPC interfaces, packaged nicely. So although you might choose to download the JAX-RPC specification document (see Resources), you don't need to do anything to install JAX-RPC other than install a particular implementation of the API. Install Apache Axis The implementation of JAX-RPC used in this tutorial is Apache Axis. Axis is free, open source, well-known, and well-supported. The tutorial uses Apache Axis 1.4 rather than the somewhat bleeding-edge Axis 2.0, a retooling of the API that is not as useful for RPC applications. Axis 1.4 is still current and supported. Download Apache Axis 1.x First, go to the Apache Axis 1.x Web site's Releases page. You'll see a long list of releases you can download, organized by version number (see Figure 2): Figure 2. Choose the latest version of Apache Axis that starts with a "1" Build an RPC service and client using JAX-RPC Page 6 of 47 © Copyright IBM Corporation 1994, 2008. All rights reserved. ibm.com/developerWorks developerWorks® Select the latest version; I'm using version 1.4 in this tutorial.