Revision as of 13:42, 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

It’s not clear if I may pass parameters from javascript to java callback. Wondering if java may receive callbacks, which format it will accept. Created few functions like the one that changes background of document and other that prompts. Looks like we will need to store answers or states in model. Not clear if we may pass for example results of javascript execution right into model.


It isn’t clear how to include native JS library to the project. Should I add <script src="" type="text/javascript"></script> or I should duplicate library implementation in “body”? I tried with <script> section and it didn’t work. Well, finally, after several attempts I found out correct place for JS library based on compilation errors (“com/mycompany/mavenproject1/[34,8] error: Cannot find com/mycompany/mavenproject1/pretty.js in com/mycompany/mavenproject1/pretty.js”).

Document: Fixed the example, but possibly enlarge it.

From eclipse it is giving a

at test.Task4Model$TaskJS.chkAge(Native Method)

Action: Investigate the sample.

Error message:
at org.apidesign.html.boot.spi.Fn$1.invoke(
at com.atelles.Mul.multiply(
at com.atelles.BoxModel.showBoxPosition(


Interact with JavaScript from Java

Incidentally if executing the same file from eclipse is producing an error of

at test.Task5Model.usefulModify(Native Method)
at test.Task5Model.chkage(

Warning: The file really needs to be postprocessed by one of the Maven tasks.

The question related to the tasks 4 and 5 – can we accept a custom class as an input while making call from js to java or vice versa (I see a real need of that in one of my projects)?

Yes: It should be possible to pass any Java object to JavaScript and any JavaScript object to Java and later use them in calls or callbacks.


Did you have to leave the editor and read the documentation, why?

Yes I had to. The NetBeans editor did not have the documentation for the API attached by default plus I hadn’t used Knockout.js before, so I read Knockout docs too.

In order to understand API I read documentation, checked examples, because I need to have a picture in my head what it is all about. Some classes like Model have reference to example, but would be cool if you also add examples which show role of other classes and their usage, because x+2y+5Z = 322 example doesn’t make sense if we don’t know value of each, right? So once I read documentation, checked examples I was referring to examples and quickly adjusted that by my needs and ramped-up into it. So I didn’t leave my editor often, because it’s no so complex to be able to keep the picture in my head.

Also different parts of documentation show different aspects of behavior, but complete picture needs description probably of each class and their combination between them. I would really create some tutorials and more samples. So people start from the case which is very close to their need and adjust it a bit to their need, check some documentation, but not fully load that into their heads.

Did anything unexpected showed up during working with the API? Was the feedback from the library or the tooling helpful in case of problems?

Yes. During the Task 4, I was not able to use an external javascript library using annotation. Although there were no compiler errors there was a nullpointer exception. The stack trace wasn’t helpful at all due to the class generation.

Was it easy to do debugging & testing? If not, what was the obstacle?

The level of detail given by the stacktrace was not enough to diagnose the issue. Please see the stacktrace above. Maybe you should provide more details on debugging the auto generated classes, it looks very reasonable for me.

Name at least three ways (or more) we can improve the documentation

  1. More simple language should be used.
  2. Some comprehensive examples.
  3. Definitely requires getting started tutorial.
  4. Maybe add some possibility to leave comments on the doc pages, so developers can discuss the


  1. As I said above, I would like to have documentation for debugging applications of this type.

Compare this technology to others doing similar task. When would you prefer different rendering technology or language and why?

I can’t choose something certain for now, but I believe I choose something with a comprehensive documentation and support (community as well as vendor). The support can be a crucial factor. For example when I searched for a problem for this API there were very few or no results at all. Also, I am not sure about security of the API. How to secure a REST call? Security is very important for me and my clients.

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