Dave Johnson on open web technologies, social software and software development
If you're interested in trying the not-yet-released Apache Usergrid 2 you might want to checkout my Usergrid-Vagrant project on GitHub. I just updated the project to support Usergrid 2, using the latest code from the Usergrid "release" brach. The big changes were switching to OpenJDK 8 and adding ElasticSearch. I also rewrote the scripts to use plain old Bash instead of Groovy.
https://github.com/snoopdave/usergrid-vagrant
If you want the old Usergrid 1 Vagrant-file then checkout the "1.x" branch.
Dave Johnson in Open Source
06:44AM Jan 02, 2016
Comments [2]
Tags:
asf
baas
usergrid
In part one, I explained the basics of the example Usergrid-Ember "Checkin" app, how the index page is displayed and how login is implemented. In part two, I'll explain how Ember.js can be hooked into the Usergrid REST API to store and query JSON objects.
Ember.js includes a feature referred to as Ember-Data, which provides a persistence interface for storing and retrieving JavaScript objects that could be stored in memory, or stored on a server and accessed via REST API.
To use Ember-Data with your REST API you've got to define an Ember-Data model and add an Ember-Data REST adapter. If your REST API differs from what Ember-Data expects then you will probably have to extend the built-in REST adapter to handle your URL pattens, and extend the built-in REST serializer to handle your JSON format. By extending Ember-Data in this way, you can use it to store and query data from Usergrid without using the Usergrid JavaScript SDK at all. Below I'll explain what I had to do to make the Checkin app's Activities collection available via Ember-Data.
Ember-Data expects each of your REST API collections to have a defined data model, one that extends the DS.Model class. Here's what I added for the Activities collection:
From app.js (link)
App.Activity = DS.Model.extend({ uuid: DS.attr('string'), type: DS.attr('string'), content: DS.attr('string'), location: DS.attr('string'), created: DS.attr('date'), modified: DS.attr('date'), actor: DS.attr('string'), verb: DS.attr('string'), published: DS.attr('date'), metadata: DS.attr('string') });
The Ember-Data REST adapter expects a REST API to follow some common conventions for URL patterns and for JSON data formats. For example, if your REST API provides a collection of cats then Ember-Data will expect your REST API to work like so:
What Ember-Data expects for a cats collection:
Usergrid follows the above conventions for collections, but there are some exceptions. For example, the Usergrid Activities collection. A GET on the /activities
path will return the Activities of the users that you (i.e. the currently authenticated user) follow. You don't POST new activities there, instead you post to your own Activities collection at the path /users/{your-user-id}/activities
. It works like this:
Usergrid's Activities collection:
To adapt the Activities collection to Ember-Data, I decided to create a new model called NewActivity. A NewActivity represents the data needed to create a new Activity, here's the model:
From app.js (Link)
// Must have a special model for new activity because new // Activities must be posted to the path /{org}/{app}/users/activities, // instead of the path /{org}/{app}/activities as Ember-Data expects. App.NewActivity = DS.Model.extend({ content: DS.attr('string'), location: DS.attr('string'), actor: DS.attr('string'), verb: DS.attr('string') });
Then, in Checkin's custom REST adapter, I added logic to the pathForType()
function to ensure that NewActivities are posted to the correct path. Here's the adapter:
From app.js (Link)
App.ApplicationAdapter = DS.RESTAdapter.extend({ host: Usergrid.getAppUrl(), headers: function() { if ( localStorage.getItem("access_token") ) { return { "Authorization": "Bearer " + localStorage.getItem("access_token") }; } return {}; }.property().volatile(), // ensure value not cached pathForType: function(type) { var ret = Ember.String.camelize(type); ret = Ember.String.pluralize(ret); if ( ret == "newActivities" ) { // Must have a special logic here for new activity // because new Activities must be posted to the // path /{org}/{app}/users/activities, instead of the // path /{org}/{app}/activities as Ember-Data expects. ret = "/users/" + Usergrid.user.username + "/activities"; } return ret; } });
You can see a couple of other interesting things in the example above. First, there's the host
field which specifies the base-URL of the REST API for the Checkin app. Next, there's the headers()
function, which ensures that every request carries the access_token
that was acquired during login.
Ember-Data also has expectations about the JSON format returned by a REST API. Unfortunately, what Ember-Data expects and what Usergrid provides are quite different. The two examples below illustrate the differences:
Ember-Data vs. Usergrid JSON formats
Ember-Data expects collections like this: { cats: [{ "id": "6b2360d0", "name": "enzo", "color": "orange" },{ "id": "a01dfaa0", "name": "bertha", "color": "tabby" }] } |
Usergrid returns collections like this: { action: "get", path: "/cats", count: 2, entities: [{ "uuid": "6b2360d0", "type": "cat", "name": "enzo", "color": "orange" },{ "uuid": "a01dfaa1", "type": "cat", "name": "bertha", "color": "tabby" }] } |
|
Ember-Data expects individual objects like this: { cat: { "id": "a01dfaa0", "name": "bertha", "color": "tabby" } } |
Usergrid returns individual objects like this: { "id": "a01dfaa0", "type": "cat", "name": "bertha", "color": "tabby" } |
You can see two differences above. Ember-Data expects JSON objects to be returned with a "type key" which you can see above: the "cats" field in the collection and the "cat" field in the individual object. Also, Ember-Data expects an object's ID field to be named "id" but Usergrid returns it as "uuid."
The deal with these differences, the Checkin app extends Ember-Data's DS.RESTSerializer
. Here's the code:
From app.js (Link)
App.ApplicationSerializer = DS.RESTSerializer.extend({ // Extract Ember-Data array from Usergrid response extractArray: function(store, type, payload) { // Difference: Usergrid does not return wrapper object with // type-key. So here we grab the Usergrid Entities and stick // them under a type-key var typeKey = payload.path.substring(1); payload[ typeKey ] = payload.entities; // Difference: Usergrid returns ID in 'uuid' field, Ember-Data // expects 'id'. So here we add an 'id' field for each Entity, // with its 'uuid' value. for ( var i in payload.entities ) { if ( payload.entities[i] && payload.entities[i].uuid ) { payload.entities[i].id = payload.entities[i].uuid; } } return this._super(store, type, payload); }, // Serialize Ember-Data object to Usergrid compatible JSON format serializeIntoHash: function( hash, type, record, options ) { // Usergrid does not expect a type-key record.eachAttribute(function( name, meta ) { hash[name] = record.get(name); }); return hash; } });
In the code above you can see how the extractArray()
method moves the "entities" collection returned by Usergrid into a type-key field as expected by Ember-Data and how it copies the "uuid" field to add the "id" field that Ember-Data expects.
We also need to transform the data that Ember-Data sends to Usergrid. You can see this above in the serializeInHash()
function, which ensures that when data is POSTed or PUT to Usergrid, the type key is removed because that's what Usergrid expects.
To implement Add-Checkin, I added an HTML template called "add-checkin" to Checkin's index.html file. The template displays an Add-Checkin form with two fields: one for content and one for the location. Here's what it looks like in all its modal glory:
Both fields are simple strings (someday I'd like to extend Checkin to use location information from the browser). I won't go into detail here, but it took a bit of research to figure out how to make a Bootstrap modal dialog work with Ember.js. Below you can see the add-checkin controller, which provides a save()
function to save a new checkin.
From app.js (Link)
App.AddCheckinModalController = Ember.ObjectController.extend({ actions: { save: function( inputs ) { var content = inputs.content; var location = inputs.location; var target = this.get("target"); var activity = this.store.createRecord( "NewActivity", { content: content, location: location, verb: "checkin", actor: { username: Usergrid.user.username } }); activity.save().then( function( success ) { alert("Saved"); }, function( error ) { alert("Error " + error.responseJSON.error_description); } ); } } });
In the code above you can see how easy it is to access Usergrid data via Ember-Data now that we've got our custom REST adapter and serializer in place. We create a new Activity with a call to this.store.createRecord()
and to save it all we need to do is activity.save()
.
To sum things up, here are some closing thoughts and observations.
I appreciate any feedback you might have about this article, the Usergrid-Ember project and Apache Usergrid. If you want to see how the whole Usergrid-Ember project fits together, find it on GitHub here: Usergrid-Ember. Next up, I'll write about my experiences using Apache Shiro to replace Spring Security in Apache Roller.
Dave Johnson in Web Development
05:23AM Jan 26, 2015
Comments [0]
Tags:
asf
baas
ember
javascript
usergrid
The next one of my 2014 Side projects that Id like to share is Usergrid-Ember, an experiment and attempt to learn more about Ember.js and Apache Usergrid by implementing the Checkin example from my Usergrid mobile development talk. If you're interested in either Usergrid or JavaScript web development then I hope you'll read on...
Ember.js is one of the leading frameworks for building browser-based apps. It's one of many JavaScript Model View Controller (MVC) frameworks. Generally speaking, these frameworks let you define a set of routes or paths in your app, for example /index, /orders, /about, etc. and map each to some JavaScript code and HTML templates. Handling a route usually means using Ajax to grab some model data from a server and using a template to create an HTML view of the data that calls functions provided in a "controller" object.
JavaScript MVC frameworks are not simple and each has its own learning curve. Is it really worth the learning time when you can do so much with a little library like jQuery? For most projects I think the answer is yes. These frameworks force you to organize your code in a logical and consistent way, which is really important as projects grow larger, and they provide features that may save you a lot of development time.
Based on what I've seen on the net and local meet-ups, the leading frameworks these days are Ember.js and AngularJS. After I saw Yehudi Katzs talk at All Things Open, I decided to spend some time learning Ember.js.
The first thing you see when you visit the Ember.js site is a big button that says "DOWNLOAD THE STARTER KIT" and so that is where I started. The Starter Kit is a, a minimal Ember.js project with about twenty JavaScript, HTML and CSS files. It's a good way to start: small and simple.
Ember.js Starter Kit files:
Sidebar: I do hope they keep the Starter Kit around when the new Ember-CLI tool matures. Ember-CLI generates too many magic boiler-plate files and sub-directories for somebody who is trying to understand the basics of the framework. And this is an interesting point of view: Ember-CLI is Making You Stupid by Yoni Yechezkel.
I like to bite off more than I can chew, so I decided to use a couple of other tools. I used Bower to manage dependencies and Grunt to concatenate and minify those dependencies, and other things like launching a simple web server for development purposes. I also decided to use Bootstrap to provide various UI components needed, like a navbar and nicely styled list views.
I won't cover the details, but it was relatively easy to get Bower and Grunt working. Here are the config files in case you are interested: bower.json and Gruntfile.js. I did hit one problem: when I included Bootstrap as one of my dependencies the Glyphicons would all appear as tiny boxes, so I decided to pull Bootstrap from a CDN instead (looks like there is a fix for that now).
Every Ember.js app needs to define some routes. There is a default route for the "/" path which is called the index route, and you can add your own routes using the Router object. The snippet below shows what I needed to get started:
Part of app.js (link)// create the ember app object App = Ember.Application.create(); // define routes App.Router.map(function() { this.route("login", { path: "/login" }); this.route("logout", { path: "/logout" }); this.route("register", { path: "/register" }); });
Ember.js will look for the JavaScript Route and Controller objects as well as the HTML template using the names above. For example: Ember.js will expect the login route to be named App.LoginRoute
, the controller to be named App.LoginController
and the template to be named "login."
Let's talk about the index route. When a user arrives at your app theyll be directed to the index route. Ember.js will then look for a JavaScript object called App.IndexRoute
to provide the model data and JavaScript functions needed for the index page. Heres a partial view of the index route:
App.IndexRoute = Ember.Route.extend( { // provide model data needed for index template model: function() { if ( this.loggedIn() ) { return this.store.find("activity"); } return []; } });
The index page of the Checkin app shows the Checkin activities of the people that you follow. Above you can see how to route's model()
function makes that data available to the template for display. If the user is logged in we call the store.find(activity)
function to call the Usergrid REST API to get an array of the latest Activity objects. There is some serious Ember-Data magic going on there and I'll cover that in part two of this article.
To display the index route, Ember looks for an HTML template called index and will use that template to display the index page. Below is the index template. The template is a Handlebars template and the things that appear in double curly-braces are Handlebars expressions.
Part of index.html (link)In the above template you can see a couple of {{action}}
expressions that call out to JavaScript methods defined in the Checkin app. The part of the code that uses the model is in the {{#each}}
loop which loops through each Activity in the model and dispays an HTML list with the the item.content and item.location of each Activity.
Here's what the above template looks like when displayed in a browser:
In Checkin, login is implemented using HTML Local Storage. Once a user has successfully logged in, the app stores the username and the user's access_token in Local Storage. When user arrives at the index page, we check Local Storage to see if that user is logged in and if not, we direct them to the login route, which in turn displays the login page using the template below.
Part of index.html (link)The LoginController provides the functions needed by the Login page itself and there are two. There is a login()
function (called on line 27 above) that performs the login, and there is a register()
function (called on line 31 above) that directs the user to the New User Registration page. Here's a snippet of code from the App.LoginController
that provides these two functions:
App.LoginController = Ember.Controller.extend({ actions: { login: function() { // login by POST to Usergrid app's /token end-point var loginData = { grant_type: "password", username: this.get("username"), password: this.get("password") }; $.ajax({ type: "POST", url: Usergrid.getAppUrl() + "/token", data: loginData, context: this, error: function( data ) { // login failed, show error message alert( data.responseJSON.error_description ); }, success: function( data ) { // store access_token in local storage Usergrid.user = data.user; localStorage.setItem("username", loginData.username ); localStorage.setItem("access_token", data.access_token ); // clear the form this.set("username", ""); this.set("password", ""); // call route to handle post-login transition this.get("target").send("onLogin"); } }); }, register: function() { this.transitionToRoute("register"); } } });
The above code shows how to login to a Usergrid app using jQuery's Ajax feature. The login()
function takes the username and password values from the login form, puts those in a JSON object with grant_type "password" and posts that object to the /token
end-point of the Usergrid app. If that post succeeds, the response will include an access_token. We store that in Local Storage; we'll need to use it in all subsequent calls to Usergrid.
Usergrid fans will notice that I'm not using the Usergrid JavaScript SDK. That's because Ember.js provides Ember-Data, which acts as a very nice REST client and can be adapted to work with the URL structure and JSON formats of just about any REST API. I'll write about that in part two of this article.
Dave Johnson in Web Development
04:39AM Jan 20, 2015
Comments [0]
Tags:
asf
baas
emberjs
javascript
I travelled to Budapest, Hungary for a couple of weeks for a very nice vacation with my wife and to speak at ApacheCon EU. Here are the slides that I presented at ApacheCon EU:
(you can also view the presentation on Slideshare.)
And here is the session abstract:
Whether you are building a mobile app or a web app, Apache Usergrid (incubating) can provide you with a complete backend that supports authentication, persistence and social features like activities and followers all via a comprehensive REST API and backed by Cassandra, giving you linear scalability. All that, and Usergrid is open source too.
This session will explain how you can use Usergrid to provide a back-end for your application. Well start with an overview of Usergrid features, then explore in depth how to authenticate users, store data and query data with the REST API provided by a Usergrid server. Well develop a simple HTML5 app and package it as a native mobile app via Apache Cordova. We'll also cover how to run Usergrid locally for development and testing.
Dave Johnson in Open Source
05:09AM Nov 29, 2014
Tags:
apache
apachecon
asf
baas
I've been working at Apigee since September 2013 and one of the things I love most about my new job is the fact that I'm actively contributing to open source again.
I'm working on Apache Usergrid (incubating), an open source Backend-As-A-Service (BaaS) that's built on the Apache Cassandra database system. Apigee uses Usergrid as part of Apigee Edge (see the Build Apps part of the docs).
Apigee contributed code for Usergrid to the Apache Software Foundation back in October 2013 and Usergrid is now part of the Apache Incubator. The project is working towards graduating from the Incubator. That means learning the Apache way, following the processes to get a release out and most importantly, building a diverse community of contributors to build and maintain Usergrid.
One on the most important parts of building an open source community is making it easy for people to contribute and and that's why I submitted a talk to the ApacheCon US 2014 conference (April 7-9 in Denver, CO) titled How to Contribute to Usergrid.
The talk is intended to be a briefing for contributors, one that will lead you through building and running Usergrid locally, understanding the code-base and test infrastructure and how to get your code accepted into the Usergrid project.
Here's the outline I have so far:
I'm in the process of writing this talk now so suggestions and other feedback are most welcome.
Dave Johnson in Open Source
12:10PM Mar 16, 2014
Comments [0]
Tags:
apachecon
asf
baas
cassandra
java
opensource
usergrid