06
Sun, Oct
2 New Articles

Java Journal: Web Services Developer Pack JAX-RPC

Java
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times
Before we dig into this month's "Java Journal" on how to build a Web Service using Sun's Java Web Services Developer Pack, a little celebration is in order. This month's column marks the completion of Java Journal's first year. I hope you have enjoyed reading the articles as much as I have enjoyed writing them, and I look forward to another year of helping you explore the Java Jungle. We've covered a lot of topics over the past year, but many more await our exploration.

One of those topics is Web Services. Lots of people have been talking about Web Services for awhile now. If you are looking for yet another article on how Web Services are going to change the world, then this article is not for you. If, however, you are interested in the fastest way to create a Web Service so that you can start playing with this great new technology, then read on. Sun's Java Web Services Developer Pack (Java WSDP) is a Swiss army knife of tools that you can use to quickly and easily create Java Web Services. As of WSDP Version 1.1, it contains the following:
  • Java Architecture for XML Binding (JAXB) V1.0
  • Java API for XML Messaging (JAXM) V1.1.1
  • Java API for XML Processing (JAXP) V1.2.2 (with XML Schema support)
  • Java API for XML Registries (JAXR) V1.0_03
  • Java API for XML-based RPC (JAX-RPC) V1.0.3
  • SOAP with Attachments API for Java (SAAJ) V1.1.1
  • JavaServer Pages Standard Tag Library (JSTL) V1.0.3
  • Java WSDP Registry Server V1.0_04
  • Ant Build Tool 1.5.1
  • Apache Tomcat 4.1.2 dev container (plus fixes)


You can download the Java WSDP here. There are currently two versions of the kit, one for Windows 2000/XP and one for Solaris 8 and 9 and Red Hat 7.2. You should be able to run it in other environments, but these are the only ones that Sun specifically tests. For the Windows version, you can read the installation instructions here. However, all you really need to know is that to install it you should first have a 1.3.1 or higher version of the Java 2 SDK (J2SE SDK) and about 70 MB of space in addition to the 34 MB that the installation package itself occupies. Double-click on the installer and follow the directions for a typical install. Note that, if you are using the J2SE SDK Version 1.4, you will have to manually move some files as directed by the installer.

You can download a very comprehensive tutorial on using the Java WSDP from here, and the source code from the examples is also available for download from here. The examples are packaged as a zip file that you should unzip to /docs. However, be aware that the tutorial is a somewhat less-than-petite 928 pages. Don't get me wrong; it is a wonderful tutorial, but I think I can come up with an example that is a little less involved to save you some eyestrain. I find it ironic that Web Services are billed as being easy to create, and then most of the explanations either go into great detail about how XML is parsed (yawn) or are based on a drawing with three boxes and some arrows. I've found that just about anything, when condensed down to three boxes and some arrows, looks plausible.

So let's create our own Web Service and Web Service client, but we'll just focus on the code that you actually have to write, and we will cookbook most of the configuration. One of my favorite Arthur C. Clarke quotes is "Any sufficiently advanced technology is indistinguishable from magic," so, for now, let's just assume that what's going on behind the scenes in our example is magic. For those of you who don't believe in magic, I would direct you back to Sun's 928-page tutorial on Web Services. For the rest of you, download and install the Java WSDP. Then, download the Web Services example page and unzip it to the documents directory so that we can nab a few choice configuration files. Now, we are ready to create our Web Service and client.

Example Overview

We are going to build a simple inventory checking Web Service that looks up the quantity of parts in inventory for a particular part number. We will build our Web Service using JAX-RPC. JAX-RPC is in the alphabet soup of acronyms included as part of the Java WSDP. Essentially, it is an XML-based Java API for making remote procedure calls. The XML is wrapped as SOAP messages and sent over HTTP.

First, we will develop and deploy the Web Service itself. Then, we can create a client to test out the Web Service.

Web Service

Our Web Service will simply wait for SOAP messages (requests); then, JAX-RPC will perform the magic of decoding the message into a method invocation on a particular object--in this case, a call to check inventory for a particular part number. The results of the request are returned, and once again, through the magic of JAX-RPC, the results are encoded into a SOAP message and returned to the requestor.

So let's start by cranking up Tomcat and all the other WSDP services. You can do this by going to /bin and double-clicking on shutdown.bat. One of the trickiest parts of building Web Services is building Web Services. What do I mean by that? Well, in our example, the Ant file that we will use to do builds is larger than all the source code combined. This is partly due to the trivial nature of our example; nevertheless, it's worth noting. Here is where we get some significant leverage from the writers of the Java Web Services tutorial. First, go to the /docs/tutorial/examples/jaxrpc directory and create a new directory called inventory. Then, from /docs/tutorial/examples/jaxrpc/hello directory, copy over build.xml to your new inventory directory. This is a very well-crafted Ant build file that we can reuse for our example. Actually, build.xml references another file called targets.xml, which lives in the common directory, but together they will help bootstrap our example. To create our Web Service, we will need to create the following files and store them in our new inventory folder.

  • build.properties--This file is read by the generic build.xml file that we borrowed from the Java Web Services Tutorial and will be provisioned with the files from our example. It will be used for both the Web Service and the Web Service client.
  • InventoryIF.java--This is the service definition interface Java source file.
  • InventoryImpl.java--This is the service definition implementation Java source file.
  • jaxrpc-ri.xml--This configuration file generates ties.
  • web.xml--This file is the deployment descriptor.


What follows is the contents of the files listed above, which should reside in /docs/tutorial/examples/jaxrpc/inventory>:

build.properties

example=inventory
context-path=inventory-jaxrpc

client-class=inventory.InventoryClient
client-jar=${example}-client.jar

portable-war=${example}-portable.war
deployable-war=${context-path}.war

war-path=${tut-root}/tutorial/examples/jaxrpc/${example}/dist/${deployable-war}

username=mike
password=panda

InventoryIF.java

package inventory;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface InventoryIF extends Remote 
{
  public String checkInventory(String s) throws RemoteException;
}

InventoryImpl.java

package inventory;

public class InventoryImpl implements InventoryIF 
{
  public String message = "Inventory ";

  public String checkInventory(String s) 
  {
    String results = "0";

    // In a real world Web Service you would
    // probably have a call to the database here
    if (s.equals("AAA"))
    {
      results = "100";
    }
    else if (s.equals("BBB"))
    {
      results = "200";
    }
    else
    {
      results = "0";
    }

    return results;
  }
}

jaxrpc-ri.xml



    xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd"
    version="1.0"
    targetNamespaceBase="http://com.test/wsdl"
    typeNamespaceBase="http://com.test/types"
    urlPatternBase="/ws">

    
        name="MyInventory"
        displayName="Inventory Service"
        description="A web service to check inventory" 
        interface="inventory.InventoryIF"  
        implementation="inventory.InventoryImpl"/> 
 
    
        endpointName="MyInventory"
        urlPattern="/inventory"/>

web.xml




    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">


  Inventory Checking Application
  A simple example
  
    60
  


To create and deploy our Web Service, we will do the following:

1. Compile the service definition (InventoryIF.java and InventoryImpl.java)
2. Create the WAR file
3. Generate ties and WSDL
4. Deploy and verify the service

The service definition is composed of two Java source files, InventoryIF.java and InventoryImpl.java. We'll compile them by issuing the following Ant command at the command prompt while in the /docs/tutorial/examples/jaxrpc/inventory directory.

ant compile-server

Next, we will package the class files we just generated along with jaxrpc-ri.xml and web.xml into a WAR file with the following commands:

ant setup-web-inf
ant package

These commands create the inventory-portable.war file. Next, we need to generate the tie classes and WSDL file. Tie classes sit between JAX-RPC and the classes that implement a service. WSDL files describe services. We will also need the WSDL file later when we build our client. The following command will generate our ties and WSDL file:

ant process-war

We are now ready to deploy and test our Web Service. The service can be deployed using this command:

ant deploy

Once you have deployed a service, you will need to use this command to redeploy it:

ant redeploy

To test that the service was deployed correctly, launch your favorite Web browser and go to the following URL:

http://localhost:8080/inventory-jaxrpc/inventory

This location is known as the "service endpoint URL." It will report back such information as the PortName, status (active or inactive), the remote interface, and the implementation class.

Congratulations! You have deployed your Web Service! Now, let's make a client to consume it.

Web Service Client

To create a client for our Web Service, we will reuse a couple of the source and configuration files from our Web Service. Additionally, we will want to use the WSDL file that we generated previously. We will need the following files:

  • build.properties--Same as the one from above
  • config.xml--Configuration file for generating Web Service stub
  • InventoryClient.java--The client code class containing main() and a call to the Web Service stub


We will do the following to generate our client:

1. Build the client stubs
2. Compile the client source files
3. Jar the client stubs and class files

Client stubs are the reciprocal of tie classes. As the name implies, a stub is just a local interface that represents a remote service. To build the client stubs, we again use the build.xml file that we liberated from the Web Services tutorial. We can issue the following command to generate the stubs:

ant generate-stubs

Our only new files for the client are InventoryClient.java and config.xml, which look like this:

InventoryClient.java

package inventory;

import javax.xml.rpc.Stub;

public class InventoryClient
{
  public static void main(String[] args) 
  {
    try 
    {
      Stub stub = (Stub)(new MyInventory_Impl().getInventoryIFPort());
      InventoryIF inventory = (InventoryIF )stub;
      String partNumber = "AAA";
      System.out.println(inventory.checkInventory(partNumber));
    } 
    catch (Exception ex) 
    {
      ex.printStackTrace();
    }
  }    
}

config.xml



  xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  
       packageName="inventory"/>


Compile InventoryClient with this command:

ant compile-client

Then, jar it up:

ant jar-client

Now, we can test our Web Service by invoking the client:

ant run

Our expected result is that the client will look up partNumber AAA, find that there are 100 available, and echo that back out to the command line. Of course, to check for other partNumbers, you will need to modify the client source code, recompile, and re-jar.

And that's all there is to it! There are some log files in /logs that are helpful to take a look at if you have any problems.

Summary

In order to create Web Services, you don't have to become an XML guru or understand all the gory details of XML parsing or namespaces. Instead, it is possible to create some simple examples and rely on the tools to provide a little magic. We simply made a Java client that makes requests to a stub and defined a serve- side Java interface and implementation to handle requests. Everything in between was handled by the generated stubs and tie classes that in turn talk to the underlying JAX-RPC infrastructure. When you are ready to look under the hood and see how all the magic is done, the Web Services tutorial has all the details.

Where We Have Been

Over the past year, we have explored our way through the Java Jungle together. We started, ironically enough, with how to use Java Web Start to make sure your users are always running the latest version of your software. We explored how to use JavaMail to send email from within your Java applications and how to use SQLJ instead of JDBC to connect to your relational database. We then spent awhile doing some Web programming with servlets and JavaServer Pages (JSPs). We also spent some time on Design Patterns and learned that, even though object-oriented languages like Java are great at code reuse, you get even more benefit from design patterns, which give you design reuse. Then, we delved into how to counteract the Laws of Thermodynamics and software entropy though Refactoring. Armed with a background in design patterns and refactoring, we took a look at the oddly named Extreme Programming methodology of software development. A cross-platform language like Java deserves a cross-platform build tool, but since Sun didn't make one as part of Java itself, we took a look at Ant, the tool the gurus at Apache developed. With all these new concepts that we are learning, it is becoming increasingly more important for developers to be able to communicate at an abstract level, so we spent some time with UML (Unified Modeling Language) and learned how a picture can be worth a thousand lines of code. Next, we examined how you can use JBoss as a free alternative to costly application server.

As I like to say, "Java Journal is not my column; it is your column." What do I mean by that? Well, it's simple. I let you, the reader, help select my topics. So drop me an email at This email address is being protected from spambots. You need JavaScript enabled to view it. and let me know what you would like to see next. Is it something cool you saw at Java One that you think everybody should know about? Or is there a Java technology that you have always wanted to learn? Or maybe there's some Java technology that we have already covered in a previous Java Journal that you would like more or updated information on?

Finally, I would like to say thanks for all the suggestions and feedback you've provided over the last year. You have been critical in making this column a success. I would also like to thank my wife, Kimberly Floyd, for putting up with all the late nights and my editor, Victoria Mack, for her superb wordsmithing. I look forward to being your guide through the Java Jungle for another year.

Michael J. Floyd is an extreme programmer and the Software Engineering Technical Lead for DivXNetworks. He is also a consultant for San Diego State University and can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it..

Michael Floyd

Michael J. Floyd is the Vice President of Engineering for DivX, Inc.

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: