onedb 0.0.4

The version 0.0.4 of the core client library and the test library for onedb have been released. In addition to a small enhancement and bugfix also some documentation has been added. Please find the details below.

The development of onedb has made extensive use of the OSGi platform to assure that the library is truly modular and no unwanted interdependencies between different components ‘creep’ into the codebase. I use OSGi also in other projects and, since it is often difficult to find OSGi ready versions of Maven artifacts, I have uploaded a number of such artifacts on github.

Apart from the smaller changes made to the client libraries, some bigger changes are in the works on the server-side. In particular, a number of changes have been made to accommodate the almost ready JavaScript API. I will write a separate post about these changes once they have been fully tested.

All older client libraries (0.0.1-0.0.3) should continue to function. No API breaking changes have been introduced in 0.0.4 (for apps written against the API of 0.0.3).

Documentation

There is now a small Java swing example application available on github. At the moment, only two screens are implemented:

  • Screen 1: Provides a simple user interface to create new realms (note, you will need to obtain an API key from the onedb website for this feature)
  • Screen 2: Provides a simple user interface to upload node with text to onedb.

Enhancements

  • It is now possible to ‘identify’ security tokens with the URI of the node, for which they grant access. This helps client and server negotiate the correct required secret for a node. For instance:

one.newNode(“mysecret”).asReadTokenWithIdentification(“http://u1.linnk.it/erg/myrealm“);

Bugfixes

  • The pom.xml file for oneTestJre.min and oneClientJre.min could lead to problems in some cases, since they included a dependency to the internal artefact oneClientJre. The pom.xml files for the 0.0.4 artifacts resolve this problem.

Callbacks in JavaScript

From many a Java programmer’s perspective, JavaScript has one serious limitation: within the browser applications written in JavaScript limited to only a single thread (with the exception of web workers as part of ‘HTML5’).

As with many other ‘limitations’ any programming environment provides, also the ‘single-threadedness’ of JavaScript comes both with advantages and disadvantages.

Since every line of a JavaScript program should be executed without noticeable latency to the end user, it is not advisable to execute long running operations within the unit of a single statement. Examples for such ‘long running’ operations would be a call to the server (AJAX) or the opening of a file (in the context of node.js).

In order to allow the developer to execute such operations, JavaScript frameworks use the concept of callbacks: The statement initiating the operation will be executed with very low latency and ‘call back’ a function specified as one of its parameters when the operation has been completed.

I believe that such callbacks, although they complicate the program flow, are a more natural way to model/program distributed applications; that is applications which in some way or another depend on resources distributed within a network or the Internet. Therefore, I have heavily based the onedb API on callbacks.

However, I have also done so in order to allow the onedb API to be ported into a JavaScript API naturally and easily.

In developing this JavaScript API now, I learned that there are multiple (accepted?) ways in JavaScript to model such callbacks.

Node.js Style

No specific function has to be defined for the ‘error’ case. If an error occurs, the first variable of the called back function (‘err’) will be defined. Hence, the developer must check within every callback function whether the ‘err’ variable is defined.

…load(filename, function(err, res) { if (err) … else { } });

Advantages

  • Very good for showing crisp code examples (which conveniently ignore the error case).

Disadvantages

  • A user of the API is not ‘forced’ to handle the error case, which can lead to more instable applications in the long term.
  • The callback function’s body will look more untidy and the control flow might be less clear because of the additional required ‘if’ function.

jQuery Style

The jQuery library in its largest part deals with local operations, which can hardly fail (e.g. fading out an element) or, more accurate, for which the handling of the failure case is insensible in most circumstances.

However, a few methods in jQuery do require the consideration of a potential ‘error’ occurring. This is particularly relevant for calls to a backend server (Ajax). For this case, jQuery allows the specification of multiple callback functions. These functions are only called if the case they represent becomes reality.

.ajax({…, success: function() {…}, error: function() {…}});

Variations of this approach include:

  • Pass as arguments to functions only one JavaScript object. Its key-value pairs represent the parameters for the function. In this case, adding the error case requires only to specify one more (optional) attribute in specifying the ‘argument’ object (this is the example given above).
  • Pass every callback function as parameter. In this case, the adding/removal of a callback function would require changing the method signatures.
  • Have one parameter designated to hold a map of the possible callback functions.

Advantages

  • Allows to easily specify global defaults for error functions (e.g., one function, which will always be called by default, if an error case occurs) (Variants 1,3)
  • Allows to keep the API more evolvable (what is, for instance, if we would like to distinguish between a ‘recoverable’ error and an ‘unrecoverable’ error (Variants 1,3)
  • Allows to avoid an additional if statement into the application flow (Variants 1,2,3)

Disadvantages

  • Might be a bit more verbose than the Node.js style (depending on which variant is used) (Variants 1 and 3 the most verbose, since they require to specify a ‘key’ for each parameter passed).
  • In Variants 1 and 3 the developer is not ‘forced’ to handle the failure case.

So What’s the Best Way to do Callbacks in JS?

My main reasons for recommending the jQuery style of JS callbacks (in particular variants 1 and 3) are:

  • Apart from the most trivial/standard APIs, I believe that evolveability should be a key concern in the development of APIs. The jQuery style approach allows for greater evolveability and flexibility since the different occurring case are not ‘hard wired’ into the application flow (as if statements).
  • In general, I think it is a good idea to use as little ‘if’ statements as possible (to make the application flow more ‘functional’)

Resources

jQuery .Ajax Error Handling Function

NodeJS Callback Conventions and Your App

A consistent naming scheme proposal for Javascript callbacks

Missing Name After . Operation

Problem

While accessing a GWT/Java class using the JSNI interface from JavaScript, GWT reports an exception along the lines of ‘missing name after . operation‘.

This might also happen when using the automated Java à JavaScript API converter gwt-exporter.

Analysis

This problem is caused by invalid JavaScript statements. In particular, if any of the Java packages and sub-packages contain words, which are reserved words in JavaScript but not in Java, JavaScript will not be able to evaluate the line referencing the Java object.

For instance:

com.mycomp.export.User is invalid, since the package name ‘export’ is a reserved word in JavaScript.

Solution

Avoid package names, which equal reserved JavaScript words such as export, var, goto, …

Refactor your existing classes and move them to packages with names not including any JavaScript reserved words.

References

JavaScript reserved words

Discussion Thread JSNI Reserved Word

Maven Module for gwt-exporter

gwt-exporter is an awesome library to generate usable JavaScript APIs for Google Web Toolkit applications.

It allows writing powerful libraries in Java and reuse the features these libraries provide in JavaScript applications!

I have assembled a small Maven Module for gwt-exporter 2.4 (M1), which readily configures gwt-exporter to be used as part of an OSGi-enabled project. This is particularily useful, if one wants to develop using the excellent eclipse plug-in development platform (which is useful for far more than developing eclipse plugins).

The source code is hosted as part of the osgi-maven project: thrdGwtExporter24.

The Maven dependency and repository are as follows:

Dependency:


 <dependency>
 <groupId>de.mxro.thrd.gwtexporter24</groupId>
 <artifactId>thrdGwtExporter24</artifactId>
 <version>0.0.1</version>
 </dependency>

Repository:


<repositories>
 <repository>
 <id>onedb Releases</id>
 <url>http://dl.dropbox.com/u/957046/onedb/mvn-releases</url>
 </repository>
</repositories>

If you would like to use gwt-exporter in a vanilla Maven project (without OSGi), you can use the gwt-exporter artefact hosted on Maven central:


<dependency>
 <groupId>org.timepedia.exporter</groupId>
 <artifactId>gwtexporter</artifactId>
 <version>2.4.0-M1</version>
 <scope>provided</scope>
 <exclusions>
<exclusion>
<groupId>com.sun</groupId>
<artifactId>tools</artifactId>
</exclusion>
 </exclusions>
</dependency>

(The exclusion is necessary to avoid dependencies to the Sun/Oracle JVM.)