Developing RESTful Services in Java

Transcription

1 Developing RESTful Services in Java Version 1.1 Instructor s Guide

2 Overview We begin this course, as we do all our Java web services courses these days, with a twochapter overview of web services and the Java APIs for building them. For this course, which then starts to focus on JAX-RS, this means a lot of the intro material is about JAX- WS and students may or may not feel that they have use for it. But it seems worth the while to get a good lay of the land that puts JAX-RS in the context of Java EE 6 and the related WS technologies in that platform. And, this may be fair or unfair, but REST seems to have defined itself so much as the not-soap option that, at any rate, explaining JAX- RS as a simpler approach by contrast to JAX-WS does seem to work. After this high-level view, the course drops to ground to explain first JAXB and then JAX- RS, somewhat meticulously and with many examples that are meant to illustrate and prove out most of the likely techniques. With JAX-RS in particular, we ve included a lot of these research-style examples, such as the Basic application that functions almost as a test suite for JAX-RS, trying one of each parameter type, HTTP method, path option, etc. These should give a nice clear view of the framework s capabilities, and give students the sense that they can construct their own RESTful services from scratch. Then, right at the end, the course moves to a more challenging case study application: it uses a relational database, implements a consistent CRUD pattern using parameterized interfaces and classes, implements also a parameterized entity provider, experiments with JAX-RS s quite limited support for dependency injection, and finally shows how to develop support for List<T> entities. Timeline Day 1 2½ hours Module 1, Chapter 1 3 hours Module 1, Chapter 2 3 hours (spans days) Module 2, Chapter 1 Day 2 2 hours Module 3, Chapter 1 2 hours Module 3, Chapter 2 2 hours (spans days) Module 3, Chapter 3 Day 3 2½ hours Module 3, Chapter 4 2 hours Module 3, Chapter 5

3 Teaching Notes I hope that the coursebook is sufficiently clear and detailed, and so the following notes just capture a few ideas about how to approach a given topic, additional concepts to add to your lectures and discussions, and any surprises you might encounter. Module 1 Almost all of this course s exercises are in JAXB or JAX-RS. But in this overview module there are JAX-WS examples. These are more affected by the choice of Tomcat as the target server, because in their usual forms they rely on JSR-109 metadata, which Tomcat doesn t support. So these are bent around to use the JAX-WS reference implementation s own front-controller servlet and metadata vocabulary. Module 3, Chapter 4 Examples/Ellipsoid/Step4 can be tested either at its deployed URL or right where the form.html file sits though note that the latter technique will not work on Firefox. IE is fine, and both browsers work (as any browser ought to) with the deployed application. If you open the file directly in FF, it sees the request from the local file to the deployed application as cross-site, and that triggers an initial OPTIONS request to gain access. Jersey and FF fail to shake hands at that point, and the Ajax request fails. Module 3, Chapter 5 Regarding the use in JAX-RS: more precisely, these annotations are respected on application classes, and on root resources and providers whose lifecycle is once-per-request. No singletons, and no non-root resource classes. Also, it might be worth noting that, if you get context injection wrong, most often it fails quietly. It would be nice if JAX-RS warned you that a given type was not injectable, but instead it just pretends you didn t annotate it There is a final, third step to the case study application, in Examples/Billing/Step3. It adds getall methods for each entity, which involves defining inner classes that are lists of the entity type so that they can be used as return-type entities. If there s extra time this is worth a look.

4 Additional Topics Some suggestions for discussion if you have extra time or anyone expresses interest: WADL: note that Jersey will provide a WADL descriptor in response to an OPTIONS request. You might give this a try and discuss the possibilities, contrast with WSDL, etc. JSF managed beans and EJB stateless sessions as root resource classes. Client development: since JAX-RS doesn t provide any standard client programming model, interesting options include Jersey s client API and JAX-WS.

5 Revision History Version 1.1 is the initial revision of the course. It borrows its first two modules from Course 561. Troubleshooting If you run into any trouble with code exercises, the first and best thing to do is to doublecheck that the classroom machines have been set up precisely according to the course setup guide. Especially, the wrong version of a tool can cause significant problems; don t wander off-book in this way unless absolutely sure you can support the software that you prefer and that we haven t tested. Check environment variable settings carefully, too; these are the cause of a great many classroom glitches. Errata There are no errata for the course at this time. Feedback We very much appreciate whatever feedback we can get on our courseware especially from the instructor s perspective. Naturally, the more specific, the better, and we strongly encourage you to make notes on issues you may encounter in the classroom, whether they re typos, missing files, or suggestions for clearer language to explain a concept. We can t guarantee that we ll act on every suggestion, but we re aggressive about stamping out problems and try to be highly responsive. Hopefully this means that when you give us good feedback, you get a better course the next time you need to teach it. Please direct all courseware feedback to Will Provost Capstone Courseware mailto:provost@capcourse.com For anyone who s interested, we have a very informal defect-tracking system, based in Excel spreadsheets with columns to capture defect location, nature, status, and author feedback. Ultimately, feedback goes into these sheets, so if you want a template, we ll be happy to provide one, to facilitate the reporting process.