Usergrid sub-projects information

This is a small article that uses the readMe files in the stack project of Apache Usergrid so that enthusiasts can get the information from one location without going through the file structure. 

Keep in mind that the files may have been changed by the time you are reading this though.

This will help you get the basic idea. Enjoy !

User- Grid- Stack

The user-grid-stack consists of a parent maven project with the following modules.

Modules:

Built-tools

Holds key configuration files for build plugins (Contains resources like the checkstyle.xml).

 

Config

Runtime config resources of Usergrid system are contained here.

 

Core

This contains the core services for Usergrid system.

Usergrid-core contains the persistence layer [m1] [Mm2] and shared utilities for powering the Usergrid service. The services layer is contained in Usergrid-services and exposes a higher-level API that's used by the Usergrid-rest web services tier.

Launcher

Usergrid Launcher is a graphical server launcher.

The launcher is a simple Java app that provides a GUI for running the server as a desktop app.

 

Mongo emulator

This provides the Mongo emulation layer for the Usergrid system[m3] [Mm4] . This is still experimental and incomplete implementation of Mongo emulation layer so Mongo clients can connect to Usergrid.

There are a number of drivers and tools for talking to Mongo DB, which has a data model that is very similar to that of Usergrid. In order to make it easier for people to get started quickly with Usergrid, it's desirable for them to be able to integrate it very quickly into their existing applications.

The goal here is to support the Mongo native wire protocol and to map enough of the query and CRUD operations so that this can happen.

Rest

This contains the REST web services for Usergrid system (Usergrid REST API Web App).

This installs as a web-app in Tomcat and has not been extensively tested in other web containers.

See Usergrid-standalone for an example of running inside Grizzly.

Services

This contains the Service layer for Usergrid system.

This is where most of the high-level functionality for accessing Usergrid data is performed. It functions as the glue between the REST API as exposed by Jersey and the entity management functionality in Usergrid-core. This is also where security and account management functionality is contained.

The security model of Usergrid is implemented with Apache Shiro: http://shiro.apache.org/

The services model for Usergrid involves converting the REST web service requests into collection queries and routing these to a set of collection handlers.  [m5] [Mm6] This provides a "virtual collection" layer on top of the actual collections that are exposed in the persistence tier.  This makes it possible to:

- implement logic behaviour on top of persistent objects

- enforce object and property visibility

- perform fine-grained permission checks

 

Test-utils

This contains the test utilities for Usergrid system as implied by the name.

 

Tools

This contains the command line tools for Usergrid system as implied by the name.

The Usergrid Tools are a set of Java programs that can be run from a command-line console.

Websocket

This contains the WebSocket API for Usergrid system. It is still an experimental (incomplete) implementation of Websocket API.  Websockets info can be found at http://en.wikipedia.org/wiki/WebSockets

The Websocket API will allow for asynchronous communications with the Usergrid API.

OAuth credentials are put in the query string of the initial GET request since the JavaScript Websocket API provides no mechanism for specifying header contents.

Once a connection is established, there are two mechanisms of usage.

Async Request/Response

The first is to simply access the API the same way as the REST interface provides, except over the open websocket connection. The benefit is there is much less overhead than with the REST API since there is no processing of individual HTTP requests and authentication credentials are checked at the time the websocket is opened as opposed to per-request as is necessary with the stateless REST API.

Subscriptions

The second is to issue subscribe requests against entities and collections and be notified asynchronously as those are updated. Subscriptions against the activity inbox and message queue collections for either users, groups, or the entire application allow connected applications to get real-time updates.

Connecting to an inbox or queue in the websocket URL will automatically start a subscription to that collection. For example, the following websocket URL will listen to a specific user's inbox:

ws://api.usergrid.com:8088/chatapp/users/johndoe/inbox

This is the real-time equivalent of making a regular REST GET request to:

http://api.usergrid.com/chatapp/users/edanuff/inbox

Usergrid listens to websockets on an alternate port than it does standard HTTP requests. Although websockets can coexist on the same ports 80 or 443, Tomcat and other Java servlet containers don't do a particularly great job of handling open async socket connections despite what they claim. For our purposes, we're using a bare metal Netty websocket server that listens on port 8088. This is going to be much more performant that trying to integrate it into Tomcat and allows us to move the websocket servers onto different machines.