Revision as of 13:22, 11 March 2014 by Jtulach (Talk | contribs)

In order to understand how good your API is (or at least how it satisfies time to market requirements), it is the best to perform a usability study. I ordered one for the Html4Java API in February 2014. Here are the observations.

The usability study was run by and I can only recommend their service: I didn't have to bother with searching for participants, getting them in place, collecting results, etc. All of this was very simplified thanks to Denis @apiusabilitytst.



I had to think-up some tasks for the participants. Here is what I made up:

  1. Creating own application in Java that renders through HTML.
  2. Animating an HTML page from Java via knockout bindings:
  3. Communicating with a server using JSON & REST or WebSockets
  4. Create a Java API wrapper for some JavaScript library - provide an ability to call some library's functions from Java
  5. Interact with JavaScript from Java

all of these tasks were actually listed and documented in the javadoc, so my expectation was, it can't be that hard to follow them. But, we have usability studies to get surprised!

Creating own application in Java that renders through HTML

Comments related to the first task:

Eclipse is Broken

Getting the example working was easy. But there were compiling problems on Eclipse: the Data class was missing and it took me a while to understand what was going on. One option to make the setup easier is to change the pom.xml generated by the archetype to include the “target/generated-sources/annotations/” as a source folder, and put a note in the documentation that you should run “mvn compile process-classes” every time there’s a change in your model.

Action: Document the API behavior in Eclipse as it does not seem to deal with Maven appropriately.

You have to be very careful when you put names in strings, the compiler won’t complain until you run, and even then the error message could not be so clear (I did misspelled a property name, and it took me 15 minutes to see my mistake).

Note: Eclipse, probably does not deal well with annotation processors. Well, other IDEs do... For example participants using InteliJ Idea 13 finished the first task quickly without any complains.

Not a JavaEE Technology!

I then spend some time figuring out what was going on with the example, read the suggested docs, and trying some changes. I didn’t know Knockout.js, so I had to learn the basics. Using the Main class to start a BrowserBuilder was a bit weird, I would prefer a more common approach: building a WAR, running it on Tomcat or Jetty and using Chrome to inspect the html and js.

Note: The JavaEE background of this participant shows. This technology has nothing to do with JavaEE (except being able to talk to the server). Probably we should note that somewhere.

Why Model Annotation at All?

Why should we use annotations for the property Models? It seems easier to have a single @Model, and the properties are real attributes in the class. The main issue here is: what am I gaining in using the @Model with the properties instead of a simple bean? Using a bean would make the code easier to understand and to work with.

Valid: Yes, JavaBeans are well understood concept, and Java developers are used to them. Having a way to expose existing JavaBeans and use it from Knockout, would simplify migration. On the other hand, it requires reflection and the whole @Model API tried to avoid reflection. But yeah, there should be an optional module to convert a JavaBean to a model class and use it. Thanks.

Understanding Knockout.js

It isn’t clear from the documentation that a developer must be familiar with Knockout.js. “This API allows you to write your application logic in Java and present it using modern HTML rendering technologies like Knockout and” so I thought your API uses some similar technology like Knockout, but not Knockout itself.

Valid: Point out that the Knockout website is great source of information for the HTML part of the technology.

Another observation is: I have no idea how the name scope would work when I have more than one model in the same page, or how to build a list, but this can be me not knowing Knockout.js, but I’m a bit unsure about how it would work from the sample code.

The compiler throws error but does not describe the problem. It seems to be a runtime exception. However the problem which I got after going deep into the stacktrace is that:

netscape.javascript.JSException: Error: Unable to parse bindings.
Message: ReferenceError: Can't find variable: on;

Note: Yeah, this is an exception coming from Knockout and it is a runtime exception. Currently there is no verification of the correspondence between the model and the actual tags in the HTML page.

Understanding Maven

Also, when I tried to download a project with Maven, I just copied your example command line “mvn archetype:generate -DarchetypeGroupId=org.apidesign.html - DarchetypeArtifactId=knockout4j-archetype -DarchetypeVersion=x.y” and it didn’t work, because of “-DarchetypeVersion=x.y”. Fortunately, I managed to try 7.5.0 instead of x.y and it worked.

Valid: Should always replace the x.y with appropriate version in the documentation.

When I started to execute maven script from “Getting Started” the compilation was showing some errors with JDK 1.6, so I switched to 1.7.

Valid: Fix the sample to run on JDK6. The API itself does, just the sample does not.

Animating an HTML page from Java via knockout bindings

Please really consider improving the documentation. I simple can’t get the “flow” and understand how to use the API. I am just using the existent examples, guessing and playing with them.

I based this task on the Task1. It took about 30 minutes to understand some details of Knockout.js (I hadn’t had experience with Knockout.js).

Documentation: Probably talk more about knockout.js and warn that this is not JavaEE

It is strange for me that a getter for generated boolean property has prefix “is”, but the setter has prefix “set”. When I played with the example, I tried several times with “getOn()” and got compilation error, but finally managed that I should use “isOn()”.

Note: Follows JavaBean specification. Could be made configurable in the annotation however.

The creation of a simple BoxModel with X and Y values was easy, but I’ve had to recompile and process-classes a few times because I changed the properties names a few times. The problem I found is that I had already used the methods of the generated Box on the Main class, and maven would fail to compile the code (for example: I changed the property from x to xPosition, but I didn’t change the setX() on the Main class):

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-
plugin:2.3.2:compile (default-compile) on project task1: Compilation failure
/Volumes/Oliphaunt/Users/user1/Documents/tasks/eclipse/task2/src/main/java/com/user1/[23,8] error: cannot find symbol

This was also annoying when I created a @ComputedProperty and I always forgot to change it’s parameters when I changed the @Model. Then I used the data-bind style to animate a green box based on the X,Y form inputs.

My issues interacting with the framework were the same as on Task1, and most of then would be gone if the Model were closer to a java bean.

Note: The optional module converting to JavaBean would be handy. At least users of Eclipse would have something that naturally works on their IDE...

Communicating with a server using JSON & REST or WebSockets

Online example really helped me. Not related to the task: it isn’t clear how to get access to nested JSON, for example:

  "html_url": "",
  "files": {
    "gistfile1.cs": {
      "filename": "gistfile1.cs",
      "type": "text/plain",
      "language": "C#",
      "raw_url": "",
      "size": 139

How to access “filename” property for example? I can’t find the answer in the documentation or examples.

Valid: Yes, this is not possible right now. Gists use JSON in a bit unexpected way (from my original point of view).

The problem with json/rest is that it’s not clear how it will handle complex rest/json models. Looks like we will need to define everything. It’s not clear from documentation, and I need to experiment, guess, and so on.

Valid: It is enough to name just few fields, the rest will be ignored. Will fix the documentation.

Can we initialize our class object with local JSON file? If yes, maybe you should mention that in the docs.

Valid: Yes, if the URL is relative to the index.html page, it should be possible to load a .json file next to the page. Need to verify and document.

Does the API support other providers like XML or Database to initialize a class object?

Too complex: Possibly, but it requires own implementation of transfer: - this is way beyond the scope of initial tutorial.

The json I wanted to show: The categoryID would be the variable, but I started with a fixed category. Both examples I found was for an array of the same type, but the JSON I had is a type with properties and arrays inside it. I tried many combinations with the mappings, but I couldn’t make it work.

Valid: OK, I add example non-array communication.

Too cryptic error message:

java.lang.Exception: [object XMLHttpRequestProgressEvent]
at org.netbeans.html.ko4j.LoadJSON.notifyError(

Finally it worked as I had included an extra parameter in the @Model

/** Generates class Resp which is a Java representation
* of appropriate JSON object sent from the server.
@Model(className="Resp", properties={
@Property(name="url", type=String.class), this was wrong
@Property(name="one", type=String.class),
@Property(name="key", type=String.class)
static class RespImpl {

Action': Investigate, improve error messages.

Create a Java API wrapper for some JavaScript library


Interact with JavaScript from Java


Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo