Revision as of 12:07, 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.

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