RESTful Java with JAX-RS 2.0 (2013)

Part II. JAX-RS Workbook

Chapter 17. Workbook Introduction

Reading a book on a new technology gives you a nice foundation to build on, but you cannot truly understand and appreciate a new technology until you see it in action. The following workbook chapters were designed to be a companion to the main chapters of this book. Their goal is to provide step-by-step instructions for installing, configuring, and running various JAX-RS examples found throughout this book with the RESTEasy framework.

This chapter focuses on downloading and installing RESTEasy and the workbook examples. Following this, each workbook chapter corresponds to a specific chapter in the book. For example, if you are reading Chapter 3 on writing your first JAX-RS service, use Chapter 18 of the workbook to develop and run the examples shown in that chapter with RESTEasy.

This workbook is based on the production release of RESTEasy JAX-RS 3.0.5. I picked RESTEasy as the JAX-RS framework for the workbook for no other reason than I am the project lead for it and I know it backward and forward. That said, I took great care to ensure that you can easily port the examples to other JAX-RS implementations.

Installing RESTEasy and the Examples

The workbook examples are embedded within the RESTEasy distribution so that as future versions of RESTEasy are released, the workbook examples will be updated along with that release. (I discovered that having a separate download for the workbook examples causes various problems—users can get confused about which package to download, and the examples can get out of sync with specific software versions.)

You can download the distribution by following the download links at http://jboss.org/resteasy.

Download the latest RESTEasy JAX-RS distribution (for example, resteasy-jaxrs-3.0.5.Final.zip). Figure 17-1 shows the directory structure of the distribution.

RESTEasy directory structure

Figure 17-1. RESTEasy directory structure

Table 17-1 describes the purpose of the various directories.

Table 17-1. RESTEasy directories

Directory	Description
docs/javadocs	Generated Javadocs for both the JAX-RS APIs and RESTEasy
docs/userguide	Reference guide for RESTEasy in both HTML and PDF format
examples	Top-level directory containing all RESTEasy examples
examples/oreilly-jaxrs-2.0-workbook	Contains workbook example code for each workbook chapter
lib	All the RESTEasy JARs and the third-party libraries they depend on
embedded-lib	Optional JAR files used when you are running RESTEasy in embedded mode
resteasy-jaxrs.war	Sample RESTEasy servlet deployment

Don’t get confused by the other examples/oreilly-workbook directories. These are examples from the previous revision of this book.

For Apache Maven users, RESTEasy also has a Maven repository at http://bit.ly/HCHZm6.

The groupId for all RESTEasy artifacts is org.jboss.resteasy. You can view all available artifacts at http://bit.ly/1esCSDp.

Example Requirements and Structure

The RESTEasy distribution does not have all the software you need to run the examples. You will also need the following components:

§ JDK 6.0 or later. You will, of course, need Java installed on your computer.

§ Maven 3.0.4. Maven is the build system used to compile and run the examples. Later versions of Maven may work, but it is recommended that you use 3.0.4. You can download Maven from http://maven.apache.org.

Code Directory Structure

The EXAMPLE code is organized as a set of directories, one for each exercise (see Figure 17-2). You’ll find the server source code for each example in the src/main/java directory. The servlet configuration for each example lives in the src/main/webapp/WEB-INF directory. The client code that runs the example is in src/test/java.

Code directory structure

Figure 17-2. Code directory structure

To build and run the exercises, you’ll use the Maven build tool. A product object model (POM) is provided in the pom.xml file at the top-level directory of each example. It contains the Maven configuration needed to compile, build, and run the specific example.

Environment Setup

For Maven to work correctly, you will have to make sure the Maven scripts are in your path. Depending on your platform, you’ll have to execute commands like these:

§ Windows:

C:\> set PATH=\maven\bin;%PATH%

§ Unix:

$ export PATH=/home/username/maven/bin:$PATH

In each chapter, you’ll find detailed instructions on how to build, deploy, and run the exercise using Maven.