Enzo’s simple gauge in JFXtras

Gerrit Grunwald is an enspiring internet of things (IoT) evangelist and his JavaFX library ‘Enzo’ contains many visually attractive controls, well suited for IoT but also many other JavaFX applications. Gerrit used to be an active contributor to JFXtras, but he decided to move his work to his Enzo library. Why? Because the scope of JFXtras did not fit his needs.

As an IoT evangelist he develops many JavaFX controls for his demos, and he wants to get results fast; there is always that next conference in a few days.  JFXtras on the other hand tries to uphold a certain quality by a.o. requiring tests to prevent regression. This is not something a roaming evangelist wants to invest his time in. So we end up with an interesting situation; great but risky controls! Examples of this are all the gauges that are part of JFXtras-labs 2.x: they were never ported to 8.x and thus all their users have a problem there. This of course is the risk of using anything from JFXtras-labs, it is after all JFXtras’ playground, with no guarantee what-so-ever.

So what now? Great controls but too risky to touch? For Enzo that may be the case, as Gerrit states on his blog; “Please keep in mind that all controls in that library are made for my personal demos and are not production ready”. However, Gerrit and I have an agreement that I’m allowed to become ‘inspired’ by (aka blatantly copy) his demos. This already happened with CornerMenu, which was inspired by one of Gerrit demo’s and spawned CircularPane and CirclePopupMenu. The next inspiration Gerrit gave me was his SimpleGauge.

metroArcGauge

The control you see above is from  JFXtras and is known as SimpleMetroArcGauge and it (at the time of writing this) is part of JFXtras-labs. Currently it is in the process of fleshing out the API, which will be much more minimalistic than SimpleGauge, relying more on stylesheets. And also the concept of a single LinearGauge superclass is tried. After all, there is more to a good gauge than just a beautiful face.

When the gauge is finished, tests are written, and a sample is added to the samples, the gauge will move from labs to a new “gauge” module of JFXtras.

So there you have the explanation why suddenly Enzo controls start appearing in JFXtras.

Posted in Uncategorized | 7 Comments

circle popup menu

And once you are able to layout things in a circle…

Besides the CornerMenu described in the previous post, another incarnation of CircularPane is the CirclePopupMenu. It, as the name suggests, pops up a circle shaped menu on a mouse press.

circlePopupMenu

And since it is based again on CircularPane, several animation options are available and others can be created manually. A few examples are:

circlePopupMenu-appear circlePopupMenu-fromOrigin circlePopupMenu-overTheArc

CirclePopupMenu is available in JFXtras-8.0-SNAPSHOT-r2. And like CornerMenu; let me know how it works in real world applications.

Posted in Java, javafx, jfxtras, UI | Leave a comment

corner menu

A few months back I had the pleasure of attending the multidevice presentation by Gerrit Grunwald (@hansolo_). In this presentation he demonstrated how easy it was to port a single JavaFX code base to several devices, including Android, iOS, RasberryPi, and a few more. One of the UI elements he showed on each device was a corner menu; circular icons appearing from the corner of a window. This was visually a great UI component, and Gerrit told me it was part of his Enzo library. The Enzo library is full of such visually appealing JavaFX controls and components, and freely available to everyone who wants to use them, but it is also the case that Enzo mainly exists to support Gerrit in his presentations and demonstrations. And there is a difference between a control intended for public use and one that is a result of a demonstration. So when I asked Gerrit if I could take his control and move it over to JFXtras, he agreed immediately.

The first order of business was to layout stuff in a 90 degree arc. And I could have just copied Gerrit’s code, but as things go in a hobby project I decided that this should be something reusable, so CircularPane was born.

CircularPaneRectanglesAndCircles

It took some time to get it working correctly; creating a general purpose pane for laying out stuff in a circle dynamically is not as trivial as it seems. But after a few weeks it got to the point where CircularPane was mature enough, a demo was available, and it was unit tested. After that, work could finally start on one of the primary things it was created for: CornerMenu. (Although the fact that a round shaped Android watch will come out soon, may turn out to be a nice coincidence.)

So CornerMenu is exactly what it says: a menu that is located in any of the four corners of a window. The menu can be static, but usually it will show the items when the mouse comes close to the corner, like so:

cornerMenu-fromOrigin

Because CornerMenu is leaning heavy on CircularPane, it also supports configurable animations. Build-in are “from origin” (which can be seen above) and “over the arc” (below), both are based on the animations defined in CircularPane, but in CornerMenu some transparency and rotation is added.

cornerMenu-overTheArc

CornerMenu uses the standard MenuItem class of JavaFX, so starting to use it should be very straight forward. The main difference is that in CornerMenu the graphic of a MenuItem is mandatory, while in regular menu’s only the text is.

	// position a corner menu in the top left corner, that initially is not visible
	CornerMenu cornerMenu = new CornerMenu(CornerMenu.Location.TOP_LEFT, stackPane, false)
		.withAutoShowAndHide(true);

	// add the menu items
	cornerMenu.getItems().addAll(facebookMenuItem, googleMenuItem, skypeMenuItem, twitterMenuItem, windowsMenuItem);

CornerMenu is available in JFXtras-8.0-SNAPSHOT-r2. I’m very curious how it will work out in real world applications, so if anyone uses it, drop a line in the comments below!

Posted in Java, javafx, jfxtras, UI | 2 Comments

Java 8 method references

Java 8 is finally out officially and it brings probably the biggest change to the Java platform ever; lambda’s. Lambda’s are a very powerful technology which will have major influence on the way API’s in Java will be written, but the first critical sounds also are heard already.

Lambda’s in Java have two main aspects; one is the powerful stream API, where all kinds of processing is chained and in that way multicore processing is easily made possible. The other aspect is the replacement of the anonymous inner classes scaffolding, and that is probably the thing people are exited about first, when discovering lambda’s in Java 8. Let’s take a peek using my latest hobby project as an example.

In the previous blog I’ve written about CircularPane; a way to layout nodes in JavaFX in a circle. Below is an example of how some tests in CircularPane look (the green circles are debugging hints):

CircularPaneRectanglesAndCirclesDebug

One of the latest additions is that nodes can be animated into their positions. The example below shows that the left two CircularPanes animate their nodes into place “over the arc”, the right two “from origin”.
circularPaneAnimation

Now, this animation is a calculation of a progress (0.0 to 1.0) over time. For example the “from origin” slowly adds the difference between the origin and the end location; at 0.0 all nodes are at the origin, at 1.0 all nodes have the full difference added and are at their end location. For this a Transition is used to handle the calculation of the progress value, CircularPane has precalculated all sorts of layout values, so the actual calculation it is pretty straight forward.

   	new Transition() {
		...
		@Override
		protected void interpolate(double progress) {
			for (AnimationLayoutInfo animationLayoutInfo: animationLayoutInfos) {
				double lX = animationLayoutInfo.originX + (progress * -animationLayoutInfo.originX) + (animationLayoutInfo.nodeLayoutInfo.x * progress); 
				double lY = animationLayoutInfo.originY + (progress * -animationLayoutInfo.originY) + (animationLayoutInfo.nodeLayoutInfo.y * progress);
				animationLayoutInfo.node.relocate(lX, lY);    	
			}
		}
	}.playFromStart();

In the code above the “from origin” animation is hardcoded in the Transition, but I would like to make this dynamic, so multiple animations can be supported. In order to facilitate this, an interface is introduced that will hold the actual interpolation calculation, and that is called instead:

	// the interface
	@FunctionalInterface
	public interface AnimationInterpolation {
		public void interpolate(double progress, AnimationLayoutInfo animationLayoutInfo);    	
	}

	// a property for setting an implementation of the interface
	final private ObjectProperty<AnimationInterpolation> animationInterpolationObjectProperty = new SimpleObjectProperty<AnimationInterpolation>(this, "animationInterpolation", null);

	new Transition() {
		...
		protected void interpolate(double progress) {
			for (AnimationLayoutInfo animationLayoutInfo: animationLayoutInfos) {
				animationInterpolationObjectProperty.get().interpolate(progress, lAnimationLayoutInfo);
			}
		}
	}.playFromStart();

Things are in place to have the animation implemented externally. Prior to Java 8 this would involve creating an anonymous inner class like so:

	lCircularPane.setAnimationInterpolation(new CircularPane.AnimationInterpolation() {
		@Override
		public void interpolate(double progress, AnimationLayoutInfo animationLayoutInfo) {
			double lX = animationLayoutInfo.originX + (progress * -animationLayoutInfo.originX) + (animationLayoutInfo.nodeLayoutInfo.x * progress); 
			double lY = animationLayoutInfo.originY + (progress * -animationLayoutInfo.originY) + (animationLayoutInfo.nodeLayoutInfo.y * progress);
			animationLayoutInfo.node.relocate(lX, lY);    	
		}
	});

Even though this is a lot of scaffolding, it is very clear what is going on: you are implementing an interface defined in CircularPane, and you see exactly which method it defines. Now, if the interface changes for any reason, it is obvious that this code will get compiler errors. But also an IDE can easily find all implementations of an interface, because it is explicit. No magic.

But that is a lot of code just to be explicit. So the equivalent lambda notation does make it a lot more readable. Basically the compiler generates the anonymous inner class. It is a trade off between brevity and completeness, but one probably worth trading. And in the end, knowing how lambda’s work, there is still the notion of that anonymous inner class underneath. The scaffolding is just generated for you.

	lCircularPane.setAnimationInterpolation( (progress, animationLayoutInfo) -> {
		double lX = animationLayoutInfo.originX + (progress * -animationLayoutInfo.originX) + (animationLayoutInfo.nodeLayoutInfo.x * progress); 
		double lY = animationLayoutInfo.originY + (progress * -animationLayoutInfo.originY) + (animationLayoutInfo.nodeLayoutInfo.y * progress);
		animationLayoutInfo.node.relocate(lX, lY);    	
	});

But now we move the calculation into a static method inside CircularPane. This allows us to configure what animation to use by simply setting a method reference:

	lCircularPane.setAnimationInterpolation(CircularPane::animateFromTheOrigin);

	static public void animateFromTheOrigin(double progress, AnimationLayoutInfo animationLayoutInfo) {
		double lX = animationLayoutInfo.originX + (progress * -animationLayoutInfo.originX) + (animationLayoutInfo.nodeLayoutInfo.x * progress); 
		double lY = animationLayoutInfo.originY + (progress * -animationLayoutInfo.originY) + (animationLayoutInfo.nodeLayoutInfo.y * progress);
		animationLayoutInfo.node.relocate(lX, lY);    	
	}

This is where lambda’s become vague, and IMHO let go of the ideas behind Java. Normally if you move the implementation of an interface from an anonymous class into a formal class, than there is a reference to the implemented interface. This is not the case here; the animateFromTheOrigin method actually implements AnimationInterpolation, but that information is not visible in anyway. It appears as just a method with two parameters, only compiler / EDI errors will show otherwise, and that only after making breaking changes to either the interface or the method. And only if the method is used somewhere! If the method is never used as the interface it implements, no compiler or IDE will be able to figure out that it needs to change when refactoring the interface. I do not like that.

Maybe the static method should explicitly state that it is implementing an interface:

    static public void animateFromTheOrigin(double progress, AnimationLayoutInfo animationLayoutInfo) 
    implements AnimationInterpolation {
		...
    }

Or there should be an annotation similar to @Override

    @Implements(AnimationInterpolation)
    static public void animateFromTheOrigin(double progress, AnimationLayoutInfo animationLayoutInfo) {
		...
    }

Of course this implementing keyword or annotation can only be used for single method interfaces, but now you know that this method is not just any static two parameter method…

For JFXtras I have written test classes that use both methods, thus allowing the IDE to correctly refactor.

Posted in Java, javafx, jfxtras, Lambda | Leave a comment

Round and round she goes

JFXtras has a TimePicker that uses a number of Sliders to represent hours, minutes and seconds. And even though this is functionally an OK user interface, it is visually not very appealing.

TimePickerHM

Recently I upgraded to a new phone and ran into this Android TimePicker, which I liked better than my slider UI. So I figured I would try and create something similar.

android-calendar-time-control-1

The first thing that is needed to create a UI like this, is to layout nodes in a circle. That turned out not to be too difficult, but the implementation was very specific for the circular time picker I was working on. And I figured it would be nice if the circular layout was reusable, so I got side-tracked in creating CircularPane.

CircularPane is a standard JavaFX layout implementation that does nothing more or less than position its children in a (partial) circle, like the JavaFX Buttons example below:

CircularPaneButton

Of course any node can be placed in a circular layout, the example below has some (rotated) primitive shapes:

CircularPaneRectanglesAndCircles

As soon as the nodes are getting more diverse, it becomes less clear if they are placed neatly in a circle. To visualize this better, CircularPane has a debug mode, where it will draw (in this case green) circles around the space allocated to each child:

CircularPaneRectanglesAndCirclesDebug

These circles visualize the layout logic; CircularPane searches for the largest node in its children, and uses that as the basis for the layout. The rectangles in the second and third CircularPane are a good example.
As soon as the largest child has been found, it is used to determine the smallest circle where all children can be placed on, assuming each child has the same space available as the largest child.

Besides using a full circle, it is also possible to instruct CircularPane to place its children in a partial circle, or an arc:

CircularPaneCircles200

Of course a larger diameter circle is needed to place these nodes, but the empty space is automatically clipped away.

Often when a circular layout is used, the nodes being laid out are also shaped as a circle. This allows the nodes to be visually easily positioned anywhere on the circle. But this fact allows for an optimization; nodes in JavaFX are rectangular, they have a width and height. A rectangle is the shape that fully uses a node’s available space. Not knowing what exactly is or will be drawn in a node, CircularPane must assume that any node might use all of its space, so the debug circles encompass the rectangle by basing their size on the diagonal. This can clearly be seen in the second example. But the first example shows that for circular nodes room is wasted: even the largest circle has spare room.

CircularPaneRectanglesAndCirclesDebug

So if all children are circular themselves, a more tight layout logic can be used, and the layout can be based on the width or height of the node instead of the diagonal. This is clearly visible in the first example below, where CircularPane was told that its children were all circular (or smaller):

CircularPaneChildrenAreCircles

With the recent popularity of wearable devices and especially Motorola announcing a round smart watch (the Moto 360, see below), a circular layout may just be what the doctor ordered. CircularPane currently is part of JFXtras-labs (8.0-r2) and will eventually move to JFXtras-layout, once all the tests and samples are in place.

LG360

Posted in Java, javafx, jfxtras, UI | 4 Comments

Named queries are evil

The JPA specification has the concept of named queries which is an attempt to ‘Don’t Repeat Yourself’ (DRY), but in my opinion it is more a ‘Mistake By Specification’.

The fact that a query is written as a string, and therefore is not compiler checkable, is a missed chance (solutions like QueryDSL offer great alternatives here), but not the point I would like to make. My issue is with the ‘named’ part.

The link to named queries above has the following example:

@NamedQuery(
    name="findAllEmployeesByFirstName",
    queryString="SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = :firstname"
)

What you see here is that there is a definition of a query (usually located at the top of the Entity class) and somewhere else the query is used to read employees from the database, like so:

Query queryEmployeesByFirstName = em.createNamedQuery("findAllEmployeesByFirstName");
queryEmployeeByFirstName.setParameter("firstName", "John");
Collection employees = queryEmployessByFirstName.getResultList();

The problem is that the named query in no way enforces or even specifies the parameters it requires. In this case it requires one, and its name of course suggest that, but this is a very thin and unstable relation, and not something I would like to base the stability of my code upon. After all, we all know how easy the name may go out-of-sync to the contents of the query.

What named queries try to prevent is that the query text is present on multiple locations. But the query and the required parameters are tightly related, basically they are a single unit which should not be split.

Because you need Java code anyhow to execute the JPQL query, I believe it is much better to wrap the query text and the parameters into a single method, where the query parameters are identical to the method parameters.

public Collection<Employees> findAllEmployeesByFirstName(String firstName) {
    Query query = em.createQuery("SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = :firstname");
    query.setParameter("firstName", firstName);
    Collection<Employees> employees = (Collection<Employees>)query.getResultList();
    return employees;
}

This puts the query text and the parameters closely together, making it easier to keep them in sync, and (because the query text cannot be reused outside this method) ensuring that any change in the parameters is compiler checkable. It does not really matter if such a finder method is placed in a DAO object, or in a static method on the entity (emulating a named query). What ever suits your taste.

Having argued that named queries are a bad idea, but solely because you need to keep the query and parameters together, could lead to the approach of just scattering queries through out the code, as long as the parameters are there as well. And conceptually this is fine; the premises that ‘the EntityManager is the DAO’ would in fact encourage this. However, there is an additional advantage of moving queries into finder methods; domain level security. Domain level security becomes important when users can have different permissions on different instances of the same class. For example an user in a forum may have edit permissions on his own posts, but he is not allowed to edit posts of another user. And the user also may not be allowed to read post that are part of a shielded forum. Implementing such security, for example using Spring Security – Access Control Lists (ACL), requires checking individual objects. Named queries in their intended use do not have a single place where they are executed -otherwise it would not make much sense using named queries-, and it will be very hard to make sure all query results are processed by the domain level security. But scattering queries all over the place is not very practical either, using DAO classes makes this much easier.

So, to summarize; do not use named queries, they’re evil. But because of future requirements maybe you should not use the EM directly at all and stick to DAO’s.

Posted in Java, JEE, JPA | 2 Comments

The Java 9 named parameter pitch

In the previous post Daan van Berkel again made clear that a fluent API is so much more readable than the “regular” API’s. Unfortunately a lot of projects do not have the luxury of being able to convert their code to the fluent paradigm. But there are some easy improvements possible, one of them would be the introduction of named parameters.

Let me first start with a simple example:

    component.show(false, true);

Well, there is nothing wrong with that code, except as an outsider you have no clue what it is doing exactly. What do the two booleans indicate? This can only be solved by a round trip to the documentation. A fluent API would fix this:

    component.modal(false).centered(true).show();

But a lot of codebases cannot simply be converted to a fluent API, and fluent API’s are not easy to get right in the first place. Some developers improve bad readability by adding inline comments like so:

    show(false /*modal*/, true /*center*/);

That surely improves readability, but it also is very dangerous, because there is no validation that the comments actually match the meaning of the parameters. (Did I just now make an argument against comments, in contrast to my previous blog? Yes I did.) So what actually is needed is something like compiler checked comments; named parameters.

    show(modal:=false, center:=true);

This looks a lot more readable than the first example. What would happen here is that, given that the called method has parameter information available, the compiler would match that against the specified names. If they do not match, or no parameter information is available, named parameters would cause a compiler error. So there cannot be ‘incorrect comments’.

But if the compiler knows what parameters are expected and which are provided, then it can be smart about their sequence: it can rearrange the provided parameters to match the expected. So the compiler can rearrange this call to make it work correctly:

    show(center:=true, modal:=false);

The compiler knows the order of the parameters and at compile time can rearrange them to the correct order, in the end the resulting byte code should still be ‘just’ the old style call:

    component.show(false, true);

This approach is a compiler-only enhancement and perfectly backwards compatible. It improves readability, and allows for changes in the parameter sequence to not cause problems.

A point of attention is when changes are being made to parameters inside a call. In this situation reorder-than-evaluate has different results compared to evaluate-than-reorder. I believe the last is the most natural option, meaning that any expressions are evaluated before the parameters are reordered, so the parameter values match the sequence in the source code. For example assume a method “call(int p1, int p2)”:

    int a = 0;

    // parameters in the correct order:
    object.call(a++, a); // call(0,1)
    object.call(p1:=a++, p2:=a); // call(0,1)

    // changing the order of the parameters:
    object.call(p2:=a, p1:=a++); // call(0,0) evaluate than reorder 
    object.call(p2:=a, p1:=a++); // call(0,1) reorder than evaluate

What you see is that reorder-than-evaluate (4th call) has no influence on the effective method call, while evaluate-than-reorder (3rd call) results in a different call. Changing the order of the parameters should have obvious consequences. So even though the 4th call is identical to the 2nd (changing the order of the parameters at the caller has no effect), this is not the preferred behavior. Changing the order of the parameters at the caller should have obvious consequences; the “a++” happens after p2 has its value assigned, so the 3rd call (evaluate-than-reorder) is the preferred behavior.

A possible issue is the situation where a SNAPSHOT version of a jar contains parameter info, but the actual released jar does not; this would cause compiler errors. But I’d suggest that Java starts including parameter info per default anyhow, I know ctrl-space in IDE’s will greatly benefit from that as well.

Posted in Java | 12 Comments