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 iOS, 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 | Leave a comment

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

To comment or not, that is the question

Recently I worked my way through the “Effective Unit Testing” book. A nice read, nothing too complex or difficult, but it is always good to read the opinions of someone who really put some effort into a certain topic. One point was the question if code should contain comments or not, mainly because comments can have a negative impact because they can be incorrect and misleading. So the proposed solution was to write code that does not require comments at all; write “self documenting code”.

In my current project I run into similar situations on a daily basis; my idea on how code should look differs from the most of the other developers. I see people writing tons of code without a single comment in them and declare them “self documenting”. The problem is that for some reason I do not seem to be able to get comfortable with that code, and I’m really starting to wonder if I’m getting old, and am missing out on the “new and improved way” of doing things. But I’m not one to accept that without an effort, so I gave it a shot.

Below is an example of a simple unit test. Please do not spent too much time on this, because it is the “before” example. But the test is ok, there is nothing technically wrong with it, it just can be written better.

    public void testVerifyGroupThenAddClient() throws ValidateException {
        // group starts off not verified
        GroupCare assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId());
        assertNull(assertGroupCare.getVerifiedAt());

        // add client
        groupCareManager.addClient(groupCare, client.getData(), groupActivity.getData(), user);

        // group is not yet verified
        assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId());
        assertNull(assertGroupCare.getVerifiedAt());

        // verify the group
        groupCareManager.verifyGroupCare(user, groupCare);

        // assert that the group is verified
        assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId());
        assertNotNull(assertGroupCare.getVerifiedAt());

        // add new client
        groupCareManager.addClient(groupCare, client2.getData(), groupActivity.getData(), user);

        // group is no longer verified
        assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId());
        assertNull(assertGroupCare.getVerifiedAt());
    } 

The next step was to apply the best practices according to the “Effective Unit Testing” book to it, which basically comes down to creating simple methods to be called in the test itself, and extract all scaffolding into helper methods. At first glance you will immediately see the improvement, and it most certainly is an improvement. However, now I want you to actually try and understand the test, actually read the code below. Humor me.

    public void testIfAddingClientToVerifiedGroupMakesItUnverified2() throws ValidateException {

        assertNotVerified(groupCare);

        addClient(groupCare, client, groupActivity, user);
        assertNotVerified(groupCare);

        verify(groupCare, user);
        assertVerified(groupCare);

        addClient(groupCare, client2, groupActivity, user);
        assertNotVerified(groupCare);
    } 

I’m very curious if you really have the feeling you understand what is tested in that code, but more importantly how much time and effort it took for you to understand it.

For me, I had been starting at that code for quite some time and it simply did not sit right. Yes, it is a huge improvement over the “before”, but I am used to write code differently: first write out what you intent to do (create a scenario), and then implement that. The big difference is that a scenario is written in a natural language, and natural languages are much easier to read for humans than computer code. And last time I checked (this morning under the shower) I still am human, and not a compiler.

So after I’d given that code a long stare, I decided it needed comments after all, which resulted in the code below. Again, please, read it and tell me which version is easier to comprehend.

    public void testIfAddingClientToVerifiedGroupMakesItUnverified3() throws ValidateException {

        // group starts off not verified
        assertNotVerified(groupCare);

        // when adding a client to the group, then it should stay not verified
        addClient(groupCare, client, groupActivity, user);
        assertNotVerified(groupCare);

        // when verifying the group, then it should become verified (obviously)
        verify(groupCare, user);
        assertVerified(groupCare);

        // when adding a second client to the group, then it should become not verified again
        addClient(groupCare, client2, groupActivity, user);
        assertNotVerified(groupCare);
    } 

So maybe I really am an old dump not being able to catch on to the latest way of writing code, but at least I confirmed that I’m still human ;-)

Update:
Daan van Berkel has pointed out that using a fluent API both in the domain objects and the test library (Hamcrest) will make the example much more readable. And he is right, fluent API’s are a great improvement, as you can see below. The fact is that my current project does not have a fluent API, and fluent API’s can be really difficult to write correctly. Never the less, is the improved example below “self documenting”? Would you have understood what is tested just as easily as the example with the comments?

    public void testIfAddingClientToVerifiedGroupMakesItUnverified2() throws ValidateException {

        assertThat(groupCare, is(not(verified())));

        groupCare.add(client.with(groupActivity)).as(user);
        assertThat(groupCare, is(not(verified())));

        groupCare.verify().as(user);
        assertThat(groupCare, is(verified()));

        groupCare.add(client2.with(groupActivity)).as(user);
        assertThat(groupCare, is(not(verified())));
    }
Posted in Java, unittest | 6 Comments