Debian Codegraph @

samples/atompub-contacts/atompub-contacts-server/README.html

raw
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 &lt;content&gt; 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