index.xtp

RESIN 3.2 最新源码

public class FlickrResponse {
  @XmlAttribute public String stat = "ok";
  @XmlAnyElement(lax=true) public FlickrPayload payload;

  public String toString()
  {
    return "FlickrResponse[stat=" + stat + ", payload=" + payload + "]";
  }
}
</example>
<p>
Notice the @XmlRootElement annotation on the class.  This annotation sets the
the element name to <code>rsp</code>.  Next, there is a status field which
is an attribute in the element.  JAXB simply uses the field name in this case
to set the attribute when the @XmlAttribute annotation is present.  Finally,
the payload is annotated with @XmlAnyElement.  This annotation is
necessary since <code>FlickrPayload</code> is an interface.  @XmlAnyElement
allows the marshalling of an interface or abstract class.  The <code>lax</code>
property allows JAXB to use known classes to unmarshal an interface or
class.  How to let JAXB know about such class is covered at the next
section.
</p>
<p>
FlickrPayload is an empty interface, used only for typing in this example.
FlickrUser implements FlickrPayload and is the response payload used by the 
<code>flickr.people.findByEmail</code> and
<code>flickr.people.findByUsername</code> methods.  The XML response from
the section "REST Bindings" above corresponds to this class.
</p>
<example title="FlickrUser.java">
package example.data;

import javax.xml.bind.annotation.*;

@XmlRootElement(name="user")
public class FlickrUser implements FlickrPayload {
  @XmlAttribute public String nsid;
  @XmlElement public String username;

  public String toString()
  {
    return "FlickrUser[nsid=" + nsid + ", username=" + username + "]";
  }
}
</example>
<p>
The <code>FlickrUser</code> class is somewhat simpler than
the <code>FlickrResponse</code> example above in that it only has a root
element, <code>&lt;user></code>, a single
attribute, <code>nsid</code>, and a single child element, 
<code>&lt;username></code>.  The attribute and child element here are both
simply strings.  <code>FlickrPhotos</code> is a more complex class with
a variable number of child elements.
</p>
<example title="FlickrPhotos.java">
package example.data;

import java.util.*;
import javax.xml.bind.annotation.*;

@XmlRootElement(name="photos")
public class FlickrPhotos implements FlickrPayload {
  @XmlAttribute public int page;
  @XmlAttribute public int pages;
  @XmlAttribute public int perpage;
  @XmlAttribute public int total;

  @XmlElement(name="photo") public List&lt;Photo> photos = new ArrayList&lt;Photo>();

  public static class Photo {
    @XmlAttribute public String id;
    @XmlAttribute public String owner;
    @XmlAttribute public String secret;
    @XmlAttribute public int server;
    @XmlAttribute public String title;
    @XmlAttribute public int ispublic;
    @XmlAttribute public int isfriend;
    @XmlAttribute public int isfamily;

    public String toString()
    {
      return "Photo[id=" + id + ", " +
                   "owner=" + owner + ", " +
                   "secret=" + secret + ", " +
                   "server=" + server + ", " +
                   "title=" + title + ", " +
                   "ispublic=" + ispublic + ", " +
                   "isfriend =" + isfriend + ", " +
                   "isfamily=" + isfamily + "]";
    }
  }

  public String toString()
  {
    StringBuilder sb = new StringBuilder();
    sb.append("FlickrPhotos[page=" + page + ", ");
    sb.append(             "pages=" + pages + ", ");
    sb.append(             "perpage=" + perpage + ", ");
    sb.append(             "total=" + total + ", ");
    sb.append(             "photos=(");

    for (Photo photo : photos) {
      sb.append(photo.toString());
      sb.append(' ');
    }

    sb.append(")]");

    return sb.toString();
  }
}
</example>
<p>
Here there are four attributes of the root element and a list of child
elements representing the photos.  Each photo has a set of attributes
as well.  By default, JAXB serializes lists as unadorned sequences of
elements.  For example, a FlickrPhotos object with two photos might have
the following XML:
</p>
<example title="">
&lt;rsp stat="ok">
  &lt;photos total="2" perpage="10" pages="1" page="1">
    &lt;photo isfamily="0" isfriend="0" ispublic="1" title="Our wedding"
           server="2" secret="x123456" owner="12345678901@N01" id="3041"/>

    &lt;photo isfamily="0" isfriend="1" ispublic="0" title="Best friends"
           server="1" secret="y123456" owner="12345678901@N01" id="3042"/>
  &lt;/photos>
&lt;/rsp>
</example>
<p>
The remaining payload classes, <code>FlickrError</code>, 
<code>FlickrGroups</code>, and <code>FlickrPerson</code>, are annotated
similarly.
</p>
</s1>

<s1 title="Client configuration">

<p>
A REST client is configured using the &lt;web-service-client> tag, just like
with SOAP and Hessian clients.  The only difference is that the URL must
use the "rest:" prefix.  The Resin SOA connects to the service using the
given URL and places a proxy instance into JNDI.  Any clients may access
the service then by doing a JNDI lookup, then calling methods on the returned
object.
</p>

<example title="resin-web.xml">
&lt;web-service-client jndi-name="rest/flickr">
  &lt;url>rest:${webApp.url}/flickr/rest/&lt;/url>
  &lt;interface>example.FlickrAPI&lt;/interface>
  &lt;jaxb-package>example.data&lt;/jaxb-package>
&lt;/web-service-client>
</example>

<p>
Notice the &lt;jaxb-package> tag.  In order for JAXB to marshal and
unmarshal objects, it must know all the classes it might encounter.
There are two ways to inform JAXB about the classes: either by a list of
package names or an explicit list of classes.  In this example, all of the
classes that JAXB will use are in the package <code>example.data</code>,
so the &lt;jaxb-package> tag is the easiest way.  The &lt;jaxb-package>
tag may be used multiple times to add classes from several packages.
(It is also possible to use multiple &lt;jaxb-class> tags to list the
classes explicitly.)
</p>

<p>
Simply listing a &lt;jaxb-package> may not be appropriate in all cases.  
In fact in this example, notice that FlickrPayload is simply an empty
interface and is not JAXB-annotated.  Thus JAXB should load only those
classes in the <code>example.data</code> package that are annotated. 
The JAXB standard specifies that a file named "jaxb.index" will be read 
by JAXB whenever a package is given.  This file should be placed in the
package directory.  The list of classes should be relative to the package,
without a .java or .class suffix, and should be separated by newlines.
For this example, the jaxb.index is the following:
</p>

<example title="jaxb.index">
FlickrError
FlickrGroups
FlickrPerson
FlickrPhotos
FlickrResponse
FlickrUser
</example>
</s1>

<s1 title="Testing the interface">
<p>
An example implementation of the service is provided here for testing
purposes only.  It returns sample data upon receiving REST requests and 
does not actually store or display images.  Because setting up a REST
service is covered in another tutorial, only the client side of the REST
connection is explained fully here.
</p>

<p>
The demonstration JSP simply looks up the proxy interface in JNDI, then
calls the methods with sample queries.  The calls and their results are
printed.
</p>

<p>
<i>flickr is a trademark of Yahoo! Inc.</i>
</p>
</s1>

  </body>
</document>