Drombler Commons: JavaFX controls for the new Date & Time API (JSR-310)

I managed to open source and release two more libraries I mainly worked on in spring 2012. They form the first 2 components of this first Early Access version of Drombler Commons: Drombler Commons - FX - Core and Drombler Commons - FX - Date and Time.

Drombler Commons - FX - Core

This component contains various JavaFX utility classes.

Note that this component is still very experimental as I'm trying to figure out what works best with JavaFX.

Among others it contains:

• LimitedComparableProperty: a JavaFX property class for Comparables with an optional min and max value.
• DataRenderer Framework: a framework which allows to reuse data rendering implementations across various controls and cell factories. There is already support for various controls including an IntegerField, a list cell factory and support for sub-classes of Labeled.

The library is available from Maven Central (along with the sources and javadoc artifact):

<dependency> <groupId>org.drombler.commons</groupId> <artifactId>drombler-commons-fx-core</artifactId> <version>0.1</version> </dependency> The library contains the necessary OSGi meta data and thus is ready for use in a Drombler FX application, but it should also be useable outside an OSGi framework.

Drombler Commons - FX - Date and Time

This component is an extension of Drombler Commons - FX - Core and provides controls and DataRenderers for the new Date and Time API (JSR-310), which is planned to be added to the upcoming Java SE 8 release.

This library provides the following custom controls:

• MonthOfYearComboBox: a ComboBox to choose an instance of the MonthOfYear enum.
  The text representations of MonthOfYear are locale sensitive (as provided by the Date and Time API).

• YearField: a TextField for Year.

• YearMonthSpinner: a skinnable Spinner control for YearMonth.
  The default Skin provides optional Buttons to spin through YearMonth instances and provides a MonthOfYearComboBox and a YearField to let the user change the MonthOfYear and Year directly.
  The text representations of MonthOfYear are locale sensitive (as provided by the Date and Time API).

• LocalDateFixedYearMonthChooser: a skinnable Control which allows the user to select a LocalDate in a given YearMonth.
  As the complicated name hints, this control is intended as a building block for other controls rather than to be used in applications directly.

• LocalDateChooser: a skinnable Control which allows the user to select a LocalDate.
  The default Skin combines a LocalDateFixedYearMonthChooser with a YearMonthSpinner.
  
  The first sample of this control uses the following configuration:

• selectedDate.max: now.plusWeeks(3) (now=3rd April 2013)
• selectedDate.min: now.minusMonths(19) (now=3rd April 2013)
• previousMonths: 1
• nextMonths: 1
• locale: en_US (English, United States)

This sample shows three months at a time: the current year month + 1 previous month + 1 next month.
Note that the previous year and the previous month scroll buttons are only shown for the first chooser and the next year and the next month scroll buttons are only shown for the last chooser. The other scroll buttons are hidden.

Since the selectedDate property is a limited property, you can specify an optional min and max date.
Note that the MonthOfYearComboBox limits the possible values depending on the values set for the min and max date. (Here: the max YearMonth of the center chooser is April 2013, so the possible values for MonthOfYear in 2013 for the previous chooser are: January - March).
Also note that the year and the month scroll buttons get enabled and disabled depending on the values set for the min and max date. (Here: the year scroll button on the right hand side is disabled.).
The day buttons are also disabled if the dates are out of range (here: the day buttons are disabled from 25th April 2013 onwards).

As some months span up to 6 weeks, at least 6 weeks are always shown, where the first week is the week with the first day of the month.

The week of the year is shown on the left-hand side.

The dates are colored differently depending on if they are in the shown month or not.

Here is another sample of the same control with the following configuration:

• previousWeeks: 2
• nextWeeks: 1
• showingWeekOfYear: false
• showingYearScrollButton: false
• locale: de_CH (German, Switzerland)

This sample only shows a single month at a time.

The previousWeeks and the nextWeeks are added to the standard 6 weeks, so this sample shows 9 weeks.

Note that in this sample, the week of year column at the left-hand side of the control and the year scroll buttons of the YearMonthSpinner are hidden.

Also note that not only the days of the week and the months are now shown in German, but the week starts now with Monday, where when using the en_US locale the week starts with Sunday.
All this locale-sensitive information is provided by the Date and Time API.

• LocalDatePicker: a skinnable Control which provides a text field and allows to pick the LocalDate from a control.
  The default Skin uses a LocalDateChooser in a pop-up window. You can specify a DataRenderer to format the LocalDate in the text field. Note that the text provided by the default DataRenderer is locale sensitive (as provided by the Date and Time API).

This components also provides 3 DataRenderers:

• DayOfMonthRenderer: a DataRenderer for LocalDate based on its getDayOfMonth()-method.
• MonthOfYearRenderer: a DataRenderer for MonthOfYear.
• YearRenderer: a DataRenderer for Year.

The following packages provide some utility classes:

• org.drombler.commons.time.calendar: utility classes for classes in the javax.time.calendar package.
• org.drombler.commons.time.calendar.format: utility classes for classes in the javax.time.calendar.format package.

The library is available from Maven Central (along with the sources and javadoc artifact):

<dependency> <groupId>org.drombler.commons</groupId> <artifactId>drombler-commons-fx-time</artifactId> <version>0.1</version> </dependency> The library contains the necessary OSGi meta data and thus is ready for use in a Drombler FX application, but it should also be useable outside an OSGi framework.

In order to use the Date and Time API jars inside an OSGi framework, you need to register the system packages. In a Drombler FX application you can add the following configuration to your drombler-fx-application module:

src/main/resources/config.properties

org.osgi.framework.system.packages.extra=${jfx-${jfx.specification.version}}, ${javax-time-jsr-310-ri-0.6.3} javax-time-jsr-310-ri-0.6.3=javax.time.i18n;uses:="javax.time.calendar,javax.time,javax.time.calendar.format", \ javax.time.calendar.format;uses:="javax.time,javax.time.calendar,javax.time.calendar.zone", \ javax.time.calendar.zone;uses:="javax.time.calendar,javax.time,javax.time.calendar.format", \ javax.time.calendar;uses:="javax.time.calendar.format,javax.time,javax.time.calendar.zone", \ javax.time;uses:="javax.time.calendar.format,javax.time.calendar"
Since the Date and Time API jars replace some core classes, you need to specify the jars on the bootclasspath. On the command line you can add the following java command line argument:

-Xbootclasspath/p:<JAVAX_TIME_0_6_3_HOME>/jsr-310-ri-0.6.3.jar:<JAVAX_TIME_0_6_3_HOME>/jsr-310-TZDB-all-0.6.3.jar
where <JAVAX_TIME_0_6_3_HOME> is the parent directory of the Date and Time API jars.

If this path is stored in an environment variable you can use ${env.JAVAX_TIME_0_6_3_HOME} when you're using the Exec Maven Plugin to run your application.

Project

The aggregated Javadoc of both components can be found here: http://www.drombler.org/DromblerCommons/docs/site/0.1/apidocs/

The source code can be found here.

Possible Next Steps

• Visual enhancements: the controls could use some more styling

• API enhancements: the API needs to be evaluated. Is the existing API fine? Should something be added? It's also not clear to me right now what parts should be configurable via API only, what parts via CSS only and what parts via API and CSS.

• Migrate to Java SE 8: the latest released JARs and Javadoc of the Date and Time API are quite old. But since spring 2012, when I wrote most of this Drombler Commons code, most if not all code of the Date and Time API has been integrated into Java SE 8. So the Drombler Commons code should be migrated to Java SE 8 as well.

• Earlier this year a new JavaFX issue has been filed requesting to add a DatePicker control based on the new Date and Time API and people started to work on this issue already.
  I will check the scope of this issue and if some Drombler Commons code can contribute to solve this issue.

When a core API such as the Date and Time API gets "replaced", you must make sure it integrates well with the existing libraries and frameworks.

The  Drombler Commons - FX - Date and Time component provides this integrations for JavaFX and shows that, at least with some additional utility methods, the new Date and Time API is fit for that job.

But I would like to read more about how to integrate the new Date and Time API with other frameworks as well, such as:

• Controls for Web GUI toolkits such as JSF
• JAXB: There is a guide how to replace XMLGregorianCalendar with java.util.Calendar or java.util.Date and there are the DatatypeConverter and the DatatypeFactory classes which help to convert to and from XML data types.
  But I haven't found a guide or helper classes to convert to and from the new Date and Time API, yet, though. Especially one which doesn't involve the now legacy API java.util.Calendar and java.util.Date.
• JDBC: It's great to see that java.sql.Date, java.sql.Time and java.sql.Timestamp already provide some support for the new Date and Time API. But then, is this enough? Or maybe it would be useful to have some direct support in classes such as PreparedStatement and ResultSet as well?
• JPA: JPA provides support for java.util.Calendar and java.util.Date using the Temporal annotation and the TemporalType enum. The next JPA specification after the Java SE 8 release should add support for as many classes of the Date and Time API as possible, so that these classes can be used in JPA entities as well (the JPA specification is currently part of the Java EE specification and not part of Java SE).

JavaFX: Using the JavaFX Doclet with Maven

The Oracle JDK ships with a JavaFX Doclet for the Javadoc tool. This doclet provides special support for JavaFX properties.

To use the JavaFX doclet you can add the following snippet to the pluginManagement section of your parent POM of your JavaFX project:

<pluginManagement> <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.9</version> <configuration> <additionalJOption>-J-Djavafx.javadoc=true</additionalJOption> <doclet>com.javafx.tools.doclets.formats.html.HtmlDoclet</doclet> <docletPath>${env.JAVA_HOME}/lib/javafx-doclet.jar</docletPath> <show>private</show> <links> <link>http://docs.oracle.com/javafx/2/api/</link> </links> </configuration> </plugin> ... </plugins> </pluginManagement>
The JavaFX Doclet tutorial provides addtional information about the doclet.

Note that at the time of writing the tutorial mentions the outdated package name com.javafx.lib.doclets.formats.html.HtmlDoclet.
I already sent a feedback and asked Oracle to update the tutorial.

As the tutorial mentions, you can add the Javadoc to the private properties fields and it will generate the Javadoc for the property-method as well as for the getter and setter methods. To make this work you have to use <show>private</show> in the configuration as I've shown in the Maven snippet.

Alternatively it also seems to work when you add the Javadoc to the property-method (the Javadoc for the getter and setter method will be generated as well).

As this doclet doesn't seem to generate any Javadoc for any private-members (such as non-property-fields and -methods) even with <show>private</show>, the two options seem to be equivalent

Drombler FX: building modular JavaFX applications with OSGi and Maven

If you have ever learned to use a modular Rich Client Platform such as the NetBeans Platform (Swing based) or Eclipse RCP (SWT based) it's likely you wouldn't want to write rich clients in any other than in a modular way.

And so I'm happy to announce the availabilty of a first Early Access version of Drombler FX. Drombler FX is a modular Rich Client Platform for JavaFX based on:

• OSGi: OSGi is the de facto standard for writing modular software in Java.
• Maven (POM-first): Drombler FX applications can be build with Maven. The build follows the standard POM-first approach (the OSGi meta data will be generated for you). A custom Maven Plugin will help you to easily create JavaFX applications with Maven. A custom Maven Archetype will help you to get started.
• Declarative programming model: Annotations can be used at many places to register elements such as menus, toolbars and GUI components.

The first use case supported by Drombler FX is building standard desktop applications: applications with a menu bar, possibly several toolbars and a content pane with tab panes in nested split panes.

There's a Getting Started page which explains how to create, build and run a Drombler FX sample application with a few simple steps.

In addition, this Early Access release of Drombler FX provides initial versions of the following frameworks:

• Actions, Menus and Toolbars Framework
• Docking Framework
• Context Framework

You can use the Drombler Forum for questions and discussions.

If you find issues or have enhancement requests, you can file a ticket here: http://issues.drombler.org.

Note: As this is an Early Access release, all APIs might be subject to change.

News from the Software Smithy: Version 0.3 released

SoftSmithy news: I recently released a new version of the SoftSmithy Utility Library and the SoftSmithy Development Utility Library.

In addition to the API updates, a lot of migration work has been done:

• Project migration: Bundle split: softsmithy-lib-awt project added
• Project migration: Bundle split: softsmithy-lib-beans project added
• Project migration: Bundle split: softsmithy-lib-swing project added
• Project migration: Bundle split: softsmithy-lib-swing-customizer project added
• Several Swing - Customizer classes were moved to different packages. All Swing - Customizer classes are now in the package or subpackages of org.softsmithy.lib.swing.customizer.*
  

Note that for easier version management the version of the SoftSmithy Development Utility Library is aligned with the version of the SoftSmithy Utility Library. As the SoftSmithy Development Utility Library has a dependency on the SoftSmithy Utility Library it's recommended to use the same version of both libraries until the APIs are stable!

I've added a new Positionable Framework and several small fixes and clean-ups.

You can download the archives (including the jars, documentation, samples etc.) and read more about the changes here:
SoftSmithy Utility Library v0.3 (online documenation)
SoftSmithy Development Utility Library v0.3 (online documentation)

I deployed the artifacts (including source and javadoc artifacts) to Maven Central. You can use the following dependencies:

For the SoftSmithy Utility Library - Core:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-core</artifactId> <version>0.3</version> </dependency>

For the SoftSmithy Utility Library - AWT:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-awt</artifactId> <version>0.3</version> </dependency>

For the SoftSmithy Utility Library - Beans:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-beans</artifactId> <version>0.3</version> </dependency>

For the SoftSmithy Utility Library - Persistence:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-persistence</artifactId> <version>0.3</version> </dependency>

For the SoftSmithy Utility Library - Swing:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-swing</artifactId> <version>0.3</version> </dependency>

For the SoftSmithy Utility Library - Swing - Customizer:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-swing-customizer</artifactId> <version>0.3</version> </dependency>

and

For the SoftSmithy Development Utility Library (usually with scope = test):
<dependency> <groupId>org.softsmithy.devlib</groupId> <artifactId>softsmithy-devlib-core</artifactId> <scope>test</scope> <version>0.3</version> </dependency>

News from the Software Smithy: Version 0.2 released

SoftSmithy news: I recently released a new version of the SoftSmithy Utility Library and the SoftSmithy Development Utility Library.

In addition to the API updates, a lot of migration work has been done:

• Project migration: Java SE 6 -> Java SE 7, so you need Java SE 7 to use the latest version.
• Project migration: OSGi metadata added
• Project migration: Maven 2.2.1 -> Maven 3.0.4
• Project migration: artifactId prefix added: "softsmithy-". Since this is automatically also the prefix of the JAR files, it will now be easier to distinguish SoftSmithy JARs from other JARs.
• Project migration: softsmithy-lib-persistence project added and moved the org.softsmithy.lib.persistence package from softsmithy-lib-core to softsmithy-lib-persistence. This has the effect that softsmithy-lib-core has only dependencies on the standard libraries while softsmithy-lib-persistence also has a dependency on javax.persistence version 2 or higher. In an OSGi environment the dependencies are enforced.

Note that for easier version management the version of the SoftSmithy Development Utility Library are aligned with the version of the SoftSmithy Utility Library. As the SoftSmithy Development Utility Library has a dependency on the SoftSmithy Utility Library it's recommended to use the same version of both libraries until the APIs are stable!

I added new utility methods, classes and framework updates for working with the new NIO File API introduced in Java SE 7, service providers, text parsers and formatters and more.

In addition there are new samples and tutorial updates and fixes.

You can download the archives (including the jars, documentation, samples etc.) and read more about the changes here:
SoftSmithy Utility Library v0.2 (online documenation)
SoftSmithy Development Utility Library v0.2 (online documentation)

I deployed the artifacts (including source and javadoc artifacts) to Maven Central. You can use the following dependencies:

For the SoftSmithy Utility Library:
<dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-core</artifactId> <version>0.2</version> </dependency>
and <dependency> <groupId>org.softsmithy.lib</groupId> <artifactId>softsmithy-lib-persistence</artifactId> <version>0.2</version> </dependency>
For the SoftSmithy Development Utility Library (usually with scope = test):
<dependency> <groupId>org.softsmithy.devlib</groupId> <artifactId>softsmithy-devlib-core</artifactId> <version>0.2</version> <scope>test</scope> </dependency>

News - OpenJFX: Better Skin support in OSGi-environments

Great news from the OpenJFX project: my patch (with refinements from Oracle and other community members) to load custom Skins in an OSGi-environment has been pushed to the OpenJDK/ OpenJFX/2.2/master/rt repository and integrated into the JavaFX 2.2 Developer Preview .

Here is the according JIRA issue: RT-14177

OpenJFX is Oracle's effort to open source JavaFX, the next-generation GUI toolkit to create Rich Internet Applications (RIA) on top of the Java SE platform.
OpenJFX is a part of the OpenJDK project (Oracle's effort to open source the Java SE platform).

For me, working on this patch not only helped to unblock Skin-loading in OSGi-environments, but also showed that through the OpenJFX project Oracle is working on JavaFX together with the community.

It's not very hard to get started with OpenJFX development, although the Getting Started page is slightly out-dated. You will have to replace '2.1' with '2.2' to get the current development branch. I encourage the community to help to improve JavaFX.

News from the Software Smithy

SoftSmithy news: I recently released a new version of the SoftSmithy Utility Library and the SoftSmithy Development Utility Library.

In addition to the library updates, a lot of migration work has been done:

• Project migration: Ant -> Maven
  
• Project migration: Subversion -> Mercurial
  
• License upgraded: SPL -> CDDL
  
• Project versioning aligned with Maven versioning, starting with v0.1
• Project layout restructured

For easier version management I aligned the version of the SoftSmithy Development Utility Library with the version of the SoftSmithy Utility Library. As the SoftSmithy Development Utility Library has a dependency to the SoftSmithy Utility Library it's recommended to use the same version of both libraries until the APIs are stable!

I added new utility methods, classes and framework updates for locale-sensitive sorting, object matching, Swing JTable row headers, streams, lists, unit tests and more.

You can download the archives (including the jars, documentation, samples etc.) and read more about the changes here:
SoftSmithy Utility Library v0.1 (online documenation)
SoftSmithy Development Utility Library v0.1 (online documentation)

Since the project is now built with Maven, I deployed the artifacts (including source and javadoc artifacts) to Maven Central. You can use the following dependencies:

For the SoftSmithy Utility Library:
<br /> <dependency><br /> <groupid>org.softsmithy.lib</groupid><br /> <artifactid>lib-core</artifactid><br /> <version>0.1</version><br /> </dependency><br />

For the SoftSmithy Development Utility Library (usually with scope = test):
<br /> <dependency><br /> <groupid>org.softsmithy.devlib</groupid><br /> <artifactid>devlib-core</artifactid><br /> <version>0.1</version><br /> <scope>test</scope><br /> </dependency><br />