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.
