# AtomPub Example Application -- Contacts System

This module is one of a three part set of modules that contain an example application using the jersey-atom-abdera module to send and receive data encapsulated in Atom Publishing Protocol feeds and entries. The sample application itself is inspired by the Google Contacts Data API https://developers.google.com/google-apps/contacts/v3/, with some additional functionality to illustrate alternative techniques.

## Introduction

The separation of functionality into three modules allows a common set of JavaBean "model" classes to be shared by the client and server modules.

### atompub-contacts-models module

This module contains JavaBean classes for the two types of application data that can be transmitted via this web service -- User represents a system user, and Contact represents one of potentially many contacts associated with that user. The User class contains JAXB annotations, so we can leverage the fact that JAX-RS based applications can automatically serialize and deserialize instances of such a class, with no need to provide MessageBodyReader or MessageBodyWriter providers itself.

### atompub-contacts-server module

This module contains a Jersey based server that implements the contacts API. To simplify setup, the "database" behind this service is hashmaps of JavaBeans (so it goes away when the service is stopped). It implements two top-level resources -- "/users" returns an Atom feed of all users defined in the database, while "/contacts/{username}" returns an Atom feed of all contacts defined for the specified user.

The server implementation uses a Jersey filter to implement authentication and authorization checks. Every client request must specify a valid username/ password combination (the database is initialized with a user named "admin" and password "password"). The administrative user can add, update, and delete other users, as well as manage the contacts for any user. All other users can only manage their own contact lists.

The server illustrates two different techniques for embedding application data in Atom feeds and entries:

- Contact data is sent and received by using a custom XML namespace, and embedding the various data elements as extension elements in an Atom entry. This is the same technique that Google Contacts Data API uses for this purpose.
- User data is sent and received by embedding a custom XML representation inside the <content> element of an Atom entry. The ContentHelper class (from jersey-atom-abdera) is utilized to serialize and deserialize the User instances, using the same providers (built in, since this class has JAXB annotations) that would be used if you sent or received the User instance as an entity of a JAX-RS request or response.

This module has a dependency on the "atompub-contacts-models" module for definitions of the Contact and User classes representing the application data that can be transported.

### atompub-contacts-client module

While you can write a client application to communicate with this server in any language you like (including Java), a Java client application has the option to use the ContactsClient class from this module as a proxy for the remote web service. This allows your application development efforts to focus on the business logic of your application, rather than the low level details of formatting a proper Atom message, and dealing with low level HTTP communication.

This module also has a dependency on the "atompub-contacts-models" module for definitions of the Contact and User classes (same dependency as the server, so that these classes are guaranteed to be defined identically at both ends).

### Running the example

You can start the server by issuing

           mvn clean compile exec:java

from `atompub-contacts-server` directory. Then at http://localhost:9998/users you can see an initial list of users as an Atom feed, after you have logged in entering a user name of "admin" and a password of "password" in the dialog box.

Then you can try to the client with

            cd ../atompub-contacts-client
            mvn clean compile exec:java

The client should populate data on a new user. You can now check http://localhost:9998/users again to see the new user.