Wednesday, June 24, 2015

Rx.js Session at DevNation

I presented a Session on Rx.js at DevNation this year. My goal was to impress upon the audience how Observables can be interpreted as a collection-in-time. This analogy was very well described by @jhusain his Async Javascript at Netflix talk that initially got me excited about Reactive Functional programming. My contribution to this idea is to present it in a visual way.

To visualize both a "regular" collection, as well as a collection-in-time, I used the d3.js library to visually present a collection of javascript objects that each represent a shape with a given size, color, and shape-type. In my presentation I embedded these visualizations using as Codepens, which I’ve included in this blog post below.

The slides from my presentation are available at:

A Collection

Here is the visualization of a Collection. With a "regular" collection we can get a reference to every object in the collection at any given point in time. Go ahead, "grab" a shape with your mouse!

See the Pen Collection | Iden by Brian Leathem (@bleathem) on CodePen.

An Observable

And here we have the visualization of an Observable as a Collection-in-time. An Observable is different from a "regular" collection in that we cannot grab a reference to every object at any given point in time. The objects stream past us as time progresses.

See the Pen Observable by Brian Leathem (@bleathem) on CodePen.

Reactive Extensions

In the session I then proceed to use these visualizations as basis for describing some of the tools we use for manipulating Collections/Observables:

Map

With the map function we can operate on each item in the collection. In our example mapping function we map each shape into a new shape of the same size, but of type square and color green.

.map(function(x) {
      return {
        id: x.id
      , color: 'green'
      , size: x.size
      , type: 'square'
      };
    });

Collection map

Here we have the above map function applied to a "regular" Collection:

See the Pen Operating on a Collection by Brian Leathem (@bleathem) on CodePen.

Observable map

The above map function applied to an Observable:

See the Pen Map an Observable by Brian Leathem (@bleathem) on CodePen.

MergeAll

The mergeAll function is used to "flatten" a 2-dimensional collection into a 1-dimensional collection. In this code sample we map each shape into a pair of shapes which we return as an array. The resulting "array of arrays" is then passed to the mergeAll function where it is flattened.

.map(function(x) {
        var y = _.clone(x);
        y.id = y.id + 80;
        y.color = 'green';
    
        var z = _.clone(x);
        y.size = y.size / 1.5;
        z.size = z.size / 1.5;
    
        return [y, z];
      })
      .mergeAll();

Nested Collections

This visualization shows the above mapping without the mergeAll applied. Notice how the resulting collection consists of object pairs. We do not have a flat collection. Try to grab one of the shapes with your mouse and see for yourself!

See the Pen Map a nested Collection by Brian Leathem (@bleathem) on CodePen.

Nested Collections mergeAll

With the mergeAll function applied to the Nested collection we now have a flattened collection, which we can continue to operate on with our tool set.

See the Pen MergeAll a Collection by Brian Leathem (@bleathem) on CodePen.

Observable mergeAll

The mergeAll function applied to a 2-dimensional Observable.

See the Pen MergeAll an Observable by Brian Leathem (@bleathem) on CodePen.

FlatMap

It turns out the mapmergeAll combination is a pattern we apply so often that we created the flatMap function as a shorthand. We can then rewrite the above transformation as:

.flatMap(function(x) {
        var y = _.clone(x);
        y.id = y.id + 80;
        y.color = 'green';
    
        var z = _.clone(x);
        y.size = y.size / 1.5;
        z.size = z.size / 1.5;
    
        return [y, z];
      });

Reduce

A common use case for analyzing collections is the reduce function, where one iterates over a collection and "accumulates" a value for each object in the collection. In this code sample we are accumulating the size of each shape, and using that to create a new shape of the accumulated size.

var outputData = inputData
      .reduce(function(acc, x) {
        return {
          id: x.id
        , color: 'green'
        , size: acc.size + x.size
        , type: 'square'
        };
      }, {size: 0});

Collection reduce

The above reduce function applied to a collection:

See the Pen Reduce a Collection by Brian Leathem (@bleathem) on CodePen.

Observable reduce

The reduce function applied to an Observable:

Note

You will want to click the RERUN button that appears when you mouse-over this codepen. Then wait until the input Observable terminates to see the reduce result.

See the Pen Reduce an Observable by Brian Leathem (@bleathem) on CodePen.

Zip

The last function we will look at is the zip function which is used to combine many Observables into a single observable. It accomplishes this by taking each Observable as a parameter, followed by a function that is used to "combine" the object retrieved from each Observable.

In the following code sample we combine our shapes by creating a new shape with the color of the first shape, but the size and type of the 2nd shape.

var outputData = Rx.Observable.zip(
      input1Data,
      input2Data,
      function(x1, x2) {
        return {
          id: x1.id
        , color: x1.color
        , size: x2.size
        , type: x2.type
        };
      });

Observable zip

See the Pen Zip an Observable by Brian Leathem (@bleathem) on CodePen.

The rest of the talk

In the remaining slides I discuss creating and subscribing to Observables, and went through a number of use cases and examples. I ended with a preview and brief code walk-through of the Red Hat Summit Middleware keynote demo, that I wrote using Rx.js. But that is a topic for another post.

The slides are available at:


Thursday, February 5, 2015

Google Play Services Oauth2 Token Lookup via Cordova

Delegating to 3rd parties to manage your authorization is incredibly helpful when developing a new application. A benefit to users and developers alike, this task is made all the more helpful with the number of social networks providing Oauth2 APIs that we can use for our authorization. In this blog post I will address using the Google Play services on Android from a hybrid mobile Cordova application to retrieve an Oauth2 token that we can then use with Google’s Oauth2 REST API.

There are a number of blogs and how-tos on the web that show us how to use the Cordova InAppBrowser to trigger an Oauth2 token request. This approach works well, and indeed achieves the desired result of authenticating the user and retrieving an Oauth2 token. However the user experience is poor, requiring the user to enter their credentials. Why not leverage the already authenticated user logged into the mobile device? To achieve this we will have to make use of the Google Play services API.

Google Play services API

The Android documentation on Authorizing with Google for REST APIs is quite clear. We can use the Android API GoogleAuthUtil.getToken() method to retrieve an Oauth2 token for the logged-in user. The only missing link then is invoking the Android API from our javascript application.

A Cordova plugin

To close this gap, I created a Cordova plugin that invokes the GoogleAuthUtil API from a line of javascript, and returns the retrieved Oauth2 token to the javascript environment using a callback function. The Cordova Plugin Development Guide does a good job in describing how to author plugins. I recommend giving it a read if you are not familiar with developing Cordova plugins.

The only "gotcha" I had to deal with was the UserRecoverableAuthException that is thrown when first trying to retrieve the token. The above-mentioned Android documentation does a good job on describing how to catch the exception and retrieve appropriate permissions, but the Oauth2 token seems to get lost in the process. It turns out the token can be retrieved from an "Intent Extra" in the onActivityResult method of our plugin. Check out the plugin source if this is meaningful to you.

Consuming the plugin

The plugin I created is available on Github, and is installed using the command:

cordova plugin add https://github.com/bleathem/cordova-oauth-google-services.git

Remove this plugin with the command:

cordova plugin remove ca.bleathem.plugin.OauthGoogleServices

Invoke the plugin from your javascript:

window.cordova.plugins.oauth([scope], done, [err]);
  • scope optional: the scope for the Oath2 token request. Default: https://www.googleapis.com/auth/plus.me

  • done required: a success callback invoked the Oauth2 token as its single parameter

  • err optional: a failure callback invoked when there is an error retrieving the token

Example usage

In my Angular.js application I used a Promise API to retrieve the token:

var localLogin = function() {
      var deferred = $q.defer();
      $window.cordova.plugins.oauth.getToken('openid', function(token) {
        deferred.resolve(token);
      }, function(error) {
        deferred.reject(error);
      });
      return deferred.promise;
    }

I then posted the token to my backend where the token was verified and used to lookup/create a user. I set up a fallback mechanism to use the InAppBrowser approach to retrieve a Oauth2 token in cases where the Google Play services API was not present:

if ($window.cordova && $window.cordova.plugins && $window.cordova.plugins.oauth) {
      return localLogin().then(verifyToken, remoteLogin);
    }

The Final Word

This was the first Cordova plugin I created, and I must say I’m impressed at how easy it was to implement. I’ll definitely keep this tool close-at-hand when developing hybrid mobile applications.

Hopefully this Cordova plugin is useful to someone else; it certainly is easier to use than setting up the InAppBrowser solution!


Wednesday, January 28, 2015

Scalable splash screens with Cordova

Adding a splash screen to your mobile application is useful to provide users with feedback that their application is starting while performing any initialization tasks. In this blog post I will summarize how I created a scalable splash screen and how I configured my Cordova application to use it.

Drawing the splash screen

If you’re not an artist (as I am not!) then creating a graphical splash screen can be a somewhat daunting task. Finding a relevant image to use as a starting point can be a big help. I used the Creative Commons Search tool to find my initial image.

Edit the image using your favorite imaging editing software (I’m a fan of GIMP). Android pre-defines a set of sizes which you should target with your image:

  • xhdpi: 640 x 960

  • hdpi: 480 x 800

  • mdpi: 320 x 480

  • ldpi: 240 x 320

Similarly Apple has a set of predefined sizes, see the Apple HIG for details, but I’ll be addressing specifically Android with this post.

To keep things simple, I created a single square image to use for both portrait and landscape orientations:

Splashscreen

Making the splash screen scalable

Scaling the above image to fit the size and shape of a phone or tablet would distort the graphic and the text. To get around this we use the 9-patch file format to mark the areas of the image that can safely be stretched.

To convert the PNG file you created above into a 9-patch file, use the draw9patch application distributed with the android SDK. The basic steps of the conversion are as follows:

  1. Open you PNG file with the draw9patch application

  2. Drag with you mouse to mark the areas on the top and left margins where it is safe to stretch the image.

    • The right and bottom margins can be used to mark where content should be inserted into the image, and are useful when creating images for buttons. However this does not apply to splash screens, and you can safely ignore the right and bottom margins.

  3. Save your file with the *.9.png extension. The extension is critical, otherwise your splash screen image will not be interpreted as a 9-patch file, and the stretching will not be applied. I named mine splash.9.png.

Further details on using draw9patch can be found in the Android documentation.

Cordova build hooks

I like to structure my cordova projects to leave the platforms and plugins folders out of source control. I then use Cordova build hooks to install plugins and copy resources. For more information on build hooks, refer to this great post on using build hooks.

I place the above 9-patch image in the project folder config/android/res/screens and use the following build hook to copy this scm-controlled resource into the platforms folder:

030_resource_files.js
#!/usr/bin/env node
    
    //
    // This hook copies various resource files
    // from our version control system directories
    // into the appropriate platform specific location
    //
    
    // [{source: target}]
    var filestocopy = [
      ...
      , {
        "config/android/res/screens/splash.9.png":
        "platforms/android/res/drawable/splash.9.png"
      }
    ];
    
    
    var fs = require('fs');
    var path = require('path');
    
    var rootdir = process.argv[2];
    
    filestocopy.forEach(function(obj) {
        Object.keys(obj).forEach(function(key) {
            var val = obj[key];
            var srcfile = path.join(rootdir, key);
            var destfile = path.join(rootdir, val);
            console.log("copying "+srcfile+" to "+destfile);
            var destdir = path.dirname(destfile);
            if (fs.existsSync(srcfile) && fs.existsSync(destdir)) {
                fs.createReadStream(srcfile).pipe(
                   fs.createWriteStream(destfile));
            }
        });
    });

I’ve taken a one-size-fits-all approach with my splash screen. This works because I place my splash screen file in the platforms/android/res/drawable folder. If you want to create a different splash screen to accommodate each of the different screen sizes in either the portrait or landscape orientations, you can modify the above build hook to copy the appropriately sized files into each of the platforms/android/res/drawable-{port|land}-{ldpi|mdpi|hdpi|xhdpi}/ folders.

Cordova configuration

Finally we will install the cordova splashscreen plugin. This plugin allows us to manage the splash screen from our Cordova application.

We configure the default timeout and the name of our splash screen file in the config.xml of our project:

config.xml

    ...
    <preference name="SplashScreen" value="splash" />
    <preference name="SplashScreenDelay" value="10000" />
    ...
    

Using an appropriate listener in your Cordova application, dismiss the splash screen:

navigator.splashscreen.hide();

Conclusion

Getting the above pieces correctly lined up was surprisingly difficult. If the files are not named correctly, or placed in the wrong folder, everything falls apart. The Cordova documentation on the topic provides some help, but leaves out a lot of important details. This is apparent in the number of forum, stack overflow, and github issue threads on the subject. Hopefully this post helps someone shortcut the frustration of getting this working.


Monday, January 26, 2015

Vert.x with gulp.js

Vert.x is often put forward as a polyglot alternative to node.js that runs on the JVM. A read through the vert.x javascript docs indicates that javascript is a first-class language in vert.x, and both node.js and vert.x use an event-driven, non-blocking I/O programming model. But to what degree will a node programmer feel at home in writing a vert.x application?

In this blog post I will look at using gulp, a node.js build tool, to build a vert.x 2 module.

Platform Installation

Before proceeding, be sure to have both the vert.x and node.js platforms installed. Vert.x will provide the run-time for our application, and node.js will provide us with the build environment for our project. Refer to the vert.x install docs and the node and npm install docs for further details.

Project layout

The gulp.js build tool has us apply transformations to streams of our source code, and as such doesn’t dictate how we structure our source code within our project. The structure I chose is as follows:

.
    ├── gulpfile.js
    ├── node_modules
    │   └── ...
    ├── package.json
    ├── src
    │   ├── app.js
    │   ├── mod.json
    │   └── ...
    ├── tasks
    │   ├── vertx.gulp.js
    │   └── zip.gulp.js
    └── vertx_modules
        └── ...

The package.json file manages the npm dependencies for our gulp.js build, where those dependencies are stored in the node_modules folder. The gulpfile.js file is our gulp build file, and incorporates individual build tasks defined in the tasks folder. The src folder contains our the source for our vert.x module, and finally the vertx_modules folder contains the vert.x modules on which our application depends.

The gulp build

The gulp build file (gulpfile.js) is pretty straightforward; the top-level gulp file is used to configure the project, with individual tasks defined in separate files. These files are then included using the require statement.

gulpfile.js
process.env.VERTX_MODS = 'vertx_modules';
    
    var gulp = require('gulp');
    
    var opts = {
      module: {
        group: 'ca.bleathem',
        artifact: 'demo',
        version: '0.0.1'
      },
      paths: {
        src: 'src/**/*',
        dist: 'dist'
      }
    };
    
    opts.module.name = opts.module.group + '~'
                     + opts.module.artifact + '~'
                     + opts.module.version + '.zip';
    opts.paths.cp = 'src';
    
    require('./tasks/vertx.gulp.js')(gulp, opts);
    require('./tasks/zip.gulp.js')(gulp, opts);
    
    gulp.task('default', ['vertx']);

Notice the VERTX_MODS environment variable is set in the gulpfile. Using the build file to programtically set environment variable depending on the deployment target (production/development) can be a powerful technique. Here we set VERTX_MODS to store vertx modules in a folder paralleling the node.js modules.

The *.gulp.js build files containing the individual gulp task definitions are stored in the gulp sub folder.

...
    ├── tasks
    │   ├── vertx.gulp.js
    │   └── zip.gulp.js
    ...

Let’s explore these vertx and zip tasks further.

The vert.x gulp task

The gulp plugin guidelines recommend not creating a plugin for a task that can "be done easily with an existing node module". To this end, we’ll start by seeing how far we can by leveraging the abilities of node to spawn a child process. Below is a gulp task that runs the vert.x module that is our sample application:

vertx.gulp.js
var spawn = require('child_process').spawn
      , gutil = require('gulp-util');
    
    module.exports = function(gulp, opts) {
      gulp.task('vertx', [], function(done) {
        var child = spawn('vertx', ['runmod', opts.module.name, '-cp', opts.paths.cp ], {cwd: process.cwd()}),
            stdout = '',
            stderr = '';
    
        child.stdout.setEncoding('utf8');
        child.stdout.on('data', function (data) {
            stdout += data;
            gutil.log(data.slice(0, data.length - 1));
        });
    
        child.stderr.setEncoding('utf8');
        child.stderr.on('data', function (data) {
            stderr += data;
            gutil.log(gutil.colors.red(data.slice(0, data.length - 1)));
            gutil.beep();
        });
    
        child.on('close', function(code) {
            gutil.log('Done with exit code', code);
            done();
        });
      });
    };

The bulk of the above listing deals with re-directing and formatting the output of the vert.x child process. The invocation of the spawn function is the interesting part, and is where we pass our arguments to the vert.x process. In our case we want to run the module that is our sample project, and we set the vert.x classpath to our source folder to allow for on-the-fly code changes.

Invoking the build via the command gulp vertx will start vert.x, running the module in our project.

The zip gulp task

The distribution format for vert.x is a wonderfully simple zip format. This makes it easy to use a the gulp-zip plugin to zip up the file and create a bundle for our module.

vertx.gulp.js
var zip = require('gulp-zip');
    
    module.exports = function(gulp, opts) {
      return gulp.task('zip', function() {
        return gulp.src(opts.paths.src)
          .pipe(zip(opts.module.name))
          .pipe(gulp.dest(opts.paths.dist));
      });
    };

The above source transformation is a trivial one. Those familiar with gulp will recognize we could easily add additional stream transformations here, eg. compiling coffescript, minifying client code, compiling sass etc.

On to vert.x 3

The above build works well for vert.x 2. However vert.x 3 is around the corner and introduces many changes. The changes relevant to our gulp build include:

  1. Vert.x 3 will do away with modules and flatten the classpath across verticals. This will directly affect how we structure our source code and invoke vert.x from our gulpfile.

  2. Vert.x 3 will also resolve packaged verticles from npm, which will align nicely with our npm-based build approach.

Stay tuned for a new post addressing a gulp.js build targeting vert.x 3.


Tuesday, January 20, 2015

RichFaces 4.5.2.Final Release Announcement

RichFaces

RichFaces 4.5.2.Final is now available for download! Check out @Michal Petrov's blog for the detailed RichFaces 4.5.2.Final release announcement.


Tuesday, December 2, 2014

RichFaces 4.5.1.Final Release Announcement

RichFaces

RichFaces 4.5.1.Final is now available for download! Check out @Michal Petrov's blog for details of what this 4.5.1.Final release includes.


Wednesday, October 29, 2014

RichFaces 4.5.0.Final Release Announcement

RichFaces

RichFaces 4.5.0.Final is now available for download! RichFaces 4.5 is a significant improvement over the previous 4.3 release, offering JSF 2.2 compatibility, new components, a simplified build and distribution layout, and Page Fragments for simplified functional testing. Please read below for details on each of these improvements..

To try out this release: You can download the distribution directly, or for maven users, increment the RichFaces version in your pom.xml to 4.5.0.Final. For more information on setting up a RichFaces 4 application, refer to our getting started guide.

Compatibility with RichFaces 4.3: RichFaces 4.5 is intended to be backwards compatibility with RichFaces 4.3 and should be a drop in replacement into your applications, requiring only changes in your pom.xml.

Any breaking changes with RichFaces 4.5 are being tracked in our GitHub wiki migration page. Please update that wiki page with a Pull Request if you find any incompatibilities.

JSF 2.2 Compatibility

RichFaces 4.5 has been developed and tested against both JSF 2.1 and 2.2. Go forth and take advantage of the new features available in JSF 2.2.

Chart components

Thanks to the hard work of our Google Summer of Code student and subsequent intern Lukas Macko, we are providing a set of Chart components in RichFaces 4.5. Use these components to graphically represent the data in your applications with a similar API as the rest of your JSF components.

Read more about the RichFaces 4.5 charts in Michal Petrov’s blog post on using charts.

Component improvements

A number of existing components have seen some improvements in RichFaces 4.5. These are outlined below:

Select component with autocomplete

The <rich:select> component has been augmented to support the same auto-completing functionality as the <rich:autocomplete> component. The rule-of-thumb to keep in mind when deciding between incorporating either of these similar components is as follows:

  • use the <rich:select> component when auto-completing a list of backend objects.

  • use the <rich:autocomplete> component when auto-completing with text-based input.

Built-in sorting and filtering of the DataTable

The <rich:dataTable> has picked up the built-in sorting and filtering capabilities that have been available for some time in it’s big brother the <rich:extendedDataTable>.

If you are already using the <rich:dataTable> in your application with custom controls, and do not wish to take advantage of the built-in controls, then please refer to the Component reference for instructions on disabling the builtin sorting and filtering controls.

Push with web-sockets

We’ve upgraded our atmosphere dependency to version 2.2, allowing our <a4j:push> component to take advantage of web-sockets. The component will gracefully fall-back to long-polling when web-sockets are not available in either your deployment container nor in the browser.

Fileupload

The <rich:fileupload> component has been re-worked to take advantage of the new APIs provided with the Servlet 3.0 specification. This re-implementation has allowed us to add some new features. Check out the Fileupload sample in the showcase to play with the new implementation.

Under the hood

A number of improvements have been made in RichFaces 4.5 under the hood, these include:

A new ExtendedPartialViewContext

The new RichFaces EPVC extends the PVC in Mojarra, rather than fork it. This has the effect of not only making our EPVC easier to maintain with new Mojarra releases, but also eases compatibility with other JSF libraries.

However, due to a patched bug in Mojarra, our new EPVC will only work with newer Mojarra releases. As such we’ve implemented a check verifying that you are running in a container providing Mojarra ≥ 2.1.28 or ≥ 2.2.6. MyFaces is not affected by this bug.

Simplified build

The build in RichFaces 4.5 has been greatly simplified. We’ve consolidated the RichFaces source down to a single github repository. Along with improvements to the CDK, we have been able to drastically reduce our developer turnaround time when working with the framework.

It’s also expected that this simpler build structure will encourage more community contributions, so get those Pull Requests coming!

Page Fragments

If you do functional testing (or would like to) and haven’t yet looked at the Arquillian Graphene Page Fragments, then do yourself a favour and do so.

This is all the more relevant with our RichFaces 4.5.0.Final release as our RichFaces QE team has ported their set of page fragments for RichFaces components to the framework, providing you with a stable set of page fragments matching the shipped components. Write your tests to the stable page fragments API, and you won’t be caught by surprise with failing tests when the DOM implementation of a component changes in a future release.

Have a look at one of our Framework tests to see these page fragments in action.

Asciidoc

We’ve ported the RichFaces docs from the hard-to-work-with docbook xml to the writer’s paradise that is Asciidoc. This migration was motivated in large part by the Asciidoc improvements introduced by the Asciidoctor team. Thanks guys!

The docs are on github and ready for pull requests!

Release Notes

Check out the Release notes for a list of the issues addressed since the 4.5.0.CR2 release.

A bug with Mojarra

An unfortunate regression in Mojarra caused by the fix to JAVASERVERFACES-3152 has broken a number of RichFaces components when nested in a <ui:repeat> component (see RFPL-3506). We are working with the Mojarra team to see this resolved (via JAVASERVERFACES-3452).

In the mean time please use the <a4j:repeat> component as a workaround.

Next steps

We will follow on the 4.5.0.Final release with a series of micro releases further improving the stability of our framework. There are no planned additional releases of the 4.3 branch.