Vaadin, let's hack the Profiler

Post to Twitter

Vaadin comes with a builtin Profiler which is only available during debug mode, which might not be available or reasonable. So, let us see if we can use it without the debug mode enabled.

It has a profiler?

Yes, there is one right builtin on the client side. You can activate it easily enough by adding the following to the widgetset:

  1. <set-property name="vaadin.profiler" value="true" />

But to see the results, you also have to switch the application into debug mode by changing the web.xml to the following:

  1. <context-param>
  2.     <description>Vaadin production mode</description>
  3.     <param-name>productionMode</param-name>
  4.     <param-value>false</param-value>
  5. </context-param>

This allows you to enter the debug mode of an application, though, that requires to restart the application (or in the worst case, a redeploy). One upside of testing new Widgetsets can be that one can apply them to any running application without modifications, because that is purely client-side. So changing the configuration of the application might not be possible or desirable.

There are some forum posts out there which talk about that it is enough to enable the profiler and see the the output of it being logged to the debug console of the browser, but that is not the case anymore.

Let's have a deeper look

The Profiler can be found in the class com.vaain.vaadin.client.Profiler and is comletely client-side. It will store all gathered information until the function logTimings() is called, which then will hand the gathered information to a consumer which can do with it whatever it wants. Now comes the interesting part, there is no public default implementation for the consumer provided. If you want to log what was profiled to the debug console you'll have to write your own. Even if there were, the function setProfilerResultConsumer(ProfilerResultConsumer) is commented with a warning that it might change in future versions without notice and should not be used - interesting. Also interesting is the fact that it can only be set once. Once set, it can not be changed.

Hm, looks a little bare bone. Of course there is an "internal" class that is utilizing it to send its output to the debug window, but we can't use any of that code, unfortunately. So let's see what we can do with it.

Send everything to the debug console

The easiest thing is to simply send all the output to the debug console of the browser, we can do this easily enough:

  1. import java.util.LinkedHashMap;
  2. import java.util.List;
  4. import com.vaadin.client.Profiler.Node;
  5. import com.vaadin.client.Profiler.ProfilerResultConsumer;
  7. /**
  8.  * A simple {@link ProfilerResultConsumer} which is outputting everything to the
  9.  * debug console of the browser.
  10.  *
  11.  * @author Robert Zenz
  12.  */
  13. public class DebugConsoleProfilerResultConsumer implements ProfilerResultConsumer
  14. {
  15.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  16.     // Initialization
  17.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  19.     /**
  20.      * Creates a new instance of {@link DebugConsoleProfilerResultConsumer}.
  21.      */
  22.     public DebugConsoleProfilerResultConsumer()
  23.     {
  24.         super();
  25.     }
  27.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28.     // Interface implementation
  29.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  31.     /**
  32.      * {@inheritDoc}
  33.      */
  34.     @Override
  35.     public void addProfilerData(Node pRootNode, List pTotals)
  36.     {
  37.         debug(pRootNode);
  39.         for (Node node : pTotals)
  40.         {
  41.             debug(node);
  42.         }
  43.     }
  45.     /**
  46.      * {@inheritDoc}
  47.      */
  48.     @Override
  49.     public void addBootstrapData(LinkedHashMap pTimings)
  50.     {
  51.         // TODO We'll ingore this for now.
  52.     }
  54.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  55.     // User-defined methods
  56.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58.     /**
  59.      * Sends the given {@link Node} to the debug console if it is
  60.      * {@link #isValid(Node) valid}.
  61.      *
  62.      * @param pNode the {@link Node} to log.
  63.      * @see #isValid(Node)
  64.      */
  65.     private void debug(Node pNode)
  66.     {
  67.         if (isValid(pNode))
  68.         {
  69.             debug(pNode.getStringRepresentation(""));
  70.         }
  71.     }
  73.     /**
  74.      * Tests if the given {@link Node} is valid, meaning not {@code null}, has a
  75.      * {@link Node#getName() name} and was {@link Node#getCount() invoked at
  76.      * all}.
  77.      *
  78.      * @param pNode the {@link Node} to test}.
  79.      * @return {@code true} if the given {@link Node} is considered valid.
  80.      */
  81.     private boolean isValid(Node pNode)
  82.     {
  83.         return pNode != null && pNode.getName() != null && pNode.getCount() > 0;
  84.     }
  86.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  87.     // Native methods
  88.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  90.     /**
  91.      * Logs the given message to the debug console.
  92.      *
  93.      * @param pMessage the message to log.
  94.      */
  95.     private native void debug(String pMessage)
  96.     /*-{
  97.         console.debug(pMessage);
  98.     }-*/;
  100. }    // DebugConsoleProfilerResultConsumer

And we can attach it rather easily, too:

  1. Profiler.setProfilerResultConsumer(new DebugConsoleProfilerResultConsumer());

Make sure to do this only once, otherwise an Exception will be thrown, stating that it can only be done once. Also the application should not be in debug mode, otherwise the Vaadin consumer will be attached. Now that we've attached a consumer we can recompile the Widgetset and actually try it, and low and behold, we see output in the debug window of the browser. Quite a lot, actually, seems like the Profiler is used often, which is good.

Filter the results

Skimming through the results is tedious, luckily most browsers come with the possibility to filter the results, but that possibility is quite limited. If we are interested in multiple results, the easiest way will be to filter them on the server side, obviously we can do that just as easily:

  1. import java.util.HashSet;
  2. import java.util.LinkedHashMap;
  3. import java.util.List;
  4. import java.util.Set;
  6. import com.vaadin.client.Profiler.Node;
  7. import com.vaadin.client.Profiler.ProfilerResultConsumer;
  9. /**
  10.  * A simple {@link ProfilerResultConsumer} which is outputting everything to the
  11.  * debug console of the browser.
  12.  *
  13.  * @author Robert Zenz
  14.  */
  15. public class DebugConsoleProfilerResultConsumer implements ProfilerResultConsumer
  16. {
  17.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18.     // Class members
  19.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  21.     /** The names of nodes we want to output. */
  22.     private Set wantedNames = new HashSet();
  24.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  25.     // Initialization
  26.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28.     /**
  29.      * Creates a new instance of {@link DebugConsoleProfilerResultConsumer}.
  30.      *
  31.      * @param pWantedNames the names of the profiler data which should be
  32.      *            displayed.
  33.      */
  34.     public DebugConsoleProfilerResultConsumer(String... pWantedNames)
  35.     {
  36.         super();
  38.         if (pWantedNames != null && pWantedNames.length > 0)
  39.         {
  40.             for (String wantedName : pWantedNames)
  41.             {
  42.                 wantedNames.add(wantedName);
  43.             }
  44.         }
  45.     }
  47.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  48.     // Interface implementation
  49.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51.     /**
  52.      * {@inheritDoc}
  53.      */
  54.     @Override
  55.     public void addProfilerData(Node pRootNode, List pTotals)
  56.     {
  57.         debug(pRootNode);
  59.         for (Node node : pTotals)
  60.         {
  61.             debug(node);
  62.         }
  63.     }
  65.     /**
  66.      * {@inheritDoc}
  67.      */
  68.     @Override
  69.     public void addBootstrapData(LinkedHashMap pTimings)
  70.     {
  71.         // TODO We'll ingore this for now.
  72.     }
  74.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  75.     // User-defined methods
  76.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78.     /**
  79.      * Sends the given {@link Node} to the debug console if it is
  80.      * {@link #isValid(Node) valid}.
  81.      *
  82.      * @param pNode the {@link Node} to log.
  83.      * @see #isValid(Node)
  84.      */
  85.     private void debug(Node pNode)
  86.     {
  87.         if (isValid(pNode))
  88.         {
  89.             debug(pNode.getStringRepresentation(""));
  90.         }
  91.     }
  93.     /**
  94.      * Tests if the given {@link Node} is valid, meaning not {@code null}, has a
  95.      * {@link Node#getName() name} and was {@link Node#getCount() invoked at
  96.      * all}.
  97.      *
  98.      * @param pNode the {@link Node} to test}.
  99.      * @return {@code true} if the given {@link Node} is considered valid.
  100.      */
  101.     private boolean isValid(Node pNode)
  102.     {
  103.         return pNode != null
  104.                 && pNode.getName() != null
  105.                 && pNode.getCount() > 0
  106.                 && (wantedNames.isEmpty() || wantedNames.contains(pNode.getName()));
  107.     }
  109.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  110.     // Native methods
  111.     //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  113.     /**
  114.      * Logs the given message to the debug console.
  115.      *
  116.      * @param pMessage the message to log.
  117.      */
  118.     private native void debug(String pMessage)
  119.     /*-{
  120.         console.debug(pMessage);
  121.     }-*/;
  123. }    // DebugConsoleProfilerResultConsumer

Now we can simply pass the list of "interesting" event names to the consumer and see only these.

JavaScript hacking

But there is more, instead of setting a consumer we can attach ourselves to the JavaScript function and instead process each profiled section individually. So in the debug console we can simply run something like this:

  1. window.__gwtStatsEvent = function(event)
  2. {
  3.     console.debug(event);
  4. };

This will output every single profiler event into the console. Now, if we want to process these events, we must first understand there is always a "begin" and an "end" event, which respectively are marking the begin and end of an event.

We can now listen for a certain event and simply output how long it took, like this:

  1. window.__profiler = {};
  3. window.__gwtStatsEvent = function(event)
  4. {
  5.     if (event.subSystem === "Layout pass")
  6.     {
  7.         if (event.type === "begin")
  8.         {
  9.             window.__profiler[event.subSystem] = event.millis;
  10.         }
  11.         else
  12.         {
  13.             console.log(
  14.                     event.subSystem
  15.                     + ": "
  16.                     + (event.millis - window.__profiler[event.subSystem]).toFixed(0)
  17.                     + "ms");
  18.         }
  19.     }
  20. };

Or, to go over the top, we could create a generic listener which informs us about everything:

  1. window.__wantedEvents = [
  2.     "Layout pass",
  3.     "Layout measure connectors",
  4.     "layout PostLayoutListener"
  5. ];
  7. window.__profiler = {};
  9. window.__gwtStatsEvent = function(event)
  10. {
  11.     if (window.__wantedEvents.indexOf(event.subSystem) >= 0)
  12.     {
  13.         if (typeof window.__profiler[event.subSystem] === "undefined")
  14.         {
  15.             window.__profiler[event.subSystem] = {
  16.                 averageRuntime : 0,
  17.                 count : 0,
  18.                 lastBegin : 0,
  19.                 lastEnd : 0,
  20.                 lastRuntime: 0,
  21.                 lastRuntimes : new Array(),
  22.                 minRuntime : 999999999,
  23.                 maxRuntime : -999999999,
  24.                 totalRuntime : 0
  25.             }
  26.         }
  28.         var info = window.__profiler[event.subSystem];
  30.         if (event.type === "begin")
  31.         {
  32.             info.count = info.count + 1;
  33.             info.lastBegin = event.millis;
  34.         }
  35.         else
  36.         {
  37.             info.lastEnd = event.millis;
  39.             info.lastRuntime = info.lastEnd - info.lastBegin;
  40.             info.lastRuntimes.push(info.lastRuntime);
  41.             info.minRuntime = Math.min(info.lastRuntime, info.minRuntime);
  42.             info.maxRuntime = Math.max(info.lastRuntime, info.maxRuntime);
  43.             info.totalRuntime = info.totalRuntime + info.lastRuntime;
  45.             info.averageRuntime = 0;
  46.             for (var index = 0; index < info.lastRuntimes.length; index++)
  47.             {
  48.                 info.averageRuntime = info.averageRuntime + info.lastRuntimes[index];
  49.             }
  50.             info.averageRuntime = info.averageRuntime / info.lastRuntimes.length;
  52.             console.log(
  53.                     event.subSystem
  54.                     + ": "
  55.                     + info.count.toFixed(0)
  56.                     + " times at "
  57.                     + info.averageRuntime.toFixed(3)
  58.                     + " totaling "
  59.                     + info.totalRuntime.toFixed(0)
  60.                     + "ms with current at "
  61.                     + info.lastRuntime.toFixed(0)
  62.                     + "ms ("
  63.                     + info.minRuntime.toFixed(0)
  64.                     + "ms/"
  65.                     + info.maxRuntime.toFixed(0)
  66.                     + "ms)");
  67.         }
  68.     }
  69. };

And we now have a neat little system in place which displays everything we'd like to know, and it is easily extendable and modifiable, too.


As we see, we have quite a few ways to get the information from the profiler even without the application running in debug mode, some might not be as obvious as others, though. The interesting part is that many things are easily accessible on the JavaScript side of Vaadin, directly from the debug console of the browser, one only has to look for it.

VisionX, a short look at Validators

Post to Twitter

It is time to have a short look at Validators, what they are, how they work and how they can be used.

Okay, what are they?

A Validator is a component which is available to our customers who have purchased VisionX, it allows to quickly and easily add field validation to a form or any screen with records.

Validators in VisionX

Validators are readily available in VisionX as components which can be added to the screen.

VisionX Validators - Toolbox

It can be added to the screen by simply dragging it like any other component, but must be configured afterwards to know which field required validation.

VisionX Validators - Properties

There are three important properties to the Validator:

  • Binding: The field to which the Validator should be bound to. This works analog to selecting to a field for an Editor.
  • Automatic validate: If the validation process should be automatically performed on value changes.
    If this is checked, the Validator will listen for value changes on the specified field and will automatically run the validation action on every change. If not checked, the validation process must be run manually by calling Validator.validate() as needed.
  • Hide until first validate: If the Validator should stay hidden until at least one validation was performed.
    If this is checked, the Validator will not be visible until at least its validation has been called once, afterwards it will always be visible.

Validating values

To actually validate something, we have to attach an action to the Validator which will perform the validation. This can be readily done through the VisionX action designer, which provides everything needed to create such an action and we will not go into detail on how to do this.

We will, however, have a short look at the code of a simple action.

  1. public void doValidateNonEmpty(Validator pValidator) throws Throwable
  2. {
  3.     if (Logical.equals(rdbData.getValue("COLUMN"), ""))
  4.     {
  5.         throw new Exception("A value for the COLUMN must be entered.");
  6.     }
  7. }

It is a very simple action, the current value of the DataBook is checked and if it is empty, an Exception is. This is the most simple validation action one can create.

Validators in action

Once we have everything setup, we can put the Validators to good use. When the validation is performed, may it be automatically or manually, the validation actions will be invoked and if all of them return without throwing an Exception, the Validator will display a green check mark. However, if the actions should throw an Exception, the Validator will display a red "X".

VisionX Validators - Failed

Manual validation

Manually invoking the validation process as needed is quite simple by calling Validator.isValid(), which will return either true or false.

  1. public void doSaveButtonPressed(UIActionEvent pEvent) throws Throwable
  2. {
  3.     if (validator.isValid())
  4.     {
  5.         rdbData.saveSelectedRow();
  6.     }
  7.     else
  8.     {
  9.         labelError.setVisible(true);
  10.     }
  11. }

Above you see a sample action which manually performs the validation process and either saves the data or sets an error label to visible.

The ValidationResult

One can quickly end up with many Validators in a single screen, which might make it difficult for the user to directly see why a field is not correctly validated. So it suggest itself that there should be a short summary close to the save button to make sure that the user is readily provided with the information why the action could not be performed. For this scenario there is the ValidationResult, which is another component which can be added to the screen from the toolbox.

It will automatically find all Validators in the screen and will perform their validation as needed. Afterwards it will gather all error messages and display them in a list.

VisionX Validators - ValidationResult

The ValidationResult can be used similar to the Validator in an action.

  1. public void doSaveButtonPressed(UIActionEvent pEvent) throws Throwable
  2. {
  3.     if (validationResult.isValid())
  4.     {
  5.         rdbData.saveSelectedRow();
  6.     }
  7.     else
  8.     {
  9.         labelError.setVisible(true);
  10.     }
  11. }

Additionally, there is the clearMessage() method which allows to clear the list of errors.


The Validator and ValidationResult provide quick and easy means to add data validation to forms and screens with records and can be added and configured completely through the VisionX designer. Additionally, it provides a rich API which allows it to be easily used when writing the code manually or extending it with additional functionality.

JVx Kitchensink, a simple JVx showcase application

Post to Twitter

As we've just noticed, we've neglected so far to properly introduce the JVx Kitchensink, a (very) simple showcase application for JVx and its controls. We'd like to rectify that now.

A simple showcase, not a demo application

The JVx Kitchensink can be found on GitHub and is available under an Apache 2.0 License. It demonstrates nearly all controls and components of the JVx framework and simple and easy to digest examples.

JVx Kitchensink

As some of you might know, there is also the JVx Hello World Application. The Kitchensink does not intend to supersede the Hello World Application, quite the opposite, the intention is to complement it. The Hello World Application is demonstrating how to quickly and easily set up a complete JVx application and have it up and running in mere minutes, with focus on the lifecycle of the application. The Kitchensink on the other hand demonstrates each individual component and control of JVx, and completely neglects the "normal" lifecycle of a JVx application.


The button bar on the left allows you to quickly access each example, for example the one about databinding.

JVx Kitchensink - Databinding

Newly added has been the feature that you can now see the source code of the selected sample right inside the Kitchensink, simply select the "Source" tab.

JVx Kitchensink - Databinding (Source)

Here I have to mention the awesome RSyntaxTextArea, which is a Swing component and provides highlighting and editing functionalities for source code, and is obviously used by us.

Regarding the lifecycle

As said before, the Kitchensink as not a good example of the lifecycle of a JVx application, as outlined in JVx Reference, Application Basics.

Packaged and ready

The Kitchensink does already come as a ready to use Eclipse project with launchers, so all you have to do is import it into Eclipse and be ready to go. There is also an Ant build script and instructions on how to launch the readily compiled jars.

Last but not least, it does provide a nice test bed for most of the functionality of JVx and demonstrates most concepts in a neatly packaged manner. We've been using it excessively during the development of the JVx JavaFX frontend bindings and it can be as simply used to test new concepts and custom components.

Once again, the link to the KitchenSink GitHub repository

JVx Reference, Resource and UIResource

Post to Twitter

Let's talk about Resources and UIResources, and why they sound similar but are not the same.

The Basics

We've previously covered how the JVx GUI layer works, now we are going to have a better look at the Resources and UIResources. With "Resource" we do not mean images or similar, we mean the implementation at the technology layer which is encapsulated by a wrapper class (Bridge Pattern). An "UIResource" on the other hand is an encapsulated concrete implementation of one of the interfaces on the UI layer.

Let's do a short brush-up on how the JVx architecture looks like in regards to the GUI stack:

JVx Resource

The UI Wrappers are the main UI classes which are used to create the GUI (f.e. UIButton). These are wrapping the Implementations (f.e. a SwingButton) which themselves are wrapping the Extension/Technology (f.e. a JVxButton/JButton). Only the UI and Implementation classes are implementing the interface required for the component (f.e. IButton). That also means that the Implementation is dependent on the Extension/Technology component, but the UI can use any object which implements the interface.

Now, with that knowledge we can start defining what is what:

JVx Resource 2

The resource itself, accessed by calling <uiwrapper>.getResource(), is the Extension/Technology component. The uiresource can be accessed by calling <uiwrapper>.getUIResource(). The uicomponent can be accessed by calling <uiwrapper>.getUIComponent() and is usually the UI Wrapper itself. If we use our previous Swing example, the resource would be a JVxButton/JButton, the uiresource would be the SwingPanel and the uicomponent would be the UIButton.

As one can see, access to all objects which are comprising the GUI is at all times possible. We, of course, have the UI component, we can access the Implementation component and we can access the Extension/Technology component. Theoretically we could also swap them at runtime, but in JVx this is limited to the construction of the object to greatly reduce the error potential.

Creating custom components

Equipped with that knowledge, we can revisit the previous guide on how to create custom components, the part about the BeepComponent to be exact:

  1. public class BeepComponent extends UIComponent<IPanel>
  2. {
  3.    public BeepComponent()
  4.    {
  5.       super(new UIPanel());
  7.       UIButton highBeepButton = new UIButton("High Beep");
  8.       highBeepButton.eventAction().addListener(Beeper::playHighBeep);
  10.       UIButton lowBeepButton = new UIButton("Low Beep");
  11.       highBeepButton.eventAction().addListener(Beeper::playLowBeep);
  13.       UIFormLayout layout = new UIFormLayout();        
  15.       uiResource.setLayout(layout);
  16.       uiResource.add(new UILabel("Beep"), layout.getConstraints(0, 0, -1, 0));
  17.       uiResource.add(highBeepButton, layout.getConstraints(0, 1));
  18.       uiResource.add(lowBeepButton, layout.getConstraints(1, 1));
  19.    }
  20. }

We are setting a new UIResource (an UIPanel) in the constructor (at line #5) which is to be used by the UIComponent. In this case it is not an Implementation, but another UI component, but that doesn't matter because the UIResource only must implement the expected interface. At line #15 we start using that custom UIResource.

Because UIComponent is an abstract component designed for exactly this usage, the example might not be the most exciting one, but it clearly illustrates the mechanic.

Bolting on functionality

Also from the previous guide on how to create custom components we can reuse the PostfixedLabel as example.

  1. private UILabel testLabel = new UILabel()
  2. {
  3.     public UILabel()
  4.     {
  5.         super(new PostfixedLabel("", "-trial"));
  6.     }
  7. };

Now testLabel will be using the PostfixedLabel internally, but with no indication to the user of the object that this is the case. This allows to extend the functionality of a component completely transparently, especially in combination with functions which do return an UIComponent and similar.

An important note about the component hierarchy

If we create a simple component extensions, like the BeepComponent above, it is important to note that there is one other layer of indirection in regards to the hierarchy on the technology layer. If we create a simple frame with the BeepComponent in it, one might expect the following hierarchy:

         UI                   Technology
---------------------    ----------------------
 UIFrame                  Frame
   \-UIPanel                \-Panel
       \-BeepComponent          \-BeepComponent

With the BeepComponent added and its sub-components as its children. However, the actual hierarchy looks like this:

         UI                   Technology
---------------------    ----------------------
 UIFrame                  Frame
   \-UIPanel                \-Panel
       \-BeepComponent          \-Panel

That is because such extended components are not "passed" to the Technology, they do only exist on the UI layer because they do not have a Technology component which could be used. That is done by adding the UIComponent to the UI parent, but for adding the actual Technology component the set UIResource is used.

The special case of containers

Another special case are containers. For example we could create a panel which does display an overlay in certain situations and we will need to use that throughout the whole application.

UIResourceContainer Example

That means we do not want to build it every time anew, so one option would be to use a factory method to "wrap" the content, something like this:

  1. UIFormLayout panelLayout = new UIFormLayout();
  2. panelLayout.setHorizontalAlignment(UIFormLayout.ALIGN_CENTER);
  3. panelLayout.setVerticalAlignment(UIFormLayout.ALIGN_CENTER);
  5. UIPanel panel = new UIPanel();
  6. panel.setLayout(panelLayout);
  7. panel.add(new UILabel("Firstname"), panelLayout.getConstraints(0, 0));
  8. panel.add(new UITextField("John"), panelLayout.getConstraints(1, 0));
  9. panel.add(new UILabel("Lastname"), panelLayout.getConstraints(2, 0));
  10. panel.add(new UITextField("Doe"), panelLayout.getConstraints(3, 0));
  11. panel.add(new UILabel("Street"), panelLayout.getConstraints(0, 1));
  12. panel.add(new UITextField("Old R. Road"), panelLayout.getConstraints(1, 1, 3, 1));
  13. panel.add(new UILabel("ZIP"), panelLayout.getConstraints(0, 2));
  14. panel.add(new UITextField("11946"), panelLayout.getConstraints(1, 2));
  15. panel.add(new UILabel("Place"), panelLayout.getConstraints(2, 2));
  16. panel.add(new UITextField("Hampton Bays"), panelLayout.getConstraints(3, 2));
  18. parentContainer.add(OverlayPanelFactory.wrap(panel), UIBorderLayout.CENTER);

And the wrap method itself:

  1. public static final UIPanel wrap(IComponent pContent)
  2. {
  3.     UILabel overlayLabel = new UILabel("FOR YOUR<br>EYES ONLY");
  4.     overlayLabel.setBackground(null);
  5.     overlayLabel.setFont(UIFont.getDefaultFont().deriveFont(UIFont.BOLD, 48));
  6.     overlayLabel.setForeground(UIColor.createColor("#3465a4"));
  7.     overlayLabel.setHorizontalAlignment(UILabel.ALIGN_CENTER);
  9.     UIFormLayout layout = new UIFormLayout();
  11.     UIPanel panel = new UIPanel();
  13.     panel.setLayout(layout);
  14.     panel.setBackground(UIColor.createColor("#3465a4"));
  15.     panel.add(overlayLabel, layout.getConstraints(0, 0, -1, -1));
  16.     panel.add(pContent, layout.getConstraints(0, 0, -1, -1));
  18.     return panel;
  19. }

Which is easy enough, but let's say we'd like to add logic to that wrapper, at that point it becomes more complicated. We can't use the same technique as for custom component from above, because in that case the "overlaying panel" would simply not be displayed. However, there is a similar mechanism for containers, setting the UIResourceContainer.

The UIResourceContainer is another special mechanism which works similar to setting the UIResource, but it works exactly the other way round. While setting the UIResource does "hide" components from the Technology which are there in UI layer, setting the UIResourceContainer does hide components from the UI layer while there are added in the Technology. A little bit complicated, here is our example again using this technique:

  1. public static class OverlayedPanel extends UIPanel
  2. {
  3.     public OverlayedPanel()
  4.     {
  5.         super();
  7.         UILabel overlayLabel = new UILabel("FOR YOUR<br>EYES ONLY");
  8.         overlayLabel.setBackground(null);
  9.         overlayLabel.setFont(UIFont.getDefaultFont().deriveFont(UIFont.BOLD, 48));
  10.         overlayLabel.setForeground(UIColor.createColor("#3465a4"));
  11.         overlayLabel.setHorizontalAlignment(UILabel.ALIGN_CENTER);
  13.         UIPanel innerPanel = new UIPanel();
  15.         UIFormLayout layout = new UIFormLayout();
  17.         setLayout(layout);
  18.         setBackground(UIColor.createColor("#3465a4"));
  19.         add(overlayLabel, layout.getConstraints(0, 0, -1, -1));
  20.         add(innerPanel, layout.getConstraints(0, 0, -1, -1));
  22.         setUIResourceContainer(innerPanel);
  23.     }
  24. }

What we've done is extend an UIPanel (line #1), setting it up and adding children and then we've declared one of its children as the UIResourceContainer (line #22). So all methods which are specific to IContainer (adding children, setting a layout, etc.) are now forwarding to the innerPanel and manipulating the contents of the OverlayedPanel directly is not directly available.

And here is how it is used:

  1. UIFormLayout panelLayout = new UIFormLayout();
  2. panelLayout.setHorizontalAlignment(UIFormLayout.ALIGN_CENTER);
  3. panelLayout.setVerticalAlignment(UIFormLayout.ALIGN_CENTER);
  5. UIPanel panel = new OverlayedPanel();
  6. panel.setLayout(panelLayout);
  7. panel.add(new UILabel("Firstname"), panelLayout.getConstraints(0, 0));
  8. panel.add(new UITextField("John"), panelLayout.getConstraints(1, 0));
  9. panel.add(new UILabel("Lastname"), panelLayout.getConstraints(2, 0));
  10. panel.add(new UITextField("Doe"), panelLayout.getConstraints(3, 0));
  11. panel.add(new UILabel("Street"), panelLayout.getConstraints(0, 1));
  12. panel.add(new UITextField("Old R. Road"), panelLayout.getConstraints(1, 1, 3, 1));
  13. panel.add(new UILabel("ZIP"), panelLayout.getConstraints(0, 2));
  14. panel.add(new UITextField("11946"), panelLayout.getConstraints(1, 2));
  15. panel.add(new UILabel("Place"), panelLayout.getConstraints(2, 2));
  16. panel.add(new UITextField("Hampton Bays"), panelLayout.getConstraints(3, 2));
  18. parentContainer.add(panel, UIBorderLayout.CENTER);

Notice that we can use it is any other panel (line #5) and simply add it to the parent (line #18). For a user of the API it is transparent as to whether there are more components or not, this is also visible in the created component hierarchy:

         UI                   Technology
---------------------    ----------------------
 UIPanel                  Panel
   \-OverlayedPanel         \-Panel
       |-UILabel                |-Label
       |-UITextField                \-Panel
       |-UILabel                    |-Label
       |-UITextField                |-TextField
       |-UILabel                    |-Label
       |-UITextField                |-TextField
       |-UILabel                    |-Label
       |-UITextField                |-TextField
       |-UILabel                    |-Label
       \-UITextField                |-TextField

This makes it very easy to have containers which add additional components without the actual GUI noticing or caring.


Because of the way the JVx framework is designed, it is easy to access all layers of the GUI framework and also facilitate the usage of these layers to create custom components and allow easy access to the wrapped components, no matter on what layer or of what kind they are.

VisionX Demo Application

Post to Twitter

With the preparations for the VisionX 2.4 Update 1 we've also created several simple but telling demo applications. Let's have a look at these.


We start our short tour with the first demo, the "Aircraft Manufacturing Line Dashboard" which is emulating a dashboard as it can be found in various factories and manufacturing companies.


Its main frontend is a Swing based GUI which displays (randomly generated) data, additionally there is a Vaadin powered frontend which displays the raw data. The main highlights of this demo are:

  • Capability to customize technology-specific components.
  • Utilizing custom components in the VisionX designer.
  • Usage of cell formatters.
  • Making WorkScreens only available in certain environments.
  • Data is generated with either the Random object or OpenSimplexNoise.


This is a demo of a typical dashboard and master data forms of an ERP application, in this case a small company focused on import and export of chemical/biochemical materials and similar.


All WorkScreens are fully functional in Swing and Vaadin environments. The main highlights of this demo are:

  • Demonstration of feature parity and interchangeability between Swing and Vaadin.
  • Creation of custom controls for displaying data.
  • Fully and easily editable with the VisionX designer.


Next up is a demonstration of the ability to create end-user facing web portals with JVx and VisionX.


The whole application is designed to function on large and small displays alike, like those of smartphones. The main highlights are:

  • Demonstration of extensive customization via CSS.
  • Differing layouts depending on the environment (Desktop, Tablet, Smartphone).


Accessing data and documents on the go is always kind of a hassle, but we can make it easier and more comfortable by providing easy to use GUIs for such occasions.


This simple document management system shows off a simple and easy to use GUI for accessing and manipulating documents in the storage. The highlights are:

  • GUI designed to be used on small, touch-enabled displays.
  • Extending the Table to allow checkbox based multi-row selection.
  • Inserting and retrieving files from a database.
  • The new Upload component available in ProjX.


Last but, not least, is the "big guide" of how to use reporting in VisionX.


This application will take you step by step through the capabilities and features of the VisionX reporting solution. Every WorkScreen demonstrates another feature complete with a description, example, access to the template and final report and of course the related documentation.

  • A step-by-step introduction to the VisionX reporting solution.
  • 12 examples with easy to read and documented source code.
  • All parts easily accessible: Source code, Template, Data and Report.


All these applications are available in the VisionsX Solution Store, on demand. The source code is licensed under the permissive Apache License.

JVx Reference, DataBooks

Post to Twitter

Let's talk about DataBooks, which allow access to data without any effort.

What is it?

DataBooks are an active model, which allow you to directly query and manipulate the data. Contrary to many other systems JVx does not map the data into objects, but instead allows you to directly access it in a table like fashion, exposing columns, rows and values.

One could say that it is like a three dimensional array, with these dimensions:

  1. DataPages
  2. DataRows
  3. Columns/Values

With DataPages containing DataRows, which itself contain the values and everything is referencing the RowDefinition, which outlines how a row looks like.

DataBook Architecture


The RowDefinition defines what columns are available in the row and stores some additional information about them, like the names of the primary key columns. You can think of the RowDefinition as the headers of a table.

Its creation and usage is rather simple, and if you're working with RemoteDataBooks there is no need to create one at all, as it is automatically created when the DataBook is opened. A RowDefinition holds and manages ColumnDefinitions, which define the columns.

RowDefinition rowDefinition = new RowDefinition();



The ColumnDefinition defines and provides all necessary information about the column, like its DataType, its size and if it is nullable or not. You can think of it as one column in a table.

ColumnDefinition columnDefinition = new ColumnDefinition("NAME", new StringDataType());


Most of the ColumnDefinition is additional information about the column, like if it is nullable, the label of the column, default values, allowed values and similar information.


Of course we must define what type the value in the column has, this is done by setting a DataType on the ColumnDefinition. The DataType defines what kind of values the column holds, like if it is a String, or a Number or something else. We do provide the widest used DataTypes out of the box:

  • BigDecimal
  • BinaryData
  • Boolean
  • Long
  • Object
  • String
  • Timestamp

It is possible to add new DataTypes by simply implementing IDataType.


The DataRow repesents a single row of data, it holds/references its own RowDefinition and of course provides access to the values of the row. Accessing the DataRow can be done either by column index or column name, and the methods do either return or accept Objects. Let's look at a simple usage example:

DataRow dataRow = new MemDataRow(rowDefinition);

String value = (String)dataRow.getValue("COLUMN_A");

dataRow.setValue("COLUMN_A", "New Value");


The DataPage is basically a list of DataRows, it also holds its own RowDefinition which is shared with all the contained DataRows.

The main usage of DataPages is to allow paging in a master/detail relationship. If the master selects a different row, the detail databook does select the related DataPage.


The DataBook is the main model of JVx, it provides direct access to its current DataPage and DataRow by extending from IDataRow and IDataPage.

By default, the DataBook holds one DataPage and only has multiple DataPages if it is the detail in a master/detail relationship.

Usage example

Here is a simple usage example of a MemDataBook, an IDataBook implementation which does only operate in memory:

IDataBook dataBook = new MemDataBook();
dataBook.getRowDefinition().addColumnDefinition(new ColumnDefinition("ID", new LongDataType()));
dataBook.getRowDefinition().addColumnDefinition(new ColumnDefinition("COLUMN_STRING", new StringDataType()));;

dataBook.setValue("ID", Long.valueof(0));
dataBook.setValue("COLUMN_STRING", "VALUE");

dataBook.setValue("ID", Long.valueof(1));
dataBook.setValue("COLUMN_STRING", "VALUE_A");



dataBook.setValue("COLUMN_STRING", "VALUE_NEW");




Accessing the data with Strings

One of the major advantages of the DataBook concept is that there is no need to create new classes to represent each table, view or query result. One can always use the DataBook, directly and easily and model changes don't necessitate changes on the client side. The downside to this approach is that we lose compile time checks because we access the data dynamically. However, This can be mitigated by using EPlug, an Eclipse plugin which provides compile time checks and many more features.

No primitives, Objects only

We do not provide overloads to fetch primitives, that is because there are mainly three types of data inside a database:

  1. Numbers
  2. Text
  3. Binary Data

Text and Binary Data are both objects (arrays of primitives are Objects after all) and Numbers are either primitives or Objects. Most of the time if we deal with numbers inside a database we want them to be of arbitrary precision, which means we must represent them as BigDecimal. Supporting double or float in these cases would be dangerously, because one might write a float into the database which might or might not end up with the correct value in the database. To completely eliminate such problems, we do only support Objects, which means that one is "limited" to the usage of Number extensions like BigLong and BigDecimal, which do not suffer from such problems.

Where are the DataPages?

What is not clear from this example is how and when DataPages are used. As a matter of fact, most of the time there is no need to think about DataPages because they are managed directly by the DataBook, and if used this like there is only one DataPage. Multiple DataPages will be used if there is a Master/Detail relationship defined in which case the DataBook does select the correct DataPage automatically.


Master/Detail is something that occurs in nearly every data model. It means simply that there is one master dataset which is referenced by one or multiple detail datasets. Or to express it in SQL:


We can of course express a Master/Detail relationship when using DataBooks. For that we just create a ReferenceDefinition and assign it to the Detail DataBook:

IDataBook masterDataBook = new MemDataBook();
masterDataBook.getRowDefinition().addColumnDefinition(new ColumnDefinition("ID", new LongDataType()));;

IDataBook detailDataBook = new MemDataBook();
detailDataBook.getRowDefinition().addColumnDefinition(new ColumnDefinition("ID", new LongDataType()));
detailDataBook.getRowDefinition().addColumnDefinition(new ColumnDefinition("MASTER_ID", new LongDataType()));
detailDataBook.setReferenceDefinition(new ReferenceDefinition(new Streing[] {"MASTER_ID"}, masterDataBook, new String[] {"ID"});;

Let's assume the following data for illustration purposes:

MASTER              DETAIL
======        =================
  ID            ID  | MASTER_ID
------        ------|----------
     1             1|         1
     2             2|         1
     3             3|         2
                   4|         2
                   5|         2
                   6|         3
                   7|         3
                   8|         3

Now if we select the second row in the masterDataBook, the detailDataBook will just contain the rows with the corresponding MASTER_ID, so 3, 4 and 5.

MASTER              DETAIL
======        =================
  ID            ID  | MASTER_ID
------        ------|----------
     1             3|         2
S    2             4|         2
     3             5|         2

The detailDataBook is automatically adjusted according to the selection in the masterDatabook. Of course this can have an arbitrary depth, too.


The DataBook is the backbone of JVx, it provides a clean and easy way to access and manipulate data. At the same time, it is flexible and can be customized to specific needs with ease.

JVx Reference, Application Basics

Post to Twitter

Let's talk about the basics, how a JVx application starts, works and how the connection strings together the client and server side.

Multitier Architecture

JVx is designed to be Multitier by default. It allows a clean and easy separation of processes and makes it easy to build, maintain and extend applications by separating the client, server and data storage.


The following method is a simplified way to launch a JVx application. Normally, you'd use the technology specific launcher to launch the application. These launchers do know exactly what is required to set it up and start the technology and the application. However, covering the launchers is out of scope for this post, so we will review them and their mechanics in a follow-up.

The simplest JVx application: Just the GUI

But first, we will start without anything. The most simple application you can create with JVx is an application which does open a single window and only works with in memory data (if at all). This can be easily achieved by "just starting" the application.

The JVx GUI is a simple layer on top of the Technology which implements the actual functionality. So if we want to have a GUI we'll need to initialize the factory before doing anything else:


With this little code we have initialized everything we need to create a simple Swing application. Now we can start to create and populate a window with something:

UIFrame frame = new UIFrame();
frame.setLayout(new UIBorderLayout());
frame.addComponent(new UILabel("Hello World!"));


frame.eventWindowClosed().addListener(() -> System.exit(0));

We can start to create and manipulate the GUI, in this case we are building a simple window with a label inside. Last but not least, we make sure that the JVM will exit when the window is closed.

A very good example and showcase for that is the JVx Kitchensink.

That's it. That is the most simple way to start a JVx application. We can use all controls and we can use MemDataBooks without any problem or limitation. And best of all, we can simply switch to another Technology by using another factory.

Anatomy of a remote JVx application

Of course JVx wouldn't be that useful if it would just provide static GUI components. Now, to explain what else is required for a remote JVx application I have to go far afield, so let's head down the rabbit hole.

JVx Layers

What you are seeing here is a rough sketch of how the architecture of JVx looks like. Let's walk through the image step by step. We will look at each successive layer and work our way from the database on the server to the databook on the client.

DBAccess, accessing a database

Accessing a database is easy when using DBAccess. All we must do is to set the JDBC URL of the server and connect to it:

DBAccess dbAccess = DBAccess.getDBAccess(

As a note, the instance returned by getDBAccess is the database specific DBAccess extension, which does know how to handle its database.

We can of course use DBAccess to directly access the database:

dbAccess.executeStatement("insert into SOME_TABLE values (?, ?);",
        "Some Value");

List<Bean> data = dbAccess.executeQuery("select * from SOME_TABLE");

...or manipulate the database, or query information about the database or execute procedures or do anything else.

DBStorage, preparing the database access for databooks

The downside of using DBAccess is that everything must be database specific. To become database agnostic we must use DBStorage. DBStorage does not care which database it is connected to and can operate on any of them:

DBStorage storage = new DBStorage();

We can use this to insert, update, delete and fetch data. Additionally the DBStorage does retrieve and manage the metadata of the table we've set, which means that we can query all column names, what type they are, we can even access the indexes and the default values. Short, the DBStorage leaves little to be desired when it comes to operating on a database.

If we query data from the DBStorage we receive a List of rows. The rows are are either represented as Object array, IBean or a POJO and we can easily manipulate the data, like this:

for (IBean row : storage.fetchBean(null, null, 0, -1))
    row.put("SOME_COLUMN", "newvalue");

As one can see, it looks quite familiar to the DataBook, which isn't a coincidence. The DBStorage "powers" the DataBooks on the server side, a DataBook will get its data from and will send its modified data to the DBStorage.

I've been using the DBStorage here as an example, but actually the Storage is not dependent on a database. IStorage can be implemented to provide any sort of data provider, like reading from an XML or JSON file, scraping data from a website, fetching data from a different process or reading it directly from a hardware sensor.

Life Cycle Objects, the business objects with all the logic

Life Cycle Objects, or LCOs, are the server side business objects which contain and provide the business logic. They are created and destroyed as is requested by the client-side and are used to provide specific functionality to the client, like providing functionality specific to one screen or workflow. This is done by RPC, Remote Procedure Calls, which means that the client is directly calling the methods defined in the LCOs, which includes getting the Storages for the DataBooks.

There is also a security aspect to these, as you can permit one client access to a certain LCO but lock out everyone else, which means that only that client can use the functionality provided by the LCO.

But let's not get ahead of our selves, there are three important "layers" of LCOs which we will look at.


The LCO for the application represents the application itself and provides functionality on the application layer. It is created once for the lifetime of the application and this instance is shared by all sessions.

public class Application extends GenericBean

The LCO for the session represents one session, which most of the time also equals one client connection. It provides functionality which should be session-local, like providing the database connection which can be used.

public class Session extends Application
    protected DBAccess getDBAccess() throws Exception
        // Code for initialization and caching of DBAccess goes here.
Sub-Session aka Screen

The sub-session, also known as screen, LCO is the last in the chain. It provides functionality specific to a certain part of the application, like a single screen, and provides the storages required to power the databooks and other functionality.

public class MySubSession extends Session
    public DBStorage getTablename() throws Exception
        // Code for initialization and caching of DBStorage goes here.

Server, serving it up

There really isn't much to say about the server, it accepts connections and hands out sessions. Of course it is not that easy, but for this guide we will not go into any further detail.

Connection, connecting to a server

The connection which strings together the client and the server is used for the communication between them, obviously. It can be anything, from a simple direct connection which strings two objects together to a HTTP connection which talks with a server on the other side of the planet.

By default we provide different IConnection implementations, the DirectServerConnection, DirectObjectConnection, the HttpConnection and the VMConnection. The DirectServerConnection is a simple IConnection implementation which does simply forward method calls to known Objects - without serialization - and is used when the client and server reside inside the same JVM. The HttpConnection communicates with the server over a HTTP connection and is used whenever the client and server are not inside the same JVM. The DirectObjectConnection and VMConnection are used for unit tests.

As example we will use the DirectServerConnection, which serves as Server and Connection. It is used if the server and client reside in the same JVM.

IConnection connection = new DirectServerConnection();
// The connection will be automatically opened by the MasterConnection.

Master- and SubConnections, client-side lifecycle management

The MasterConnection is the main connection which is used to access the server and its functionality. When a MasterConnection is established, a Session LCO on the server is created.

MasterConnection masterConnection = new MasterConnection(connection);;

A SubConnection is a sub connection of the MasterConnection and allows to access specific functionality encapsulated in an LCO. When a SubConnection is established, the requested/specified LCO on the server is created and can be accessed through the SubConnection.

SubConnection subConnection = masterConnection.createSubConnection("MySubSession");;

The SubConnection can now access the functionality provided by the Application, the Session and the LCO which was specified.


DataSource, preparing the connection for the databook

To provide data to the databooks we can use the connection which we've described earlier. However, the DataBook does not directly know about the connection, it expects an IDataSource, which is used as an intermediate:

IDataSource dataSource = new RemoteDataSource(subConnection);;

Of course the RemoteDataSource is just one possible implementation of IDataSource which can be used to provide data to the DataBook.

DataBook, accessing data

And now we are at the other end of the chain, at the databook on the client side. We just need to tell our databook what datasource to use, and we are done.

RemoteDataBook dataBook = new RemoteDataBook();

The name of the DataBook is used to access the DBStorage object in the LCO provided by the datasource. The mechanism for that is a simple search for a getter with the set name.

Interactive Demo

Here is an interactive demo which allows you to explore the connections between the client and server side. The complement classes are always highlighted and you can click on the names of the objects to receive additional information about them.

The JVx application: Manual example

Now that we have seen all layers that make up the architecture of JVx, let us put all of that into code:

public class JVxLocalMain
    public static void main(String[] pArgs) throws Throwable
        // ############################## Server ##############################
        // ----------------------------- DBAccess -----------------------------
        // The DBAccess gives us access to the database.
        DBAccess dbAccess = DBAccess.getDBAccess(
        // We'll insert some data for this example.
        dbAccess.executeStatement("create table if not exists TEST("
                + "ID int primary key auto_increment,"
                + "NAME varchar(128) default '' not null);");
        dbAccess.executeStatement("insert into TEST values (1, 'Name A');");
        dbAccess.executeStatement("insert into TEST values (2, 'Name B');");
        dbAccess.executeStatement("insert into TEST values (3, 'Name C');");
        // ---------------------------- DBStorage -----------------------------
        // Our sole storage.
        DBStorage testStorage= new DBStorage();
        // -------------------- LCO / Session / Application -------------------
        // We are skipping the LCO, Session and Application in this example.
        // ####################### Network / Connection #######################
        // For this example we are initializing a DirectObjectConnection, which
        // does not require a server.
        // It is designed to be used mainly for unit testing.
        DirectObjectConnection connection = new DirectObjectConnection();
        connection.put("test", testStorage);
        // ############################## Client ##############################
        // ------------------------- MasterConnection -------------------------
        MasterConnection masterConnection = new MasterConnection(connection);;
        // -------------------------- SubConnection ---------------------------
        // We are skipping the SubConnection in this example.
        // ---------------------------- DataSource ----------------------------
        IDataSource dataSource = new RemoteDataSource(masterConnection);;
        // ----------------------------- DataBook -----------------------------
        RemoteDataBook dataBook = new RemoteDataBook();
        // You can use the DataBook here.
        // Perform cleanup of all opened objects here.

With this little example we have a completely working JVx application. We provide ways to create most of this out of the box and read most of it from configuration files, so there really is just little code to be written, see the JVx FirstApp as a perfect example for that. So there is rarely any need to write code like this, all you have to do is create a new application and start it.

Additionally, we could combine this long example with the simple one from before to initialize and create a GUI which could use our RemoteDataBook, like this:

// Insert after the RemoteDataBook has been created.

// Set the UI factory which should be used, in this case it is
// the SwingFactory.

UIFrame frame = new UIFrame();
frame.setLayout(new UIBorderLayout());
frame.add(new UITable(dataBook));


frame.eventWindowClosed().addListener(() -> System.exit(0));

Abstractions on every step

As you can see, you always have full control over the framework and can always tailor it to your needs. There is always the possibility to provide a custom implementation to fulfill your needs:

  1. Accessing a not supported database can be achieved by extending DBAccess
  2. Having a different service/way of providing data can be implemented on top of IStorage
  3. Supporting a different connection can be implemented on top of IConnection
  4. And a completely different way of providing data can be implemented on top of IDataSource

You can swap out every layer and provide custom and customized implementations which exactly work as you require it.

Just like that

Just like that we've walked through the whole stack of a JVx application, from the database which holds the data all the way to the client GUI. Of course there is much more going on in a full-blown JVx application, for example I've spared you here the details of the configuration, server, network and providing actual LCOs and similar. But all in all, this should get you going.

Three years SIB Visions, a look back and ahead

Post to Twitter

My third year at SIB Visions is now coming to an end, once more it is time to take a deep breath, sit down and have a look at everything that has happened so far.

My year has been filled with a lot of non-public work, so please forgive me if I cannot go into details on various fronts.


Quite a few customers approached us and asked if we could implement prototypes for their projects, for one reason or another they all ended up on my table, the prototypes, that is. I like working on prototypes, because they allow me to quickly and easily explore new concepts and they have a definitive, narrow scope. Also we can finally use and show off all these cool new features we have built, like the new client-side layouts which we've created for our Vaadin implementation.

In the course of the year I've worked on over half a dozen prototypes for different customers. They all came with their own set of requirements and goals, obviously, and so they were very different to work on. The most interesting part about these prototypes is the vast spectrum of different designs and ideas. I unfortunately can't go into much detail here, but we've created application frames ranging from simple Swing input forms to highly customized Vaadin dashboards and information screens. Further down I'll talk a little more about these concepts and ideas.

Improved MySQL Fetching

Our MySQL implementation did suffer from a major problem, it fetched all records, always. That is not just an inconvenience as you can imagine, it might also lead to OutOfMemoryExceptions and similar problems. So one fine day we sat down and did take a deep look at our possibilities to either mitigate or completely fix this problem. As it turned out, the fix was far simpler and easier to implement than we imagined.

To cut an already told long story short, we are now utilizing the MySQL support to limit the fetched datasets (the LIMIT keyword). Which means that we are not only able to display initial data faster, but also fetching of more rows is now working as one would expect.


As you can see, we can now display initial data a lot quicker than before.

Vaadin Client-Side Layouts

More work has been poured into the aforementioned new client-side layouts and they are now usable for testing and (limited) productive usage.

Since the beginning we had trouble to sculpt the Vaadin layouts into the necessary shape to support our ideas about layouts. Over a year ago we started to work an new layout implementations which would operate completely client-side, most of the work was based off earlier work to improve the FormLayout. These new layouts have no logic on the server-side, but instead operate completely client-side only using "hints" from the server. That means that one can implement quite complicated layout logic (like our FormLayout) with ease.

We've implemented a new component, the so called LayoutedPanel, which can have different layouts. It does provide the base component for the new layouts but does not provide any logic itself. Instead it delegates all the layouting logic to layout implementations, that means it basically works the same as the Panel from AWT/Swing. Performing the layout logic on the client has multiple upsides, for example that the actual size of the components is known and that you can do it with a lot less elements.

Let's have a short look at how the usage of the LayoutedPanel looks like in pure Vaadin:

// Assume the following classes:
//    com.sibvisions.rad.ui.vaadin.ext.ui.panel.LayoutedPanel
//    com.sibvisions.rad.ui.vaadin.ext.ui.panel.layout.FormLayout
//    com.vaadin.ui.Label

FormLayout layout = new FormLayout();

LayoutedPanel panel = new LayoutedPanel();

panel.addComponent(new Label("Some label"), layout.getConstraints(0, 0));
panel.addComponent(new Label("On the right side"), layout.getConstraints(-1, 0));

As you can see, it is quite easy to use and works nearly identical to our panel/layouts. Let's take a further look into what is happening on the server and what is happening on the client.


On the server the LayoutedPanel manages the list of components which have been added, what layout is currently in use and the constraints of the added components. There are layout classes/implementations on the server, but they are mere placeholders (so that the LayoutedPanel on the client side knows which layout to use) and provide only limited logic (for example how to write the constraints into the state which is send to the client).


On the client side there is the ClientSideLayoutedPanel, with some basic logic for adding the components to the DOM and layouting, but does otherwise delegate all the work to the current layout. The DOM structure created consists of two divs, the main element and the "canvas" element:

  • panel
    • canvas
      • child
      • child
      • child
      • child

As mentioned in my last years post, the panel must fulfill two seemingly contradicting properties:

  1. It must resize itself to the size of/fill the parent container.
  2. It must dictate its own size.

This is necessary because the panel always must fill the parent, but at the same time it must dictate its own size so that the parent does not collapse if it does not have a fixed size set. The next stumbling block on the road was that the children of that panel would be absolute positioned. That means that the panel itself would not have a size because absolute positioned children are skipped when it comes to calculating the size of an element. Quite complex, but there is a rather simple solution:

  • panel (width: 100%, height: 100%)
    • canvas (min-width: 100%, min-height: 100%)
      • child (position: absolute)

Additionally, the size of the canvas is always set to the same size as the panel, to prevent the element from collapsing. There is of course more logic in place to make it all feasible and usable, but I won't go into any further detail here.

The layouts itself are simple to implement, they have a list of components and the size of the container, and they set the location and size of each component.


For everyone adventurous and daring enough, the source for the new layouts is available in the com.sibvisions.rad.ui.vaadin.ext.ui.panel and com.sibvisions.rad.ui.vaadin.ext.ui.client.panel packages in the JVx.Vaadin project.

For those who want to give these new layouts a spin in their application, you must simply set a property on the VaadinFactory to enable them:


Or if you don't want to import VaadinFactory:


From that moment on, every layout created will use the client-side layouts. Of course you can always set it to false or true inside your code, to get either new or old layouts.

Swing GridLayout improvements

We've also improved the GridLayout in Swing, previously the Swing GridLayout would show gaps every time it is resized. After some back and forth, we've managed to implement a new way to prevent/fill these gaps. That means that the Swing GridLayout is now distributing "left over space" through out its entirety, instead of just to the last column. This creates a very "organic" feel when it is resized and it is barely noticeable that some elements are a pixel wider than others.

More databases

Hurray! Over the course of the year we've added two new databases to JVx!


The first one is SQLite. In case you don't know what SQLite is, it is a simple, lightweight and easy to use database which is embedded into the application which uses it. That means there is no server or connection, not even a different thread for the database engine, there is just the driver which does everything. This is interesting for many reasons, but the main one is to allow embedded applications to use a lightweight database. It also supports an in-memory mode, which means that it never must write the data to any kind of storage.

We've added support for it to allow JVx applications to use it as fast and easy database backend whenever there are either system constraints (little memory or CPU power) or if there is no network connection. It can be easily used, like any other database which is supported by JVx:

DBAccess dbAccess = DBAccess.getDBAccess("jdbc:sqlite:");

// Or in-memory:
DBAccess dbAccess = DBAccess.getDBAccess("jdbc:sqlite:");

Because SQLite is designed to be used in embedded applications (or at least embedded in applications) it has quite limited functionality, like no triggers, functions or sequences. But nothing beats the minimal footprint and ease of use it has.


Another database which we now support is H2. H2 is a database written completely in Java, which can be started as a server or embedded into an application directly. Last but not least, it does also support an in-memory mode and nearly most features you got used to when using databases. It can be easily used, like any other database which is supported by JVx:

DBAccess dbAccess = DBAccess.getDBAccess("jdbc:h2:");

// Or in-memory:
DBAccess dbAccess = DBAccess.getDBAccess("jdbc:h2:");

Personally, I'm quite excited to support the H2, because it is a very easy to use and yet powerful and flexible database engine. I'm looking forward to use it in projects.


For the summer we actually had an intern which wanted to take a sneak peek into the world of software development. As it is with interns (at least around these parts), they are young, foolish and shy. What took me by surprise about this one was not only the eagerness with which he set to work, but also the will to learn new things as fast as possible. No matter how much information I threw at him (not literally, though, I was disallowed that, too) in the form of books and short lectures, he seemed to be able to digest and at least follow it, that impressed me very much. With very, very few exceptions ("Did you just fetch a Timestamp from a DataBook as String, parse that String to a Date and then convert it back to a Timestamp?") he was up to speed with Java and JVx in no time and wrote very good code. As I said, I am very impressed with how he held up.

Daniel, was a honor having you!

EPlug 1.2.5

Of course the year also brought more work on our Eclipse plugin, called EPlug, and the update to 1.2.5 was released in late summer.

Some of the highlights are:

  • Better hover information/tooltips
  • More and better ways to retrieve metadata
  • More options to control the errors/warnings issued by EPlug
  • QuickFixes for misspelled column names
  • And various more improvements and bug fixes

The most important new feature in this release might be the extended and improved tooltips, which look like this:

New hover information

For this to work we had to rewrite how tooltips were presented to the user. For those familiar with the Eclipse tooltip system, there is the IInformationControl interface which allows to display tooltips and similar. In previous versions we used an implementation which embedded a HTML renderer into the tooltip. That allowed the clients to have absolute control over the content, but it also meant that there were sever restrictions, for example autosizing the tooltip was tough.

With this version we used a new implementation which uses plain old SWT components and displays well prepared information, like this list of properties. This also has the upside that we now have absolute control over how images are treated, so they are now always fully displayed in the preview:

New hover information

All that is accomplished by a rather simple system. It's nothing more than a control with an icon (top-left), a title (top) and the content, which can either be an object or an image. If it is an object there are just a few ifs which are determining how to display that information.

What I took away from that was a quite important lesson. The initial implementation tried to be as flexible as possible by using a HTML rendering engine, the new implementation is not as flexible, but has a clear and well defined behavior and does have definitive advantages. So my advice is one that has been repeated way too often: YAGNI, You Ain't Gonna Need It. Start out small, and start building up as the need arises.

Oracle Forms Importer Improvements

As some of you might remember, one of the first tasks I was assigned to was to create an Oracle Forms Importer, which we do offer to VisionX customers. It is a rather simple piece of software which allows to import Forms directly into VisionX.

In autumn we took another shot at it and improved the import system, so that it now recognizes and correctly imports an even more varied range of forms.

Some of the major changes are:

  • Better recognition of bound controls
  • Improved setup of cell editors
  • Various other layout fixes (for example checkboxes are now correctly size)
  • And other improvements (for example the table column order is now correct)

Importing a form is still quite because of the outlined differences between Forms and JVx, but I believe that we are on a very good track and the current solution works quite well for a wide variety of forms.

Kitchensink improvements

Our Kitchensink, a simple demo application with all components and controls, has seen some improvements throughout the last year:

  • JVx has been updated
  • There are now all libraries and starters in place to get it to run
  • A new sample showing the FontAwesome icons
  • Improved the StyledTableSample and StyledTreeSample
  • Various minor improvements and more options

The Kitchensink is an Eclipse project, that means all you have to do is download or clone the source and import the project into Eclipse. With the included launchers you can now start it either with Swing or JavaFX frontend.

We are currently considering to embed a lightweight application server, so that testing the Vaadin frontend also becomes as easy as starting the Swing variant. That would mean that all three major frontends could be easily tested from the Kitchensink, which would be awesome.

Custom components

Some of our customers requested that we build custom components for them, these component should work in Swing and Vaadin in the same way. As I've outlined in a previous blog post, this is actually easily done depending on what your exact use-case is.

One of the most notable examples is a calendar which we've built on the technology layer. For Swing we've used the java-swing-calendar project and for Vaadin the Vaadin Calendar. Unfortunately, Vaadin has discontinued their Calendar for the time being. Anyway, we've implemented the calendar component and also added bindings for the databook to provide events, which was quite straight forward.

I do have to rant about the Vaadin Calendar, though. It does support two sources for the data, the Container interface and a calendar specific CalendarEventProvider interface. As we already had an implementation for a Container, I used that one and adjusted it so that it could be easily used with the Calendar. All fine and dandy, until I started to work with events, which are only providing a CalendarEvent as information on what event is affected. This CalendarEvent has zero information about the model, and I mean zero. There is no way to track the model from the CalendarEvent, you just don't know what event just was clicked or dragged. The only way is to not use a Container and instead use a CalendarEventProvider which returns custom CalendarEvent extensions which know about the model.

Otherwise implementing these components was very smooth.

EPlug 1.2.6

At the beginning of this year, we did some more work on EPlug and we could release EPlug 1.2.6 after a short time:

  • Cleaned up context menu
  • Resources (Images, etc.) are now also available from outside the source folders
  • Even better handling of DataBooks
  • Some bug fixes and other new features

The updates are available in the marketplace, so Eclipse can automatically update to it.

JVx References

For the last few months I have started to write a series of blog posts about various topics around JVx, the JVx Reference series. The goal is to provide a concise and easy to digest insight into JVx and various of its mechanics and techniques. There are currently three posts published:

And there are more in the pipeline:

  • About DataBooks
  • An Overview of how JVx works
  • What Resources and UIResources are in JVx

So stay tuned!


Out of the work on prototypes for our customers arose the idea to provide quite a few these new ideas to VisionX users in the form of demo projects. We've prepared these demo projects over the last few weeks and they will be released to the VisionX solution store within the next time.

Here is a sneak peek at those:





As said, these demo applications will be available in the VisionX Solution Store.

The look ahead

Wow, that has been an interesting year. A lot of things happened and we made a lot more happen, with even more stuff in the pipeline and yet even more stuff on the horizon. From where I'm sitting, the next year looks very interesting with a lot of new challenges, which we will for sure master.

Thanks to everyone at SIB Visions, it's been an awesome year and I'm looking forward to another one with all of you!

JVx Reference, Custom Components

Post to Twitter

Let's talk about custom components, and how to create them.

The GUI of JVx

We've previously covered how the GUI of JVx works, and now we will have a look on how we can add custom components to the GUI.

In the terminology of JVx there are two different kinds of custom components:

  1. UI based
  2. Technology based

We will look at both, of course.

Custom components at the UI layer

The simplest way to create custom components is to extend and use already existing UI classes, like UIPanel or UIComponent. These custom components will be Technology independent because they use Technology independent components, there is no need to know about the underlying Technology. You can think of those as a "remix" of already existing components.

The upside is that you never have to deal with the underlying Technology, the downside is that you can only use already existing components (custom drawing is not possible, for example).

Let's look at a very simple example, we will extend the UILabel to always display a certain postfix along with the set text:

public class PostfixedLabel extends UILabel
    private String postfix = null;

    // We must store the original text so that we can return
    // it if requested. Otherwise we could only return the text
    // with the appended postfix, which works unless the postfix
    // changes.
    private String text = null;

    public PostfixedLabel()

    public PostfixedLabel(String pText)

    public PostfixedLabel(String pText, String pPostfix)


    public String getText()
        return text;

    public void setText(String pText)
        text = pText;

        if (!StringUtil.isEmpty(postfix) &amp;&amp; !StringUtil.isEmpty(pText))
            // We translate the text and the postfix now separately,
            // the underlying label will obviously try to translate
            // the concatenated version.
            super.setText(translate(pText) + translate(postfix));

    public String getPostfix()
        return postfix;

    public void setPostfix(String pPostfix)
        postfix = pPostfix;

        // If the postfix changed, we must update the text.

It will be treated just like another label, but every time a text is set, the postfix is appended to it.

Another example, we want a special type of component, one that always does the same but will be used in many different areas of the application, it should contain a label and two buttons. The best approach for a custom component which should not inherit any specific behavior is to extend UIComponent:

public class BeepComponent extends UIComponent
   public BeepComponent()
       super(new UIPanel());
       UIButton highBeepButton = new UIButton("High Beep");
       UIButton lowBeepButton = new UIButton("Low Beep");
       UIFormLayout layout = new UIFormLayout();        

       uiResource.add(new UILabel("Press for beeping..."), layout.getConstraints(0, 0, -1, 0));
       uiResource.add(highBeepButton, layout.getConstraints(0, 1));
       uiResource.add(lowBeepButton, layout.getConstraints(1, 1));

So we extend UIComponent and set a new UIPanel as UIResource on it, which we can use later and which is the base for our new component. After that we added a label and two buttons which will play beep sounds if pressed. This component does not expose any specific behavior as it extends UIComponent, it only inherits the most basic properties, like background color and font settings, yet it can easily be placed anywhere in the application and will perform its duty.

Custom controls at the Technology layer

The more complex option is to create a custom component at the Technology layer. That means that we have to go through a multiple steps process to create and use the component:

  1. Create an interface for the functionality you'd like to expose
  2. Extend the Technology component (if needed)
  3. Implement the necessary interfaces for JVx
  4. Extend the factory to return the new component
  5. Create a UIComponent for the new component
  6. Use the new factory

I will walk you through this process, step by step.

The upside is that we can use any component which is available to us in the Technology, the downside is that it is quite some work to build the correct chain, ideally for every technology.

Creating an interface

The first step is to think about what functionality the component should expose, we will use a progress bar as example. We don't want anything fancy for now, a simple progress bar on which we set a percent value should be more than enough:

 * The platform and technology independent definition for a progress bar.

public interface IProgressBar extends IComponent
     * Gets the current value, in percent.
     * @return the current value. Should be between {@code 0} and {@code 100}.

    public int getValue();
     * Sets the current value, in percent.
     * @param pValue the value. Should be between {@code 0} and {@code 100}.

    public void setValue(int pValue);

Might not be the most sophisticated example (especially in regards to documentation) but it will do for now. This interface will be the foundation for our custom component.

Extending the component, if needed

We will be using Swing and the JProgressBar for this example, so the next step is to check if we must add additional functionality to the Technology component. In our case we don't, as we do not demand any behavior that is not provided by JProgressBar, but for the sake of the tutorial we will still create an extension on top of JProgressBar anyway.

public class ExtendedProgressBar extends JProgressBar
    public ExtendedProgressBar(int pMin, int pMax)
        super(pMin, pMax);

Within this class we could now implement additional behavior independent of JVx. For example, we provide many extended components for Swing, JavaFX and Vaadin with additional features but without depending on JVx. The extension layer is the perfect place to extend already existing components with functionality which will be used by, but is not depending on, JVx.

Creating the Implementation

The next step is to create an Implementation class which allows us to bind our newly extended JProgressBar to the JVx interfaces. Luckily there is the complete Swing Implementation infrastructure which we can use:

public class SwingProgressBar extends SwingComponent
                              implements IProgressBar
    public SwingProgressBar()
        // We can hardcode the min and max values here, because
        // we do not support anything else.
        super(new ExtendedProgressBar(0, 100));
    public int getValue()
        return resource.getValue();
    public void setValue(int pValue)

That's it already. Again, in this case it is quite simple because we do not expect a lot of behavior. The implementation layer is the place to "glue" the component to the JVx interface, implementing missing functionality which is depending on JVx and "translating" and forwarding values and properties.

Extending the factory

Now we must extend the Factory to be aware of our new custom component, that is equally simple as our previous steps. First we extend the interface:

public interface IProgressBarFactory extends IFactory
    public IProgressBar createProgressBar();

And afterwards we extend the SwingFactory:

public class ProgressBarSwingFactory extends SwingFactory
                                     implements IProgressBarFactory
    public IProgressBar createProgressBar()
        SwingProgressBar progressBar = new SwingProgressBar();
        return progressBar;

Again, it is that easy.

Creating the UIComponent

So that we can use our new and shiny progress bar easily, and without having to call the factory directly, we wrap it one last time in a new UIComponent:

public class UIProgressBar extends UIComponent
                           implements IProgressBar
    public UIProgressBar()
        // We'll assume that, whoever uses this component,
        // is also using the correct factory.
    public int getValue()
        return uiResource.getValue();
    public void setValue(int pValue)

Nearly done, we can nearly use our new and shiny component in our project.

Using thecustom factory

Of course we have to tell JVx that we want to use our factory, and not the default one. Depending on the technology which is used, this has to be done at different places:

Swing and JavaFX

Add the factory setting to the application.xml of the application:


Add the following setting to the web.xml under the WebUI Servlet configuration:


Using our new component

And now we are done, from here we can use our custom component like any other.

UIProgressBar progressBar = new UIProgressBar();

// Skip

add(progressBar, constraints);

Wrapping custom components with UICustomComponent

There is a third way to have Technology dependent custom components in JVx, you can wrap them within a UICustomComponent:

JProgressBar progressBar = new JProgressBar(0, 100);

UICustomComponent customProgressBar = new UICustomComponent(progressBar);

// Skip

add(customProgressBar, constraints);

This has the upside of being fast and easy, but the downside is that your code has to know about the currently used Technology and is not easily portable anymore.


As you can see, there are multiple ways of extending the default set of components which are provided by JVx, depending on the use case and what custom components are required. It is very easy to extend JVx with all the components one does require.

EPlug 1.2.6

Post to Twitter

We're happy to announce the release of EPlug 1.2.6. Again this small version bump does not only yield important bug fixes, but also new features which will make your life a lot easier.


This release includes bug fixes along with new features. One of the most notable problems fixed was that compile time checks might not be run if the communication with VisionX was active.

Cleaner context menu with more actions

We have restructured our approach to the context menu entries and introduced a new menu item which holds all EPlug related actions:

New context menu

As you can see we've also added new actions to jump to the configuration files.

Resources outside of source folders

We do support autocompletion and compile time checks for resources, like images. But we only supported resources inside of source folders, with this version we do now also support resources anywhere in the project.


Improved DataBook handling

DataBook handling has been improved once more. There are now additional checks which make sure that a RemoteDataBook receives the correct DataSource and there for if the MetaData can reliably be determined.

Additionally, the type of flag issued if no MetaData could be determined is now a configurable build option on the project.

New context menu

An example:

private void changeSomeValues(RemoteDataBook pDataBook)
    pDataBook.setValue("COLUMN_A", "A");
    pDataBook.setValue("COLUMN_B", "B");
    pDataBook.setValue("COLUMN_C", "C");

This would have been flagged as warning, because no MetaData could be determined for pDataBook. Now the check determines that determining MetaData for this DataBook is impossible and flags it accordingly. You can configure whether you want to see this flag or not in the project settings.

EPlug does also recognize if a "foreign" datasource has been set:

RemoteDataBook dataBookA = new RemoteDataBook();

RemoteDataBook dataBookB = new RemoteDataBook();

// This will be flagged as error.
dataBookA.setValue("NON_EXISTING", BigDecimal.ZERO);

// This will be flagged according to the settings.
dataBookB.setValue("NON_EXISTING", BigDecimal.ZERO);

Usernames for sessions

Last but not least, there is now a project setting which allows to set the username which is used by EPlug for the session it creates.

A little background, to acquire the MetaData (and some other information about the application) EPlug creates a session of the application and executes the server side code. It could be that projects do have checks and manipulations on the username somewhere in their code on the server. Previously EPlug would set null as username, but now it does either use the configured autologin username or the username configured in the project settings. That allows server side code which does operate on the username of the session to run without a problem, which means that there are no checks necessary if the session was initialized by EPlug or not.

How to get it?

Simply update EPlug via Eclipse!