Outdated Java3D in OSX Lion

Sep 20 2011

On Snow Leopard, the java distribution contained an out of date set of libraries for the Java3D package. It appears that the so-called final Apple release of Java for Lion has the same problem. This is an issue because the resources are placed in the Java Extensions path, so they override duplicates that you might put into your classpath.

So far, I haven’t found anything on my system that needs these outdated resources. Since all the programs and projects I’ve encountered that requre j3d or vecmath.jar seem to either contain the jars they need or declare a Maven or Ivy dependency on a specific version, the Apple-provided libraries just get in the way.

So I believe it is entirely safe to remove these files (please let me know if you have found a reason it is not safe).

  • /System/Library/Java/Extensions/j3daudio.jar
  • /System/Library/Java/Extensions/j3dcore.jar
  • /System/Library/Java/Extensions/j3dutils.jar
  • /System/Library/Java/Extensions/libj3D.jnilib
  • /System/Library/Java/Extensions/libj3DAudio.jnilib
  • /System/Library/Java/Extensions/libj3DUtils.jnilib
  • /System/Library/Java/Extensions/vecmath.jar

To view or add comments, please see the full post.

Adding SVG Images to Javadocs in a Maven Project

Feb 10 2011

I’ve been working on a project in which many java classes are crying out for graphical content in their documentation. In particular, many can be usefully represented as directed graphs. For these classes, it is nice to include the graphical representation right in the javadocs for the library in question. This post describes a way to achieve this using a combination of the open source [graphviz | http://www.graphviz.org/] package, conventional placement of files in a Maven project, and a custom Eclipse action. Some of what’s here is specific to generating the graphics, but if you have graphics files produced some other way, there may be some helpful info here as well.

Maven conventions

Maven projects benefit from the so-called convention-over-configuration paradigm. Rather than creating a bunch of xml configuration files, you simply put things in the conventional place and, poof, they are configured. It so happens, the javadoc processor also has some conventions, namely, the doc-files directory.

In a non-maven project, you might place a doc-files directory right in your source tree. In fact, that’s where the javadoc tool will look for it if invoked as a stand-alone tool. But when the Maven javadoc plugin invokes javadoc, it expects such things to reside in the javadoc tree. The javadoc tree of a Maven project mirrors the source tree, package-wise, and is also where you put your package.html files, for example. So if you have:

- Project
  - src
    - main
      -java
        - com
          - example
            - package

Then the corresponding doc-files directory would be at

- Project
  - src
    - main
      -javadoc
        - com
          - example
            - package
               - doc-files
Javadoc Conventions

The doc-files directory is a place to put things that can be linked concisely in javadoc comments. In the case of image files, those links end up rendered in the resulting HTML. Here’s an example of a javadoc comment that links an svg graphics file:

/**
 * blah blah blah
 * 
 * <div><object id="erg" data="doc-files/my_graph.dot.svg" 
 * type="image/svg+xml" width="700" height="400">
 * </object></div>
 */

That shortcut makes an assumption about the package coordinates of the class in which the javadoc appears. Also, that link can be any kind of HTML link; so you could link a png file with an img tag, for example.

SVG and the Graphviz package.

My goal was to render graphs in javadocs in such a way that the user could “zoom in” and actually read the textual annotations contained in the graph. A static png or jpeg file won’t work, because some of the graphs can be quite large, and you don’t want to send the user a 4800×4800px image. Scalable Vector Graphics to the rescue!

The graphviz package allows you to specify a visual graph representation in an easy to edit, readable format. Here’s an example:

digraph mission_commander {
layout = "dot"
rankdir = LR;
size = 7;
  graph [ fontname = "Verdana", fontsize = 10, label = "Mission Commander ERG" ];
  node [shape = circle, fixedsize=true, width=1.1, fontname = "Verdana", fontsize = 10];
  edge [fontsize = 10, labelfontsize = 10, labelfontname = "Courier", fontname="Arial"]
  
  Activate -> "Assign\nPlan" [
    taillabel = "0",
    label = "(asset available\n & mission available)",
    decorate = "false"
  ];
  
  Ready -> "Asset\nAvailable" [
    taillabel = "0",
    label = "[Asset]",
    decorate = "false"
  ];
  
  Return -> "Mission\nAvailable" [
    taillabel = "0",
    label = "[Asset]",
    decorate = "false"
  ];
  
  "Assign\nPlan" -> "Assign\nPlan" [
    taillabel = "0",
    label = "(asset available \n& mission available)",
    decorate = "false",
    len = 2
  ];
  
  "Mission\nAvailable" -> "Assign\nPlan" [
    taillabel = "0",
    label = "(asset available)",
    decorate = "true"
  ];
  
  "Asset\nAvailable" -> "Assign\nPlan" [
    taillabel = "0",
    label = "(mission available)",
    decorate = "false"
  ];
  
  "Assign\nPlan" -> "Start\nDeployment" [
    taillabel = "0",
    label = "[Asset, Plan]",
    decorate = "false"
  ];
  
}

That “.dot” file is like source code, and must be processed to produce a renderable image. On my Mac, the graphviz system was installed using macports, so everything is rooted in /opt. The image compilation is easily done on the command line:

kirk$: cd Project/src/main/javadoc/com/example/package/doc-files
kirk$: /opt/local/bin/dot -Tsvg -omy_graph.dot.svg my_graph.dot

Then, the resulting svg file will be rendered into the javadocs when you build them. The below is a static screen capture, but if you were to view the actual javadoc page, you would see that you can zoom in and out on the illustration and the text scales in a legible way. Imagine a graph with dozens of nodes, where by default the nodes are only 1/4" in diameter; those labels would not be legible, so the ability to zoom in and read the text is critical.

A custom Eclipse Action

I wanted a way to stay in my IDE and get the same results. In Eclipse, this is pretty easy using the External Tools Configuration mechanism. I won’t walk you through the steps of creating a custom External Tools Action, but here’s a screen cap of the setup I use. With this in place, you simply select the dot file and execute the external tools action.

To view or add comments, please see the full post.

Liferay Friendly Vaadin Themes using the Chameleon Theme

Jan 01 2011

Recently I’ve been faced with the prospect of deploying Vaadin servlets to the Liferay portal platform. Vaadin has great support for Liferay, but we experienced just enough difficulty (mostly due to our inexperience with these two platforms) to warrant documenting the solution.

Part of the source of our troubles came from the need for a Liferay page to contain the Vaadin app and nothing else. (No navigation bar, no header, no breadcrumbs, etc). Our Vaadin application has a lot of layout going on in it, because it is designed to stand alone practically as its own web page. The first run through, we used the Liferay page’s Look and Feel configuration to add some css overrides to turn off the normal Liferay elements. It worked, but there are lessons learned:

  1. The Vaadin theme loads after the Liferay theme has loaded, but before the page’s private CSS overrides
  2. The CSS overrides affect the page’s control elements (Like all the forms used to set look and feel)
  3. When approaching the CSS from this position, we found it quite tricky to target elements deeply buried within the Vaadin portlet.

We found it advantageous to avoid using the CSS override for the page itself, and instead develop a Liferay theme specifically for this situation. This is quite easy, and you can see how we did it here. But doing so pointed out fact (1) above. For the most part, a normal Liferay theme doesn’t touch the internal styling of a Vaadin portlet.

We tried many combinations of the normal themes that come with Vaadin (Reindeer, Runo, and even the so-called Liferay theme). The results were not to our liking (the portlet still looked different when deployed to a normal Tomcat container than it did when deployed to Liferay) and we spent rather a lot of time trying to tweak these themes via css, again using the Liferay page’s CSS overrides.

Enter the Chameleon Theme for Vaadin

The Chameleon Theme is a very polished and flexible Vaadin theme that comes with customization tools for choosing color schemes. You use the web-based tool until you are satisfied, and then download your customized theme as a jar file. Similar to the approach taken for Liferay themes, Chameleon has a base jar file, and then a much smaller css file that contains the customizations. This one relatively small css file can then be further fine tuned by hand. Also, Chameleon has a well documented set of style name applications that can be utilized from within your java code when building the internal layout of the Vaadin app.

So our solution is to use our PlainPage-theme applied to the specific Liferay page of interest, and to theme the Vaadin app using Chameleon with a transparent background. We turn off all the Liferay chrome by turning off the portlet borders in the Look and Feel controller on the portlet page. (This has implications for which styles get applied from the Chameleon theme, and is the main reason we forced a transparent background for the portlet.)

Though we don’t yet have a need for it, it looks to us like the Chameleon theme will also ease the path to creating Vaadin apps that need to coexist on the page with non-Vaadin apps on pages that have a real Liferay theme applied to them.

Organizing the Portlet Project with the custom theme

Because we wanted to tweak the Chameleon theme, we unpacked the jar file that you get from the Chameleon web tool, and treated the style.css as our own custom theme. The unarchived files wind up being positioned as illustrated here in the context of a Maven-based project’s src directory. If you didn’t need to customize, then the single jar from the download would replace vaadin-chameleon-theme-1.0.1.jar in the figure below.

src
   main
      java
      resources
      webapp
         META-INF
         VAADIN
            themes
               chameleon-transparent-grey
                  style.css
                  ...
            widgetsets
               ...
         WEB-INF
            lib
               vaadin-chameleon-theme-1.0.1.jar
   test
      ...

Finally, in your Vaadin Application subclass, call setTheme("chameleon-transparent-grey") when you start buidling the view. Take charge then of individual layout components by calling, e.g.:

  Panel p = new Panel("My Panel");
  p.setStyleName("borderless bubble");

It is also possible to use constants defined in the theme, but not all options are available as pre-defined constants. The Chameleon theme building tool has mouse-over tips on each example that tell you what style to set for the particular widget. Very nice.

To view or add comments, please see the full post.