Bachelor Thesis: WorkbenchFX

Blender is a tool for creating 3D models which are used in animated movies or in game development. It is a tool which requires a lot of skill and is not an "every day" program.

Figure 1 gives a short impression of the program and Table 3 shows our findings.

Adobe Photoshop is probably one of the most widely used tools when it comes to manipulation of photos and creation of digital art. Since it requires some experience to use it properly, it is made primarily for power users. Figure 2 gives a short impression of the program and Table 4 shows our findings.

IntelliJ is an integrated development environment (IDE) which is used to develop a variety of programs. The tool is made for software developers and can only be used if someone is familiar with programming.

Figure 3 gives a short impression of the program and Table 5 shows our findings.

Figma is a tool used for prototyping of user interfaces. Using it is very easy and intuitive. It can used by non power users. Compared to the other applications analyzed before, its tools are fixed and defined. The tools can’t be moved or removed. The design of the software is straight forward and is kept very simple.

It consists of five main sections:

Figure 4 gives a short impression of the program.

Like Section 5.2.4, Adobe XD is a prototyping software. It is also very simple and intuitive. In fact there is not much that differs to Figma. So it can definitely be used by non power users. Figure 5 gives a short impression of the program.

After analyzing all the different programs, we simplify them to the most important and frequent characteristics:

During our research we discovered that there are two different kinds of application types, created for two different types of users.

One user type are power users:

Power users need the utmost of customizability, to ensure they can adapt the workspace to be the most ergonomic to fit their workflow, like in an IDE (Integrated Development Environment). In terms of the architecture, it could mean that it would need to allow the following:

The other user type is the opposite of a power user:

Depending on the required user type, the WorkbenchFX API would look totally different, because both use cases require a different approach on the API design.

During the user story workshop (see Section 5.3) we also decided which application type we would support. As it became clear the user was going to be Anna, we knew that we would not develop an API which allows to build large power user applications like an IDE. Anna can use a computer, but she uses it only as a tool and is not familiar with complex applications. So we had to focus on simple, easy to understand features which are intuitive to use.

WorkbenchFX is considered to be an enterprise application framework in JavaFX, just like Eclipse RCP is as well. However, besides Eclipse RCP being available on the SWT platform, the goals of either are completely different. WorkbenchFX is not meant to replace or augment Eclipse RCP for JavaFX. WorkbenchFX is also neither a successor to Eclipse RCP.

The main focus for WorkbenchFX is to build applications like Customer Relation Management (CRM) software. While Eclipse RCP can also do that, the user group of Eclipse RCP is the power user. It allows flexible re-arrangement of parts of the GUI and features a docking framework. This is ideal for developers, who work entirely in their IDE’s and want to have the most flexibility possible to customize everything.

WorkbenchFX is not as flexible on purpose, since the user group is represented by Anna and she certainly isn’t a power user. She doesn’t want to bother with moving parts of the GUI around, she just wants to get her work done quickly with good user experience out of the box.

Eclipse RCP offers lots of extension points. WorkbenchFX only selectively offers extension points where it makes sense, but still provides good defaults. The goal of WorkbenchFX is to quickly get an application up and running with minimal overhead. Also, it should be possible to use WorkbenchFX without working through hours of tutorials, programming with WorkbenchFX should feel intuitive. Eclipse RCP may offer more flexibility, but requires a lot more configuration and overhead. This also means greater complexity and being more difficult to learn.

In the end, both can lead to the same goal, but they are meant to be used for different purposes.

To plug in functionality by the API user, we use modules. However, as stated in Section 6.1.2, the name Module is not ideal, since that name already has a lot of associations. Additionally, when typing extends Module in an IDE, it will automatically imports Java’s Module. This makes it frustrating, as the implementor has to manually change the import.

To avoid confusion, we want to come up with a name which makes it clearer and less ambiguous. We did a brainstorming to come up with ideas for possible names for Module (Figure 6).

We discussed this with our customer and even though we did the brainstorming and came up with a lot of names, none of them seemed to feel "right". Even though the name Module has a lot of associations, it’s the only name that makes sense for what it stands for. In the end, we decided to rename Module to WorkbenchModule. We thought it would be easier to understand for our API users and that was the most important factor for us in this decision. This is why we decided to stick with the word Module. However, we decided to add the Workbench prefix, to remedy the importing issue mentioned above and to clearly separate it from the other Module classes in the JDK.

We chose the name "Navigation Drawer" to be consistent with the naming in the Material Design guidelines. This makes sure we use the naming that will be the most familiar among other developers and is easily understandable. An additional benefit is that if someone doesn’t know what it means, they can simply look it up in the Material Design guidelines.

During the "Hacking Days", we’ve had from time to time (more about them in Section 8.3), our advisor tested the API by implementing a module on his own. This showed us some weaknesses in the API design. We found two important findings, which are described in the following subchapters.

The biggest impact on the WorkbenchFX styling came from a UX expert. A lot of the feedback he gave us was really helpful and we decided to adopt a lot of it.

She was happy using the API which motivated and showed us that we’re on the right way.

We decided to stick with the modular concept of having multiple views and switching between them using tabs. This concept is widely used. Most of the applications analyzed in Section 5.2 use the tab concept to switch between their files. Also, common internet browsers like Google Chrome or Firefox use the tab system too.

Having a page which allows the user to open a new module is also commonly used. For example, smartphones use the same kind of concept when they display icons of installed apps on the home screen and open them on click.

For this reason we decided to go with a system, where the user can click on a certain button, which opens an overview with all of the modules shown in a grid. Clicking on one of the modules, represented as buttons (called Tile) opens the corresponding module. This way, the user has a good overview on all the modules and can easily open them.

Going with this concept led to a discussion about the names of the components. When we described the concept, we struggled with the naming of the module. Viewed objectively, the complete application built with WorkbenchFX consists of multiple "mini applications". For obvious reasons we could not name the module MiniApplication or even Application. An API user could be confused about the difference between the application (Workbench) itself and the "mini applications". So we had to find a better name. In the end we chose WorkbenchModule, which also was not the best solution, since the name "module" has a lot of associations. But it is definitely a better choice than "Application" (the complete naming process is described in Section 5.5.1).

When there are a lot of modules, the available space on the page would shrink quickly and the usability would also suffer because of the buttons becoming too small. For this reason, we introduced a pagination to only have a restricted amount of modules displayed on a page.

There are three major changes mentionable which appeared during the project.

Our most important goal was to enable Fabian to style the workbench in a simple way. Of course, he would not take advantage of all of the styling possibilities. But we thought he might want to change at least the default color theme of the workbench.

We wanted to have Fabian only change a few color values to completely restyle the whole application consistently. To achieve this, we worked with CSS variables. We defined all of the color variables in the .root > * selector of the CSS file and only used those variables throughout the whole stylesheet.

During the definition of the color variables, we discussed their names and usage in the workbench. In the end, we decided to go with the Material Design naming convention of colors and use them as defined [5]. This way, every API user is able to research on how to use the variables and in which context they are used.

By simply using the color variables, Fabian can create a custom stylesheet, assign it to the workbench and overwrite the colors he wants to change.

SteffiFX on the other hand might want to style the application a bit more. To account for this use case, we gave every component used in the workbench at least an #id or a .class name. This way, SteffiFX is able to restyle the complete application if she likes to do so.

Since we want to enable the API user to customize the workbench as much as possible, we need to think about in which way the API user should need to interact with our API to do so. Of course, the resulting API design from this needs to work with our implementation as well. When we implemented the pagination on the add module page, we wanted the API user to be able to choose the amount of modules shown per page. To do so, our initial idea was to design the API for creating a Workbench object like this:

This would be very easy to use, but it turned out to be not practical, since the GridPane with the module tiles are being initialized in the constructor of Workbench. Changing the amount of modules per page after the constructor was called, would mean that we would have needed to rebuild all of the pages with the modules again. This is not only very inefficient, but also a very bad solution for this problem.

Another way of solving this would’ve been to initialize the Workbench object with a separate method after setting the amount of modules per page, like this:

This would mean that the GridPane with the tiles would only need to be built once. However, this solution is also not very elegant. If the API user doesn’t want to set the amount of modules per page, they still need to call init(). Also, in this case the API user must remember to call init(), which is easy to forget.

One of the better options would be to solve it like this:

We would simply pass in the amount of modules to the .of() method. This would work, however it has some disadvantages. For example, the readability suffers: "What does that 10 mean again?". Also, since we want the API user to be able to define their own controls for the tabs and tiles using factories, we noticed that we also need to pass those factories in the same way. This would not only make the readability worse, this also means that if we would want Fabian to be able to define the workbench with the least effort possible, we would need to add multiple overloaded of() methods. With 3 parameters (modules per page, tab and tile factory) this would result in the combinations in Table 11.

Only 3 parameters result in 7 overloaded of() methods, which is already quite a lot. Should we need to add more parameters in the future, it would get even worse.

This is why we decided to go with our final solution, to use the builder pattern. Using it results in the following syntax:

This solution solves all of the problems. It’s not possible to forget build(), since else it won’t return a Workbench object. It’s expandable to a large amount of parameters. It allows for maximum flexibility, i. e. any combination of the parameters in any order can be specified. We decided against keeping the original Workbench.of(module1, module2) notation, since using the builder doesn’t require a lot more code and doesn’t introduce more complexity.

The following UML diagrams explain how the lifecycle of a WorkbenchModule works. The diagrams are simplified to a degree that is relevant for the implementor of a WorkbenchModule and are not complete and not exhaustive by design. The goal is to explain the principle of interactions on modules when using workbench.openModule(WorkbenchModule) and workbench.closeModule(WorkbenchModule) with a minimal amount of examples.

Generally, when clicking on a tile in the AddModuleView, workbench.openModule(WorkbenchModule) gets called.
When clicking on the x icon of a tab, workbench.closeModule(WorkbenchModule) gets called.
When a WorkbenchModule has to perform cleanup actions or needs to show a dialog before it can be closed, the closing process needs to be interrupted. To interrupt the closing process, the implementor has to return false on module.destroy(). When the closing process gets interrupted, the module will not be closed and will be set as the active module. The implementor doesn’t have to call any of the lifecycle methods, the calls are being made by the Workbench.

Overview of the lifecycle in a state diagram, showing all state changes that can occur (Figure 9).

Process of opening two modules in sequence, followed by opening the first module again (Figure 10).

Two open modules, closing of the active module (Figure 11).

Two open modules, closing of the inactive module (Figure 12).

Two open modules, closing of the active module, where the call to module.destroy() returns false (Figure 13). This leads to the closing process getting interrupted. The implementor of WorkbenchModule can then choose to do cleanup actions or open a confirmation dialog, following a call to module.close(), when the module should definitely be closed.

Two open modules, closing of the inactive module, where the call to module.destroy() returns false (Figure 14). This leads to the closing process getting interrupted. The module which interrupted the closing process will be opened, so that the user’s attention will be directed towards the interrupting module, so they can take appropriate actions.

To learn more about the interactions in detail, look at the tests below, since the tests verify the exact order of the calls and cover more situations in detail:

As with the design of the lifecycle, having a simple and easy to understand API overall for WorkbenchModule is very important to us. If there is a lot of code with a lot of methods in the WorkbenchModule class, it could make it harder for people to understand how to use the API and how it works. This is why we very carefully introduced complexity into a WorkbenchModule, and only added what really enhanced the user experience to a point that would justify the added code. We also considered to only add methods which are needed to fulfill a certain use case, which is likely to occur.

To specify an icon for a WorkbenchModule, there are different ways to implement this in the API.

Model View Presenter (MVP) was used as general architecture pattern. We thought it would be excessive to use the Control and Skin architecture from JavaFX for all internal views as well, especially since they don’t have to be replaceable (see Section 5.6). But at the same time, we wanted the views to be separated to be more readable and maintainable. We chose the MVP pattern because we used it in the PreferencesFX project and it proved to be very good for those purposes. This is why we still chose to use the MVP pattern for all internal views.

At first, we used a separate WorkbenchModel object for the model. Our customer suggests that it would be easier to skip the WorkbenchModel class and just put the logic in Workbench, since that’s the place where he would expect such logic. We decided to change it in a way that Workbench is the model object in the MVP pattern in our case. This simplifies the architecture and readability is improved, since methods are where they are expected.

View is an interface, because it’s being used as a mixin. We implemented it this way because every view needs to already extend a certain JavaFX class and multiple inheritance is not possible in Java, so using an abstract class here isn’t an option. This makes it possible to initialize all views in the same way, while also resulting in less code duplication, since the init() method and the JavaDoc doesn’t need to be rewritten over and over again.
Presenter is abstract, because it acts more like a "super class" of all the presenters. Since all presenters don’t need to extend anything else, using an abstract class is possible.

To enable the API user to easily show a custom overlay with a black transparent GlassPane in the background, they can use the respective workbench.showOverlay() and workbench.hideOverlay() methods. The GlassPane prevents click events on the components below and adds a scrim to the background. Unless a blocking (modal) overlay is being displayed, clicking on the GlassPane closes the overlay.

The GUI of WorkbenchFX is organized in layers. At all times, there is a layer of the general WorkbenchFX GUI, which is being represented by the view class WorkbenchView.

When showing an overlay, a GlassPane is added to the scene graph and shown on top of the WorkbenchFX GUI, followed by the overlay itself on top of the GlassPane. This ensures there is a "scrim"[10] between the WorkbenchFX GUI and the overlay (Figure 15).

When hiding an overlay, it is made invisible and is not removed from the scene graph, so recurring overlays don’t need to be re-inserted into the scene graph again. This is more efficient and especially overlays with animations profit from this design, since they run smoother when shown and hidden multiple times. In case of an application with very memory-intensive overlays, there is a possibility to call workbench.clearOverlays(), which will remove all overlays from the scene graph and free them up to be garbage collected.

Each overlay has its own GlassPane and it is possible to open multiple overlays on top of each other.

The programming is being done in a GitHub repository. We work using the git flow branching model [11]. Every change is represented in a pull request to develop from the feature branches.

To improve the quality of the code and also ensure collective code ownership, every pull request gets code reviewed by the other person. This worked very well for us, since comments that are made by the other person always lead to improvements and code of higher quality.

In web development the transpiler SCSS to CSS is commonly used. But we were not finding much information about using it in JavaFX projects. But because SCSS is:

We decided to give it a try.

For example, in an application with two views in one larger view. All three views have some default colors. If we want to change the colors on hover, we would need to write the following CSS code:

The code appears to be redundant and is not very readable. SCSS on the other hand:

It is much easier to read thanks to the nested code. The code is also more maintainable. When additional styling is required, it can simply be added. SCSS becomes more useful and powerful as the complexity of the stylesheet increases.

In order to maintain a well structured styling, we agreed on several conventions. The most important are described in the following subchapters.

Most of our unit testing, especially in the beginning, was done with JUnit. However, there were some test cases that were data-driven. JUnit 5 does have data-driven testing capabilities, but it doesn’t offer much flexibility and the way tests have to be implemented to be data-driven is not very readable [12]. An example can be seen in Parameterized Tests with JUnit 5 [12].

Also, JUnit 5’s data-driven testing API is still considered "experimental" [12]. We didn’t want to risk all of our data-driven tests becoming obsolete, should JUnit later choose to change the concept entirely. Combined with the readability argument, we decided not to do data-driven testing with JUnit.

At first, we proceeded to write the data-driven tests as usual with JUnit. But the tests had a lot of of duplicated code and therefore were not very maintainable (see Figure 16). So we decided to invest some time to find a better solution.

We already knew Spock as a testing framework, but we have never used it before in a Java context, since Spock is written in Groovy. However, Spock has one big advantage over JUnit: Data driven testing is very well implemented. Parameters in data-driven tests are implemented in a table-like format (see Figure 16). A test case can be built fully parameterized, which means the tested method and assertions only need to be written once. Spock will then dynamically run the test case multiple times with each row of the table-like data structure as parameters [13]. This makes the code much more readable and maintainable. It also means adding another data set after the fact just means adding another row to the data, not copying and modifying unit test code over and over again.

However, it was still unclear whether we could use Spock to test Java code and even more so JavaFX applications, which are already more difficult to test in our experience. In theory it should be possible, as Spock claims on their website [14]. Also, TestFX (see Section 7.2.2) offers support for Spock, so it seemed like a viable option. We did some research on GitHub, but we didn’t find any Java projects which used JUnit 5 together with Spock and Maven. After a lot of challenges, we were able to make it work. The key part to the solution, was that we needed to add the JUnit Vintage Engine, which is the engine that enables to run JUnit 3 and 4 tests [12]. Everything that was needed to make it work can be seen in the pom.xml file of workbenchfx-core

However, the end result was well worth the effort. We rewrote the data-driven JUnit 5 test with a lot of duplicated code mentioned above with Spock and compared both in Figure 16.

Not only is the unit test written with Spock much more readable, but also easier to maintain. The output is much easier to read with Spock as well, since it creates a separate test for every row in the parameters.

There were a few testing utilities we used to augment the already existing features of JUnit and Spock.

To simplify the code review process, we are using Travis CI. Travis CI is a build server similar to Jenkins. Compared with Jenkins, it runs in the cloud and is much more straight forward to set up in our experience. The biggest advantage is the tight integration with GitHub, which for example allows automatic building of pull requests. GitHub then directly shows the build status in every pull request and we also set up that a pull request can’t get merged until the build passes. With every build, Travis will compile the code, run checkstyle and tests.

We agreed with our customer to use the Google Java Code Style guidelines, as they are used in one of the most-widely used libraries in Java, Guava [15], and because of its well-maintained open source checkstyle configuration on GitHub [16]. If checkstyle finds code style violations, we set it up to fail the build. This provides us with immediate feedback when we open a new pull request and forget to run checkstyle checks ourselves. Also, it makes it easier for the reviewer, since they don’t need to run the tests and checkstyle themselves every time.

In order to get build results from Travis faster, we enabled "Auto Cancellation". If there are a lot of pushes from the same branch or pull request, Travis will then cancel all but the most recent build in the queue for each branch or pull request.

Travis makes two checks each time there is a push to the repository. The first check is the "push-check", which tests the compatibility of the current branch (Figure 17) [17]. The second one is the "pr-check", which emulates a merge with the target branch in order to check if the merge leads to errors making the build fail (Figure 17) [17]. This has the huge advantage that our work is not only easier, but also safer to accomplish.

Since testing was one of our main tools to ensure good code quality, we wanted to also make use of code coverage. This is where codecov.io came in. It’s a platform that visualizes code coverage and also integrates nicely with GitHub and Travis. The code coverage itself is measured by JaCoCo and is specified in the pom.xml of workbenchfx-core. We set it up so that every successful Travis build would push the code coverage to codecov.io. Thanks to the GitHub integration, a codecov bot would create a comment on every pull request, that gets updated with pushes to the branch of the pull request (Figure 18). Also, codecov.io would show a "check" in GitHub and would only pass if certain conditions are met. One of those is that the code coverage must not be lower than it previously was (Figure 19). The other one was the diff coverage, that measured how much of the added code was covered (Figure 19).

Codecov.io also enables to set exceptions on certain classes, which should not be taken into account for the code coverage. We mainly did this for view classes, since they cannot really be unit-tested. Also, we added abstract classes and interfaces to the exceptions, since it wasn’t possible for JaCoCo to recognize executions of lines in them. See Codecov.io Exceptions for all of the concrete classes we removed from code coverage.

We didn’t set a goal for the code coverage per se, since we didn’t want it to lead us to try to test everything. But in general, we tried to keep the code coverage over 90%, which is already quite high. In the end, we were able to reach a code coverage of 94.51%.

We realized code coverage is a useful tool, but you can’t solely rely on it. For example, if we added a lot of new fields with mutators and accessors, we noticed we almost always weren’t able to meet the goals defined by codecov.io in the GitHub checks. This is because getters and setters are not tested [18, P. 11]. This leads to the coverage results getting skewed, since there is more code that is also not covered, reducing the code coverage. In this case, it is the creator of the pull request’s responsibility to check, whether there is untested code that needs to be covered or if it is just the mentioned effect. Also, it is the reviewer’s responsibility to validate the creator’s decision in this regard, as sometimes checking the code coverage can be forgotten. If the results were skewed, we went with the pragmatic approach and chose to still merge the pull request. This approach worked very well for us and our decision payed off, given the high code coverage we reached.

Still, code coverage can be a double-edged sword. As we saw, lower code coverage doesn’t always equal less code quality. We realized this is also true for the opposite. Simply because a line of code was executed during a test, doesn’t necessarily mean it was tested properly. That’s where code review comes in, and we had to remind ourselves constantly to not rely on code coverage too much. We still need to check whether all of the edge cases have been tested and if the tests really perform all necessary verifications.

However, using codecov.io proved to be really useful to us. We had a quick overview over the code coverage and as with Travis, it was one step less in our code review process. We didn’t always have to build the branch to see the code coverage and the checks on GitHub doubled as a reminder to have a look at the code coverage.

Over time, we established the following process for releases:

We also automated parts of the release process with Travis. When we push a git tag on the master branch, Travis will run mvn install, make zips of the documentation and javadoc, followed by creating a release on GitHub and uploading the zips along with the built jars. The only thing left is to edit the title and description with the release name and its changelog, respectively (see Section 7.4.1).

Details on the implementation can be found in the .travis.yml file.