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.