CS 639 - class 19

Note fix to orderService’s web.xml: remove extra <servlet>. This is fixed at $cs639/orderService.

hw3 due, handout: Jersey Client Code

 

Last time: intro to Java EE software: we’re using servlets, JAX-RS, JAXB

JAXB, for Java POJOs to/from XML, is in Java SE v 1.6.

Note that JAX-WS, another package of Java EE, handles SOAP WS’s, and uses JAXB.

 

More on REST/HTTP:

·         uses HTTP verbs for its actions (as detailed in big table)

·         uses HTTP URLs/URIs for its own resources

·         uses certain HTTP headers: Content-Type, Accept, Location

·         uses HTTP/MIME (predates HTTP) types for content: text/xml, etc. , now called Media Types

·         uses HTTP success/error codes: 200, 201, ... 404, 405, 500, see index, pg. 415

 

Obviously you need to be sure of all these aspects of HTTP to deal intelligently with REST.

 

PA3: Client code in Java for orderService: get a partner!

Note that clients can be written in Javascript, Ajax, C#, other languages too. Contributions of examples welcome.

 

Last time: firstRest server code (very simple), client testing using wget for GET and POST, very handy.

Shows how little is needed to write a client for REST.  This is a big advantage over SOAP.

 

Now look at Java clients, Test.java and Test2.java, in firstRest.  See handout.

 

 

The handout shows String-to-XML (pretty trivial), DOM-to-XML, POJO-to-XML using message body writers under the covers, and the reverse conversions. 

 

Look over handout code.

Test.java: See access to env var, so same code works on Linux or home PC. Same in Test2.java

 

Test.java: See builder pattern, or “method chain”: each method returns the same type or the next type you want to use, for these long chains.

Also called a “train wreck”.

Note the longer version showing intermediate types, for POST case, as well as the compressed form.

 

Test2.java:

DOM: just create a DOM tree and hand it off to Jersey, and let Jersey send it off as XML and convert the response XML back into a DOM for easy analysis in Java.

 

DOM Wrapped up in ClientResponse: useful to get status, headers from response, as well as the DOM (in the success case).

or not: could use SAX on the return side. Useful if the doc is really big.

 

Pretty easy to work with DOM. Can do pa3 this way.

 

But of course Java programmers love POJOs, so good to know Jersey can work with JAXB to convert XML to/from POJOs.

 

Note that unlike DOM, only very simple XML trees convert to a single POJO.

 

One POJO can have various fields, corresponding to one element having several child elements.

 

The POJO Todo on the handout converts to a very simple XML, in the case of null description:

<todo><id>2</id><summary>get this working</summary></todo>

 

XML has to be this simple to convert back to one POJO: just root+direct children (each with XSD string or other simple type values)

 

So if the XML tree has 2 levels, as the echo message does:

<echo><todo><id>2</id><summary>get this working</summary></todo></echo>

 

 

Then we need two POJOs, one for <echo> having <todo> as a child, plus the <todo> POJO.

 

Look at Echo.java to see its Todo-type field.

 

Picture of <Echo POJO> ---> <Todo POJO>    little object graph for two-level XML

 

orderService: XML on pg. 59. has 4 levels, so lots of POJOs.  But actually the XSD is a better guide to POJO picture than the XML instance. In the XSD, we see that the <milk> can be ..., expressed by a Java enum, so another POJO.

 

case of StAX: not shown on handout.  StAX can compose XML in a file or string, then Jersey can send it as String.  Kind of low level, and not checked for even well-formedness. But better than pa1-type XML generation. Knows enough to quote special characters.

 

Test2.java: see we can use wrapper or not, same as DOM case.

 

Back to Chap. 4.

 

URI Templates

URIs in use in REST map to individual resources. Idea of URI template, like /order/{orderId} on pg. 57.  This is not a JAX-RS, thing. It’s used in .NET too. It’s a REST idea.  The URI template specifies the “path”, and the full URI is created by concatenating the “base URI” and the “path”. For Chap. 4, the base URI (pg. 86) is “http://restbucks.com/”.

 

A real URI for our orderService ends like this:  <BASE_URI>order/123  for order #123, so here we see that orderId = 123.

 

In /order/{orderId}, orderId is called a template parameter or path parameter. It matches against the most text that contains no / characters, so this one picks up all the chars after the last /.

 

Note that curly braces are not allowed in valid URIs, so no quoting capability is needed for this syntax

 

The table on pg. 57 shows how concisely we can describe a REST service with the help of URI Templates

Look at pg. 58 to see protocol.  Add to the POST and its reply a “Content-Type” for application/xml

Note the error codes.  Look at messages and headers.

 

More Complicated URI Templates (relevant to pa3 part on designing an extended orderService)

There is a way to pick up “the rest” of the URI after matching a prefix of it. Or picking up something fitting a regular expression, but we don’t really need these forms.

 

URI Templates can be more complicated:

Example from pa3.html:  /{eventId}/{inviteId}

So if events are id’d by “e001”, etc., and invites by 1, 2, 3,...

an individual invitation could have URI path “/e021/32”

 

There can be constant parts after a parameter, like this:

/customers/{id}/address

 

Or even multiple parameters for text between /s, like this:

/customers/{firstname}-{lastname}

which matches “/customers/bill-burke” for example.

 

This example is from Burke, RESTful Java with JAX-RS.  He has detailed discussion of URI Templates.