The Usergrid project is now open source and in the Apache incubation phase.
**[updated post available, the link can be found at the bottom after the project descriptions.]**
Setup environment for Usergrid:
Requirements
JDK 1.6: (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
Maven (http://maven.apache.org/): Download and install Maven using the instructions on the Apache Maven website
There are a few ways you can download the source from https://github.com/usergrid/usergrid/
1) Click on 'Download ZIP' or Clone the source and follow the instructions on the site to build it.
The second approach is recommended if you want to keep up to date with the latest code and/or want to contribute to the project.
At a high level this it what the project structure looks like:
If we go into the SDK folder we can see the SDKs (software development kits) available for Usergrid.
The stack contains the main project. The structure of the stack is as follows:
Here is a brief description of the projects from the readme files in the relevant folders.
Build-tools: Holds key configuration files for build plugins (Contains
resources like the cassandra.yaml).
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 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 . 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.
Query-Validator: This test package verifies that the Usergrid REST API returns results and does paging and limits in a style similar to that of SqlLite.
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.
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. 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
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.
Getting started:
Once you have the source downloaded (downloaded/cloned/forked) you can to the the stack folder and run the Maven command:
(you need to have your java path, maven path and maven repository setup for the command to be successful)
This will download the required dependencies to the Maven repository which are needed to build the Usergrid project.
Once that is done, we will go into the launcher project (see the description of launcher project above) and run that jar file with the command:
[Since the Usergrid source has been updated please switch to http://malakablogs.blogspot.com/2015/06/running-usergrid-improved-version-with.html and continue reading.]
When this jar file runs, what happens is that an instance of the Grizzly server is made inside the target folder. This is so that users can host Usergrid instantly without the need to set up servers.
It gets better, users do not even have to setup the Cassendra back-end as an instance of that will be made as well for you as you will see below:
(If however after you have got the hand-on of Usergrid you want to setup your own servers and Cassendra instances refer the documents at: http://usergrid.incubator.apache.org/ )
When the jar file is run you will see the following Graphical User Interface (GUI):
As you can see 'Start Database With Server' is already checked - this creates an instance of the Grizzly server onto which Usergrid will be deployed.
'Initialize Database on Start' will create an instance of the Cassendra back-end for you to play around as well. (Keep in mind however that unlike a proper instance, this stops when you stop the GUI above).
The 'Console URL' is by default pointer to http://apigee.github.io/usergrid-portal/. You can go ahead and use that. However later on you can host the 'Portal' web project (see project structure) in your own server and point to that (e.g.: http://localhost/usergrid-portal/).
Go ahead and press the Play button. The light will change color from red to orange to green. Green means that the setup was successful and you can now use the system. 
You now have the Usergrid console to play around and learn ! Don't forget to have fun doing it !
Regards,
Malaka
No comments:
Post a Comment