| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 |
<!-- |
| 3 |
|
| 4 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
| 5 |
|
| 6 |
Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved. |
| 7 |
|
| 8 |
The contents of this file are subject to the terms of either the GNU |
| 9 |
General Public License Version 2 only ("GPL") or the Common Development |
| 10 |
and Distribution License("CDDL") (collectively, the "License"). You |
| 11 |
may not use this file except in compliance with the License. You can |
| 12 |
obtain a copy of the License at |
| 13 |
http://glassfish.java.net/public/CDDL+GPL_1_1.html |
| 14 |
or packager/legal/LICENSE.txt. See the License for the specific |
| 15 |
language governing permissions and limitations under the License. |
| 16 |
|
| 17 |
When distributing the software, include this License Header Notice in each |
| 18 |
file and include the License file at packager/legal/LICENSE.txt. |
| 19 |
|
| 20 |
GPL Classpath Exception: |
| 21 |
Oracle designates this particular file as subject to the "Classpath" |
| 22 |
exception as provided by Oracle in the GPL Version 2 section of the License |
| 23 |
file that accompanied this code. |
| 24 |
|
| 25 |
Modifications: |
| 26 |
If applicable, add the following below the License Header, with the fields |
| 27 |
enclosed by brackets [] replaced by your own identifying information: |
| 28 |
"Portions Copyright [year] [name of copyright owner]" |
| 29 |
|
| 30 |
Contributor(s): |
| 31 |
If you wish your version of this file to be governed by only the CDDL or |
| 32 |
only the GPL Version 2, indicate your decision by adding "[Contributor] |
| 33 |
elects to include this software in this distribution under the [CDDL or GPL |
| 34 |
Version 2] license." If you don't indicate a single choice of license, a |
| 35 |
recipient has the option to distribute your version of this file under |
| 36 |
either the CDDL, the GPL Version 2 or to extend the choice of license to |
| 37 |
its licensees as provided above. However, if you add GPL Version 2 code |
| 38 |
and therefore, elected the GPL Version 2 license, then the option applies |
| 39 |
only if the new code is made subject to such option by the copyright |
| 40 |
holder. |
| 41 |
|
| 42 |
--> |
| 43 |
<html><head><title>AtomPub Contacts Server Sample</title></head> |
| 44 |
|
| 45 |
|
| 46 |
<body> |
| 47 |
<h1>AtomPub Example Application -- Contacts System</h1> |
| 48 |
|
| 49 |
<p>This module is one of a three part set of modules that contain an example |
| 50 |
application using the jersey-atom-abdera module to send and receive data |
| 51 |
encapsulated in Atom Publishing Protocol feeds and entries. The sample |
| 52 |
application itself is inspired by the Google Contacts Data API |
| 53 |
<a href="https://developers.google.com/google-apps/contacts/v3/">https://developers.google.com/google-apps/contacts/v3/</a>, with some additional functionality |
| 54 |
to illustrate alternative techniques. |
| 55 |
</p> |
| 56 |
|
| 57 |
<h2>Introduction</h2> |
| 58 |
<p>The separation of functionality into three modules allows a common set of |
| 59 |
JavaBean "model" classes to be shared by the client and server modules. |
| 60 |
</p> |
| 61 |
|
| 62 |
<h3>atompub-contacts-models module</h3> |
| 63 |
<p> |
| 64 |
This module contains JavaBean classes for the two types of application data |
| 65 |
that can be transmitted via this web service -- User represents a system user, |
| 66 |
and Contact represents one of potentially many contacts associated with that |
| 67 |
user. The User class contains JAXB annotations, so we can leverage the fact |
| 68 |
that JAX-RS based applications can automatically serialize and deserialize |
| 69 |
instances of such a class, with no need to provide MessageBodyReader or |
| 70 |
MessageBodyWriter providers itself. |
| 71 |
</p> |
| 72 |
|
| 73 |
<h3>atompub-contacts-server module</h3> |
| 74 |
<p> |
| 75 |
This module contains a Jersey based server that implements the contacts API. |
| 76 |
To simplify setup, the "database" behind this service is hashmaps of |
| 77 |
JavaBeans (so it goes away when the service is stopped). It implements two |
| 78 |
top-level resources -- "/users" returns an Atom feed of all users defined |
| 79 |
in the database, while "/contacts/{username}" returns an Atom feed of all |
| 80 |
contacts defined for the specified user. |
| 81 |
</p> |
| 82 |
<p> |
| 83 |
The server implementation uses a Jersey filter to implement authentication |
| 84 |
and authorization checks. Every client request must specify a valid username/ |
| 85 |
password combination (<b>the database is initialized with a user named |
| 86 |
"admin" and password "password"</b>). The administrative user can add, update, |
| 87 |
and delete other users, as well as manage the contacts for any user. All |
| 88 |
other users can only manage their own contact lists. |
| 89 |
</p> |
| 90 |
<p> |
| 91 |
The server illustrates two different techniques for embedding application |
| 92 |
data in Atom feeds and entries: |
| 93 |
<ul> |
| 94 |
<li> |
| 95 |
Contact data is sent and received by using a custom XML namespace, |
| 96 |
and embedding the various data elements as extension elements in an |
| 97 |
Atom entry. This is the same technique that Google Contacts Data API |
| 98 |
uses for this purpose. |
| 99 |
</li> |
| 100 |
<li> |
| 101 |
User data is sent and received by embedding a custom XML representation |
| 102 |
inside the <content> element of an Atom entry. The ContentHelper |
| 103 |
class (from jersey-atom-abdera) is utilized to serialize and deserialize |
| 104 |
the User instances, using the same providers (built in, since this class |
| 105 |
has JAXB annotations) that would be used if you sent or received the |
| 106 |
User instance as an entity of a JAX-RS request or response. |
| 107 |
</li> |
| 108 |
</ul> |
| 109 |
</p> |
| 110 |
<p> |
| 111 |
This module has a dependency on the "atompub-contacts-models" module for |
| 112 |
definitions of the Contact and User classes representing the application data |
| 113 |
that can be transported. |
| 114 |
</p> |
| 115 |
<h3>atompub-contacts-client module</h3> |
| 116 |
<p> |
| 117 |
While you can write a client application to communicate with this server in |
| 118 |
any language you like (including Java), a Java client application has the |
| 119 |
option to use the ContactsClient class from this module as a proxy for the |
| 120 |
remote web service. This allows your application development efforts to |
| 121 |
focus on the business logic of your application, rather than the low level |
| 122 |
details of formatting a proper Atom message, and dealing with low level |
| 123 |
HTTP communication. |
| 124 |
</p> |
| 125 |
<p> |
| 126 |
This module also has a dependency on the "atompub-contacts-models" module |
| 127 |
for definitions of the Contact and User classes (same dependency as the |
| 128 |
server, so that these classes are guaranteed to be defined identically |
| 129 |
at both ends). |
| 130 |
</p> |
| 131 |
|
| 132 |
|
| 133 |
<h3>Running the example</h3> |
| 134 |
<p>You can start the server by issuing |
| 135 |
<pre> |
| 136 |
mvn clean compile exec:java |
| 137 |
</pre> |
| 138 |
from <code>atompub-contacts-server</code> directory. |
| 139 |
|
| 140 |
Then at <a href="http://localhost:9998/users">http://localhost:9998/users</a> you can see an initial list of users |
| 141 |
as an Atom feed, after you have logged in entering a user name of "admin" and a password of "password" in the dialog box. |
| 142 |
|
| 143 |
<p>Then you can try to the client with |
| 144 |
<pre> |
| 145 |
cd ../atompub-contacts-client |
| 146 |
mvn clean compile exec:java |
| 147 |
</pre> |
| 148 |
|
| 149 |
The client should populate data on a new user. You can now check <a href="http://localhost:9998/users">http://localhost:9998/users</a> |
| 150 |
again to see the new user. |
| 151 |
|
| 152 |
</body></html> |
| 153 |
|