Before you start

In this tutorial, you'll learn about Web services-related projects, APIs, and specifications, such as Simple Object Access Protocol (SOAP) with Attachments API for Java (SAAJ), SOAP with Attachments (Sw/A), Apache Web Services for Java (WSS4J), and Java API for XML Registries (JAXR) presented in various scenarios and designed to extend the existing BookShop application you started in Part 1.

About this series

Part 1 of this series demonstrated the integration of service-consumer and service-provider Web services into the existing J2EE-based BookShop application on the Apache Geronimo application server. This tutorial, Part 2 of this series, shows you several additional elements that are important when using enterprise Web services in Geronimo: message handlers, attachments, security, custom exceptions, and registry access.

Back to top

About this tutorial

The current BookShop application developed in Part 1 allows customers to search for books based on categories using a Web interface and a Web services interface. Search results include the book title, author names, ISBN, description, and price in US dollars. Now learn how to extend the BookShop Web service by incorporating message handlers, binary attachment support, message-level security, and UDDI registry access and logging. The examples provide a brief discussion of these new features as well as their implementations and configurations in Geronimo.

The tutorial is structured as follows:

• Extend BookShop with JAX-RPC message handlers shows how you can add SOAP message-logging capabilities and transaction management to the BookShop application using message handlers. Message handlers can intercept SOAP messages at two points: before they are processed and after they are processed by the BookShop business logic. They provide powerful message-processing capabilities and, thus, allow SOAP message security, logging, or transaction management, among other functions.
• Add attachments to the BookShop Web service demonstrates adding attachments as part of the SOAP response message sent to the BookShop client application. This section introduces SAAJ to the mechanisms explained in the Sw/A specification. You'll see two approaches demonstrated for including attachments using SOAP messages.
• Secure the BookShop Web services explains how the WS-Security standard is applied to secure the SOAP messages sent and received by the BookShop application. You'll get an introduction to user authentication to achieve access control, digital signatures for message integrity, and encryption and decryption mechanisms to ensure message confidentiality for SOAP messages.
• Deliver custom exceptions describes how custom exceptions, or checked exceptions, enhance the usability of the BookShop Web services and provide a powerful mechanism to support the communication between BookShop clients and the BookShop application hosted on Geronimo.
• Access a business registry from the BookShop outlines how the BookShop Web services are supported by the JAXR specification and its Apache Scout-based implementation, which are shipped with Geronimo. Learn how to publish a Web service and how to find Web services using Geronimo's JAXR client API.

Back to top

Prerequisites

Geronimo developers and Java developers with prior experience in J2EE platform development, this tutorial is for you! General knowledge of distributed programming concepts and the role of Web services in this context is an added plus, but not required.

Back to top

System requirements

To run the code samples in this tutorial, you first need to download and install the following applications and libraries (see Resources for links to these downloads):

• Java 2 Platform, Standard Edition (J2SE) 1.4.2_08 SDK
• Apache Geronimo M5
• Apache Ant
• Apache Axis 1.2.1
• Sun's Java Web Services Developer Pack (Java WSDP)
• Eclipse Development Platform (optional)

Referring to Table 1, make sure that the following environmental variables are set in your shell:

After installing and setting up these applications, you need to set up a few more things:

• Create a folder in %GERONIMO_HOME%/repository/bouncycastle/jars, and copy the bcprov-jdk13-128.jar from the %PROJECT_HOME%/lib distribution into this folder. Edit the %PROJECT_HOME%/meta/ear/geronimo-application.xml, and include the following dependency to the list: <dependency><uri>wss4j/jars/bcprov-jdk13-128.jar</uri></dependency>.
• Create a folder in %GERONIMO_HOME%/repository/wss4j/jars, and copy the opensaml-1.0.1.jar, the wss4j.jar, and the xmlsec-1.2.1.jar from the WSS4J distribution into this folder.
• Edit the project build.xml, and set the correct paths for your Geronimo and your Axis installations. Also, look into %GERONIMO_HOME%/repository/tranql/rars, and adjust this file name in the build.xml file accordingly.

In this tutorial, you have the opportunity to choose the BookShop database engine in either Apache Derby or MySQL (note that Derby ships with Geronimo). The following steps provide configuration details for both databases:

• Edit the project build.xml, and set the database property to the database of your choice.

Derby-specific installation:

• Unzip derby.zip found at %PROJECT_HOME%/etc into the %GERONIMO_HOME%/var/derby directory.

MySQL-specific installation:

• Download MySQL and MySQL Connector/J driver.
• Create a database called bookshopdb in MySQL, and then run the supplied database script (etc/bookshopdb.sql) to create and populate the required relational database tables.
• Create a folder in %GERONIMO_HOME%/repository/mysql/jars, and copy the mysql-connector-java-your_version_number.jar driver to this directory.

1 of 10 | Next

Comments

Back to top

Table of contents

• Before you start
• Extend BookShop with JAX-RPC message handlers
• Add attachments to the BookShop Web service
• Secure the BookShop Web services
• Deliver custom exceptions
• Access a business registry from the BookShop
• Summary
• Download
• Resources
• About the author

---

1 of 10 | Next

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
• Buy: Rational Application Developer

Dig deeper into Open source on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.