RESTful Java with JAX-RS 2.0, 2nd Edition

Preface

Author’s Note

The bulk of my career has been spent working with and implementing distributed middleware. In the mid-’90s I worked for the parent company of Open Environment Corporation working on DCE tools. Later on, I worked for Iona, developing its next-generation CORBA ORB. Currently, I work for the JBoss division of Red Hat, which is entrenched in Java middleware, specifically Java EE. So, you could say that I have a pretty rich perspective when it comes to middleware.

I must tell you that I was originally very skeptical of REST as a way of writing SOA applications. It seemed way too simple and shortsighted, so I sort of blew it off for a while. One day, though, back in mid-2007, I ran into my old Iona boss and mentor, Steve Vinoski, while grabbing a sandwich at D’Angelo in Westford, Massachusetts, near Red Hat’s offices. We ended up sitting down, having lunch, and talking for hours. The first shocker for me was that Steve had left Iona to go work for a start-up. The second was when he said, “Bill, I’ve abandoned CORBA and WS-* for REST.” For those of you who don’t know Steve, he contributed heavily to the CORBA specification, wrote a book on the subject (which is basically the CORBA bible), and is a giant in the distributed computing field, writing regularly for C++ Report and IEEE. How could the guy I looked up to and who was responsible for my foundation in distributed computing abandon CORBA, WS-*, and the distributed framework landscape he was instrumental in creating? I felt a little betrayed and very unnerved. (OK, maybe I’m exaggerating a little…)

We ended up arguing for a few hours about which was better—WS-*/CORBA or REST. This conversation spilled into many other lengthy email messages, with me trying to promote WS-* and him defending REST. The funniest thing to me was that as I researched REST more and more I found that my arguments with Steve were just another endless replay of debates that had been raging across the blogosphere for years. They are still raging to this day.

It took months for me to change my mind and embrace REST. You would figure that my distributed computing background was an asset, but it was not. DCE, CORBA, WS-*, and Java EE were all baggage. All were an invisible barrier for me to accept REST as a viable (and better) alternative for writing SOA applications. I think that’s what I liked most about REST. It required me to rethink and reformulate the foundation of my distributed computing knowledge. Hopefully your journey isn’t as difficult as mine and you will be a little less stubborn and more open-minded than I was.

Who Should Read This Book

This book teaches you how to design and develop distributed web services in Java using RESTful architectural principles on top of the HTTP protocol. It is mostly a comprehensive reference guide on the JAX-RS specification, which is a JCP standardized annotation framework for writing RESTful web services in Java.

While this book does go into many of the fundamentals of REST, it does not cover them all and focuses more on implementation rather than theory. You can satisfy your craving for more RESTful theory by obtaining RESTful Web Services by Leonard Richardson and Sam Ruby (O’Reilly). If you are familiar with writing Java EE applications, you will be very comfortable reading this book. If you are not, you will be at a disadvantage, but some experience with web application development, HTTP, and XML is a huge plus. Before reading this book, you should also be fairly fluent in the Java language and specifically know how to use and apply Java annotations. If you are unfamiliar with the Java language, I recommend Learning Java by Patrick Niemeyer and Jonathan Knudsen (O’Reilly).

How This Book Is Organized

This book is organized into two parts: the technical manuscript, followed by the JAX-RS workbook. The technical manuscript explains what REST and JAX-RS are, how they work, and when to use them. The JAX-RS workbook provides step-by-step instructions for installing, configuring, and running the JAX-RS examples from the manuscript with the JBoss RESTEasy framework, an implementation of JAX-RS.

Part I, REST and the JAX-RS Standard

Part I starts off with a brief introduction to REST and HTTP. It then guides you through the basics of the JAX-RS specification, and then in later chapters shows how you can apply JAX-RS to build RESTful web services:

Chapter 1, Introduction to REST

This chapter gives you a brief introduction to REST and HTTP.

Chapter 2, Designing RESTful Services

This chapter walks you through the design of a distributed RESTful interface for an ecommerce order entry system. For the second edition, this chapter has been revised to include a simple client using the new JAX-RS 2.0 Client API.

Chapter 3, Your First JAX-RS Service

This chapter walks you through the development of a RESTful web service written in Java as a JAX-RS service.

Chapter 4, HTTP Method and URI Matching

This chapter defines how HTTP requests are dispatched in JAX-RS and how you can use the @Path annotation and subresources. For the second edition, I talk about some of the ambiguities of the request matching algorithm.

Chapter 5, JAX-RS Injection

This chapter walks you through various annotations that allow you to extract information from an HTTP request (URI parameters, headers, query parameters, form data, cookies, matrix parameters, encoding, and defining default values). For the second edition, this chapter has been revised to include the new @BeanParam and ParamConverter features introduced in JAX-RS 2.0.

Chapter 6, JAX-RS Content Handlers

This chapter explains how to marshal HTTP message bodies to and from Java objects using built-in handlers or writing your own custom marshallers.

Chapter 7, Server Responses and Exception Handling

This chapter walks through the JAX-RS Response object and how you use it to return complex responses to your client (ResponseBuilder). It also explains how exception and error handling work in JAX-RS. This chapter has been revised a little bit to talk about the new exception hierarchy that was added in JAX-RS 2.0.

Chapter 8, JAX-RS Client API

This chapter is new to the second edition and describes in detail the new Client API added to JAX-RS 2.0.

Chapter 9, HTTP Content Negotiation

This chapter explains how HTTP content negotiation works, its relationship to JAX-RS, and how you can leverage this within RESTful architectures.

Chapter 10, HATEOAS

This chapter dives into Hypermedia As The Engine Of Application State (HATEOAS) and how it relates to JAX-RS (UriInfo and UriBuilder). This chapter has been revised for the second edition to include additions to the UriBuilder API and the new classes for building links.

Chapter 11, Scaling JAX-RS Applications

This chapter explains how you can increase the performance of your services by leveraging HTTP caching protocols. It also shows you how to manage concurrency conflicts in high-volume sites.

Chapter 12, Filters and Interceptors

This chapter is new to the second edition. It talks about the new filter and interceptor APIs added to JAX-RS 2.0 and how you can use them to write extensions to JAX-RS.

Chapter 13, Asynchronous JAX-RS

This is a new chapter for the second edition. It walks you through the new server- and client-side asynchronous interfaces available in JAX-RS 2.0.

Chapter 14, Deployment and Integration

This chapter explains how you can deploy and integrate your JAX-RS services within Java Enterprise Edition, servlet containers, EJB, Spring, and JPA. It has been revised in the second edition.

Chapter 15, Securing JAX-RS

This chapter walks you through the most popular mechanisms to perform authentication on the Web. It then shows you how to implement secure applications with JAX-RS. It has been revised in the second edition to walk you through configuring client-side SSL and also now includes an introduction to OAuth 2.0. I also talk about JSON Web Signatures and encryption.

Chapter 16, Alternative Java Clients

This chapter talks about alternative Java clients you can use to communicate with RESTful services (java.net.URL, Apache HTTP Client, and RESTEasy Proxy).

Part II, JAX-RS Workbook

The JAX-RS workbook shows you how to execute examples from chapters in the book that include at least one significant example. You’ll want to read the introduction to the workbook to set up RESTEasy and configure it for the examples. After that, just go to the workbook chapter that matches the chapter you’re reading. 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 with RESTEasy.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

This icon signifies a tip, suggestion, or general note.

Warning

This icon indicates a warning or caution.

Using Code Examples

Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/oreillymedia/restful_java_jax-rs_2_0.

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: "RESTful Java with JAX-RS 2.0, Second Edition by Bill Burke. Copyright 2014 Bill Burke, 978-1-449-36134-1.”

If you feel your use of code examples falls outside fair use or the permission given here, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of plans and pricing for enterprise, government, education, and individuals.

Members have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and hundreds more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://oreil.ly/restful_java_jax-rs_2_0.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

First, I’d like to thank Steve Vinoski for introducing me to REST. Without our conversations and arguments, I would never have written this book. Next, I’d like to thank Marek Potociar and Santiago Pericas-Geertsen, the JAX-RS 2.0 spec leads. They ran an excellent expert group and put up with a lot of crap from me. I’d like to thank Sergey Beryozkin for contributing the Apache CXF section. It is cool when competitors can be on good terms with each other. Fernando Nasser, Jeff Mesnil, and Michael Musgrove were instrumental in reviewing this book and provided a lot of great feedback. Subbu Allaraju helped tremendously in making sure my understanding and explanation of RESTful theory was correct. By the way, I strongly suggest you check out his blog. Heiko Braun helped on the first few chapters as far as reviewing goes. I’d also like to thank the contributors to the RESTEasy project, specifically Ron Sigal, Wei Nan Li, Solomon Duskis, Justin Edelson, Ryan McDonough, Attila Kiraly, and Michael Brackx. Without them, RESTEasy wouldn’t be where it is. Finally, I’d like to thank Meghan Blanchette and the O’Reilly team for helping make this book a reality.