Vojtech Ruzicka's Programming Blog

Java Records (JEP 359)

Mon, 03 Feb 2020 22:12:03 GMT

The problem

One of the issues with Java is its verbosity and the amount of boilerplate code needed. That's nothing new.

Let's consider a simple Cat class in Java. We want each cat to have:

Name
Number of lives
Color

Quite simple, right? Now let's look at the code in Java. For simplicity, let's make our class immutable - no setters, we'll set up everything in our constructor.

public final class Cat {
    
    private final String name;
    private final int numberOfLives;
    private final String color;

    public Cat(String name, int numberOfLives, String color) {
        this.name = name;
        this.numberOfLives = numberOfLives;
        this.color = color;
    }

    public String getName() {
        return name;
    }

    public int getNumberOfLives() {
        return numberOfLives;
    }

    public String getColor() {
        return color;
    }
}

It's already quite long, isn't it? It gets worse. We'll also want to have some basic implementation of equals() and hashCode().

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    Cat cat = (Cat) o;
    return numberOfLives == cat.numberOfLives &&
            Objects.equals(name, cat.name) &&
            Objects.equals(color, cat.color);
}

@Override
public int hashCode() {
    return Objects.hash(name, numberOfLives, color);
}

Are we done yet? Not quite, we'll also need some nice toString() method:

@Override
public String toString() {
    return "Cat{" +
            "name='" + name + '\'' +
            ", numberOfLives=" + numberOfLives +
            ", color='" + color + '\'' +
            '}';
}

And we're finally done. It's about fifty lines of code! It's quite painful to write (although your IDE can help here) and difficult to read. What's worse, it's hard to find some extra functionality (such as new methods) in all the boilerplate.

In these fifty lines, there are only three lines that are actually interesting and bear some information:

private final String name;
private final int numberOfLives;
private final String color;

The rest is just boilerplate, which is predictable and can be automatically generated based on these three lines. Your IDE can do that, and there are tools such as Lombok, which can do this for you as well.

In Java, you often use classes, which just hold data, like our Cat. The implementation is always pretty much the same - a bunch of fields, getters, equals(), hashCode() and toString(). Often it is useful to have them immutable, if possible, which has many benefits. But to write and read such classes is a lot of work as there is a lot of code involved. And it is error-prone. Who knows whether your hashCode() and equals() code is actually correct?

Records

Java 14 tries to solve this issue by introducing a new type called Record, it is described by JEP 359: Records (Preview)

The same 50 lines long class from the example above could be written as a record like this:

public record Cat(String name, int numberOfLives, String color) { }

It's a lot less code, right?

The functionality is the same as in our previous example - we have:

an immutable class with three fields
Constructor assigning these fields
Getters
equals(), hashCode() and toString()

To illustrate this better, let's look at the decompiled version of our record.

public final class Cat extends java.lang.Record {
    private final java.lang.String name;
    private final int numberOfLives;
    private final java.lang.String color;

    public Cat(java.lang.String name, int numberOfLives, java.lang.String color) { /* compiled code */ }

    public java.lang.String toString() { /* compiled code */ }

    public final int hashCode() { /* compiled code */ }

    public final boolean equals(java.lang.Object o) { /* compiled code */ }

    public java.lang.String name() { /* compiled code */ }

    public int numberOfLives() { /* compiled code */ }

    public java.lang.String color() { /* compiled code */ }
}

You can see that the code is pretty much the same as our old Cat. One notable exception is that getters for the fields generated are not named as usual - instead of getColor(), there is just color().

Also, the class extends java.lang.Record.

The equals() implementation considers two records to be equal if they are the same Type and have the same values. The toString() implementation prints our record like this:

Cat[name=Fluffy, numberOfLives=9, color=White]

Even though these methods are automatically provided for you, it is possible to override them if necessary.

Limitations

There are some restrictions and limitations of records, which you should be aware of.

Records cannot extend any class, although they can implement interfaces
Records cannot be abstract
Records are implicitly final; they cannot be inherited from
You can declare additional fields in the body of a record, but only if they are static

Adding methods

Even though records are mostly used just as plain data carriers, you can declare your own methods. Of course, since records are immutable, you cannot change any state, but it can still be useful. For example:

public record Cat(String name, int numberOfLives, String color) {
 
    public boolean isAlive() {
        return numberOfLives >= 0;
    }

}

You can also add static methods.

Custom constructors

By default, new records contain only a constructor, which requires all the fields of the record as parameters. For example, our cat, which has three fields, needs to be constructed like this:

Cat cat = new Cat("Fluffy", 9, "White");

What if some parameters can be optional - if we don't provide them, we can use some default value.

In our case, the number of lives for new cats is likely to be always 9. We can create an additional constructor, which accepts only name and color, and the number of lives can be set to 9 as a default value. Of course, the constructor with all three fields still exists and is available.

public record Cat(String name, int numberOfLives, String color) {

    public Cat(String name, String color) {
        this(name, 9, color);
    }
}

The all-fields constructor is automatically generated for us. But sometimes you need to perform some custom logic there. Such as input validation. You can declare the all-fields constructor by yourself if you need to:

public record Cat(String name, int numberOfLives, String color) {

    public Cat(String name,int numberOfLives, String color) {
        if(numberOfLives < 0) {
            throw new IllegalArgumentException("Number of lives cannot be less than 0.");
        }

        if(numberOfLives > 9) {
            throw new IllegalArgumentException("Cats cannot have that many lives.");
        }

        this.name = name;
        this.numberOfLives = numberOfLives;
        this.color = color;
    }
}

If you are overriding the constructor with all the fields which record specifies (canonical constructor), you can use a declaration without writing the parameters. They are still available for use, but the code is shorter.

public record Cat(String name, int numberOfLives, String color) {

    // This is the same as public Cat(String name, int numberOfLives, String color)
    public Cat {
        // name, numberOfLives and color available here
    }
}

Runtime introspection

There are two new methods added to java.lang.Class, which have records-related functionality.

The first one is called isRecord(). It is pretty straightforward, you can just check if something is a record or not:

Cat cat = new Cat("Fluffy", 9, "White");
if(cat.getClass().isRecord()) {
    //...
}

The other one is getRecordComponents(). You would call it in the same way as in the example above. It returns a list of java.lang.reflect.RecordComponent. It is basically a list of all the fields, which are in the record with information such as:

Name
Type
Accessor
Annotations

Try it yourself!

If you want to try this feature yourself, you can already do so even though Java 14 is not out there yet (as of 2/2020).

Preview feature

Records functionality is available in Java 14. However, currently only as a preview feature. What does it mean?

A preview language or VM feature is a new feature of the Java SE Platform that is fully specified, fully implemented, and yet impermanent. It is available in a JDK feature release to provoke developer feedback based on real-world use; this may lead to it becoming permanent in a future Java SE Platform.

Before the next JDK feature release, the feature's "real world" strengths and weaknesses will be evaluated to decide if the feature has a long-term role in the Java SE Platform and, if so, whether it needs refinement. Consequently, the feature may be granted final and permanent status (with or without refinements), or undergo a further preview period (with or without refinements), or else be removed.

Such features are shipped in the JDK but are not enabled by default. You need to explicitly enable them to use them. Needless to say, it is not intended for production use, but rather for evaluation and experimentation as it may get removed or heavily changed in a future release.

To try this feature yourself, you'll need to have JDK 14 installed.

IntelliJ IDEA setup

In IntelliJ IDEA, you can enable preview features under File → Project Structure.

To use records in IntelliJ IDEA, you'll need version 2020.1and later. As of 2/2020, it is available as Early Access Program build. Currently, IDEA has basic support for records, but full-fledged support should be available with the release version.

Manual compilation

Alternatively, if building manually, you need to provide the following params to javac:

javac --release 14 --enable-preview ...

That is for compile-time. At run-time, you just provide --enable-preview

java --enable-preview ...

Maven projects

For Maven builds, you can use the following configuration:

<build>
    <plugins>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <release>14</release>
                <compilerArgs>
                    --enable-preview
                </compilerArgs>
                <source>14</source>
                <target>14</target>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <argLine>--enable-preview</argLine>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-failsafe-plugin</artifactId>
            <configuration>
                <argLine>--enable-preview</argLine>
            </configuration>
        </plugin>
    </plugins>
</build>

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

There is an example repository for this blog post, where you can check the final project.

JavaFX & Spring

When working with Java these days, you rarely work just with plain Java. In most of the projects, people usually use the Spring Framework or Spring Boot, respectively. It has a lot of advantages and many useful features.

However, when you're developing JavaFX applications, there is no easy way to integrate it with Spring. The integration does not work out of the box as JavaFX applications have their own lifecycle and take care of instantiating controllers.

JavaFX-Weaver

JavaFX-Weaver is a project by Rene Gielen, which aims to integrate Spring and JavaFX. The setup is, fortunately, not that hard.

Getting started

Let's try with a plain simple Spring Boot project, and let's try to integrate JavaFX. You can generate a new project using Spring Initializr. You don't need to add any dependencies here. If you want to avoid getting into setting up JavaFX as a dependency, select a Java version pre-11 as it still contains JavaFXas a part of the JDK.

Adding a controller

We'll need a controller and a companion .fxml view to be able to test that our application works properly both with Spring and JavaFX. Let' create a controller first. Let's keep it empty for now.

public class MyController {
}

Adding a view

Now we need a .fxml file, which will be used with our controller as a view. We'll place it in the resources folder. For the integration to work properly, it is necessary to create it in the resources folder, but in a directory structure matching the package where is our controller.

For example, let's assume our controller is in package com.vojtechruzicka.javafxweaverexample. The .fxml file needs to be placed precisely here:

src\main\resources\com\vojtechruzicka\javafxweaverexample

Let's call our file main-scene.fxml.

Dependencies

If you are using plain Spring, the setup is little different, but for Spring Boot you just need to add the following dependency to your pom.xml file:

<dependency>
    <groupId>net.rgielen</groupId>
    <artifactId>javafx-weaver-spring-boot-starter</artifactId>
    <version>1.3.0</version>
</dependency>

Or this one if you are using Gradle:

implementation 'javafx-weaver-spring-boot-starter:1.3.0'

Spring Boot Application class

When we generated our base Spring Boot application, the main application class was also generated for us. It is the class annotated with @SpringBootApplication, which is used as an entry point to run the whole app.

But wait! JavaFX also has its main application class, which is used as an entry point for starting JavaFX applications.

That's confusing. So which one should be actually used to run our app, which is both Spring Boot and JavaFX?

We'll still use our @SpringBootApplication with a slight modification. Instead of running the Spring app directly, we'll use it to run our JavaFX app. And the JavaFX Application will be responsible for properly starting the Spring application context and integrating everything together using JavaFX Weaver.

We need first to make sure that the Spring Boot app launches our JavaFX app.

import javafx.application.Application;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootExampleApplication {

    public static void main(String[] args) {
        // This is how normal Spring Boot app would be launched
        // SpringApplication.run(SpringBootExampleApplication.class, args);

        // JavaFxApplication doesn't exist yet, 
        // we'll create it in the next step
        Application.launch(JavaFxApplication.class, args);    }
}

JavaFX Application class

Now our @SpringBootApplication is calling JavaFxApplication, which does not exist yet. Let's create it now.

public class JavaFxApplication extends Application {

    private ConfigurableApplicationContext applicationContext;

    @Override
    public void init() {
        String[] args = getParameters().getRaw().toArray(new String[0]);

        this.applicationContext = new SpringApplicationBuilder()
                .sources(SpringBootExampleApplication.class)
                .run(args);
    }

}

When the JavaFX initializes, it creates a new application context based on the configuration in our SpringBootExampleApplication - the main class of the Spring Boot application, which we modified in the previous step.

Now we have a Spring Boot application running with our new application context. But we need to make sure the context is properly closed when the JavaFX application terminates. For example, when you close the window. Let's handle this now.

@Override
public void stop() {
    this.applicationContext.close();
    Platform.exit();
}

Now the last part is to actually create a new window (Stage) and show it.

@Override
public void start(Stage stage) {
    FxWeaver fxWeaver = applicationContext.getBean(FxWeaver.class);
    Parent root = fxWeaver.loadView(MyController.class);
    Scene scene = new Scene(root);
    stage.setScene(scene);
    stage.show();
}

This is where Fx Weaver comes into play. We need to obtain its bean from the application context and then use it to load our FXML.

Spring-managed controllers

Traditionally we would create our Stage using FXMLLoader, which would load the FXML file and create a Controller instance declared in it for us.

FXMLLoader loader = new FXMLLoader();
URL xmlUrl = getClass().getResource("/main-scene.fxml");
loader.setLocation(xmlUrl);
Parent root = loader.load();
Scene scene = new Scene(root);
stage.setScene(scene);
stage.show();

So why are we using FX Weaver instead? What's problematic is that FXMLLoader creates the controller instance for us. That means it is not created and managed by Spring. Therefore we cannot use dependency injection and other Spring goodies in our controllers. And that's why we introduced Spring in our JavaFX in the first place!

But when FX Weaver creates the controller for us, it creates it as a Spring-managed bean, so we can fully utilize the features of Spring.

Enabling Spring for the controller

The first thing we need to do is to annotate our existing JavaFX controller with @Component so it gets recognized and managed by Spring. Next, we need to add @FxmlView annotation, so it gets recognized by FX Weaver.

import net.rgielen.fxweaver.core.FxmlView;
import org.springframework.stereotype.Component;

@Component@FxmlView("main-stage.fxml")public class MyController {
}

Note the parameter of @FxmlView("main-stage.fxml"). It specifies the name of your .fxml file, which should be matched with the controller. It is optional. If you don't specify it, Fx Weaver will use the name of the controller class as the file name with .fxml extension. The FXML file needs to be in the same package as the controller, but in the resources folder.

Making sure everything works

Now let's make sure everything works and integrates nicely. Let's run our @SpringBootApplication with its main method. You should see a simple window with a label, nothing fancy.

Ok, that means that the application runs, but we didn't really do anything Spring-specific in our controller. No dependency injection or anything. Let's try that now.

Adding a Service

To make sure Spring integration works properly, let's create a new Spring-managed service. Later, we'll inject it in our controller and use it there.

import org.springframework.stereotype.Service;

@Service
public class WeatherService {

    public String getWeatherForecast() {
        return "It's gonna snow a lot. Brace yourselves, the winter is coming.";
    }
}

Nothing special, it's a service for weather forecasting, which is not very dynamic right now, but it will be enough for our example.

Injecting the service

Now let's inject our new service into our existing controller. It's the usual Spring stuff, nothing special here.

@Component
@FxmlView("main-stage.fxml")
public class MyController {

    private WeatherService weatherService;
    @Autowired    public MyController(WeatherService weatherService) {        this.weatherService = weatherService;    }}

Loading the forecast

Now we need to load the data from our service somehow. Let's change our FMXL view, so:

There is a button which loads the data from WeatherService on click
The loaded data is shown in a label

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.*?>
<?import javafx.scene.layout.*?>

<VBox xmlns="http://javafx.com/javafx"
            xmlns:fx="http://javafx.com/fxml"
            fx:controller="com.vojtechruzicka.javafxweaverexample.MyController"
            prefHeight="100.0" prefWidth="350.0" spacing="10" alignment="CENTER">

    <Label fx:id="weatherLabel"/>    <Button onAction="#loadWeatherForecast">Get weather</Button></VBox>

Note the fx:id="weatherLabel" identifier, we'll use it to get access to this label in our controller so that we can change its text.

onAction="#loadWeatherForecast" is a method on our controller, which should be called when the button is clicked. We still need to add it to the controller. Let's do it now.

Controller logic

The last step is to change our controller, so it reacts to the button click in the view, loads weather forecast data, and sets it to our label.

So we need a reference to the label from our view so that we can change its text. We need to select its name to match the fx:id="weatherLabel".

@FXML
private Label weatherLabel;

Now we need to add the method, which is called when the button is clicked - onAction="#loadWeatherForecast".

public void loadWeatherForecast(ActionEvent actionEvent) {
    this.weatherLabel.setText(weatherService.getWeatherForecast());
}

In this method, we take the weather forecast from the service and set it to our label, which we defined before.

If you run the app now, after you click the button, it should load the current weather forecast.

Accessing components from view

Same as in plain JavaFX, you can declare components from view to be injected to your controller, so you can interact with them.

@FXML
private Label weatherLabel;

We already saw this works well. You just need to be careful about timing. Our controller is annotated by @Component, so it is a regular Spring-managed bean. It means it is instantiated by Spring when the application context starts and all the dependencies are injected. However, the weaving by FX Weaver happens later. And during this weaving, the component references are injected.

This has one implication. In your constructor and @PostConstruct you can already work with Spring injected dependencies as usual. However, be aware that during this time, references to components from the view are not yet available and are therefore null.

Conclusion

JavaFX Weaver provides a nice and easy way to integrate Spring with JavaFX applications. It is otherwise not so straightforward as JavaFX manages its own lifecycle and lifecycle of its controllers. JavaFX Weaver makes the integration possible and quite straightforward, so you can finally use all the cool features of Spring even with JavaFX.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Commitlint: validate your commit conventions automatically

Mon, 11 Nov 2019 22:12:03 GMT

Automatically check and enforce your commit conventions either with various available configurations.

Commit conventions

Although you can put pretty much anything in your commit messages, it is beneficial to have a more standardized and structured approach. It is better to stick to a convention, so all your commit messages follow the same structure. This has many advantages:

Your commit history is more readable and easier to navigate
You can automatically generate changelogs
Based on the type of changes, you can properly bump your version when using samentic versioning:
- major: when introducing breaking changes
- minor: when adding a feature
- fix: when adding a fix

There are various conventions. One example can be Conventional Commits.

Conventions can be very useful, but only as long as you can make sure everybody follows them. You can rely on your developers' discipline, but it is risky. Especially with external contributors to your codebase who may not be familiar enough with your convention. What's much better is having an automated tool to check your commits for you and reject them if they don't follow your conventions.

Githooks & Husky

Fortunately, Git already allows you to perform some actions when specific events are triggered. It is called git hooks. You can react in many phases of the git workflow, such as:

pre-commit
pre-push
pre-rebase
post-update

The bad news is that this is configured locally in your .git directory, so by default, each developer needs to be sure to install their hooks. If they don't, there are no checks, and you cannot check your conventions.

Fortunately, there is a tool called Husky for Node/NPM projects, which solves this issue. You can define your hooks in your project and they are automatically installed for you when running the project. This way all the developers will have proper hooks installed with no effort. If you need to change your hooks, you can do it n just one place, and it gets propagated to all your developers. You can read more about Husky in one of my previous posts:

Easy git hooks with Husky

21 June, 2018

#Git

Effortless creation and management of git hooks for your Node/NPM projects with Husky.

While Husky can be used to enforce your commit conventions, it can do much more. You can run your static code analysis, tests, automatic code formatting, and much more when committing.

Commitlint

Commitlint is an automated tool that can check your commit conventions for you and reject the commit if it does not follow your rules. These rules, of course, can be configured. Under the hood, Commitlint uses Husky git hooks.

Local setup

Husky

Since Commitlint utilizes Husky, we need to install it first. Husky is provided as dev-dependency, so it is used only locally and not bundled with your production code.

npm install --save-dev husky

Now we need to register a hook for checking a commit message. The hook is called commit-msg and can be registered in your package.json.

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }  
  }
}

Alternatively, you can use a dedicated .huskyrc file, which contains only Husky configuration:

{
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

Commitlint

Now when We have Husky, we need to install Commitlint CLI, which will be executed by Husky hook to validate commit messages. Again, it is just a dev dependency, which is not included in your production bundle.

npm install --save-dev @commitlint/cli

Convention configuration

Commitlint is just a tool for checking if your messages follow your conventions. It does not for you to use a specific convention, you can use whatever you want, it is fully configurable. It offers some configurations out of Currently supported configurations are:

Let's use @commitlint/config-conventional for now, but the process would be the same for any different configuration. We just need to install the proper package:

npm install --save-dev @commitlint/config-conventional

The last step is to create a Commitlint configuration file, where you define, which configuration should be used. We'll set up the one we just installed. Create a new file called commitlint.config.js in the root directory.

module.exports = {
    extends: ['@commitlint/config-conventional']
};

Verifying the setup

Now we're good to go. Let's just make sure everything works. Let's make sure our commit messages are tested against the Conventional Commits specification. Let's try an ordinary, not structured commit message first.

C:\projects\commitlint-example>git commit -m "created base project structure"
husky > commit-msg (node v10.16.3)
⧗   input: created base project structure
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problemsundefined 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky > commit-msg hook failed (add --no-verify to bypass)

The commit was rejected due to missing subject and type. Let's fix that.

git commit -m "feat: created base project structure

Now the commit was accepted. We added the type of the commit feat and the part after the colon : is considered the subject.

The full structure of conventional commits is the following:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Continous Integration

Local setup, as described above, is necessary and useful as the first line of defense. However, it is not bulletproof. Developers can Tinker with the local setup or suppress git hooks. You cannot rely purely on the local Husky setup. As another line of defense, it is viable to integrate Commitlint with your CI. You can reject invalid commits on the server even if developers manage to sneak them in.

Travis

Commitlint supports integration with Travis CI. First, elt's create a .travis.yml file in your root directory. We need to configure that it should run the Commitlint script.

language: node_js
node_js:
  - node
script:
  - commitlint-travis

Now we need to install Travis support in our project:

npm install --save-dev @commitlint/travis-cli

Now Travis can watch your Pull Requests and check whether new commits are compliant.

Commitlint GitHub action

Even simpler alternative to Travis is adding a GitHub Action. There is an action for Commitlint available.

The setup is super-easy. You just need to go to [this page] and click Install. You can select whether this action should apply for all your repost or just selected ones. And that's it. Now, whenever you create a Pull Request, it will be automatically checked by Commitlint.

Now if your PR contains invalid commit messages, the checks will fail:

And you will get a comment explaining all the failures:

Commit message wizard

Conventions are useful, but what's even more useful is to have some tool, which can help you compose valid commit messages. Especially when your convention is new, there are new joiners or external contributors. Fortunately, there are tools available that help you with crafting compliant commit messages.

Prompt CLI

Commitlint offers a tool, basically a command-line wizard, which lets you create your commit messages based on a series of questions. It is called @commitlint/prompt-cli. You can easily install it:

npm install --save-dev @commitlint/prompt-cli

Now you can register commit command in your package.json.

{
  "scripts": {
    "commit": "commit"
  }
}

Now instead of git commit, you can run npm run commit. It launches an interactive wizard in your console, which will ask you for all the parts of a commit message such as type, subject, and so on.

Please enter a type: [required] [tab-completion] [header]
<type> holds information about the goal of a change.

<type>(<scope>): <subject>
<body>
<footer>

72 characters left
❯ type:

What's cool is that this wizard automatically loads your configuration from your commitlint.config.js and behaves based on that config.

Commitizen

Another option instead of prompt-cli is a third-party solution called Commitizen.

It is also a wizard, which lets you easily create specification-compliant commit messages.

Custom configuration

If you're not happy with any settings of the predefined conventions, you can override them and provide some more configuration options for linting. This can be done in the commitlint.config.js file, which we already created.

The detailed configuration is beyond the scope of this article, but you can check the official configuration documentation and the list of all available rules.

Example repo

You can find an example repository I created with fully set up Commitlint here. It also includes Travis integration and prompt-cli with examples of rejected PRs.

Conclusion

Having convention for commit messages has many benefits, and you can use many automated tools to utilize that. Automatic generation of changelogs and version bumps are no longer a problem. Not to mention much better readability. Commitlint helps you with that both locally and on your Continous Integration server.

Husky, used by Commit lint, is a powerful tool for managing git hooks and can be used not only for commit messages but also for a wide variety of other quality checks.

Stackbit: build JAMStack sites in a few clicks

Thu, 07 Nov 2019 22:12:03 GMT

How to easily create full-blown JAMStack sites with a theme, CMS, and deployment using various static site generators.

JAMStack

JAMStack is a powerful concept of building static sites. It is an alternative to having a traditional heavyweight CMS, like WordPress, which is also responsible for dynamically creating and serving your content.

While tools like WordPress are powerful, they are much slower than static sites and can be easily hacked unless you diligently keep everything up to date.

When you build your sites statically, you can easily distribute them via a CDN for much better performance and utilize stronger caching. Since everything is static, you don't need to worry about your system being hacked as there are no moving parts. Everything is also much cheaper to run and host.

You can learn more about JAMStack and its benefits in one of my previous posts on how I migrated from WordPress to GatsbyJS:

Migration to GatsbyJS and JAM stack from WordPress

25 March, 2018

How and Why I migrated from WordPress to static JAM Stack site built with Gatsby JS.

Building Static sites

While JAMStack-powered sites have many advantages, there are drawbacks as well. The main disadvantage is that it takes much more effort to build a full-fledged site including theme, Content Management System and deployment.

With WordPress, you can have a running site in minutes with a little effort. Even non-developers can easily create and maintain a site. Not so much with JAMStack. You have to select and learn your static site generator. Then choose a theme and make sure it works well with your generator. Then choose one of many available CMSs. Then figure how to set up your deployment pipeline.

It takes a lot of effort for developers, and it is nearly impossible for somebody not so tech-savvy. At least it was until now.

Stackbit

Stackbit is a service, which solves the biggest pain point of static sites described above. It is a wizard, which lets you build and deploy a fully functioning static site using one of the supported static generators, with a theme, CMS and a functional deployment.

Creating a new site

New sites are created with a wizard in four simple steps.

1. Selecting a theme

The first step is to select a theme for your new site. There are currently 14 built-in themes, with 23 more marked as coming soon.

However, on top of built-in themes, you can import your own.

Traditionally, there was a problem of using themes with a static site generator as each theme is generator specific and cannot be easily shared between generators. This is where Stackbit really shines as it allows you to create universal themes independent on a generator. This way, it makes it easy to reuse a theme when migrating to a new generator.

To achieve this, Stackbit defines Uniform theme model and then offers a tool called Unibit to convert it from this model to a theme specific for any supported generator. This means if a new generator is introduced in the future, you can use your old theme with it.

2. Selecting a static site generator

The second step is selecting your generator. No matter which one you choose, it will work with your theme and CMS seamlessly.

Stackbit currently supports the following static site generators:

Jekyll
Gatsby
Hugo

Two more are marked as coming soon: VuePress and Hexo. They are likely to add more generators in the future.

3. Selecting a CMS

With JAMStack, you don't have to use any Content Management System at all. Your articles are usually saved in your git repo in the form of Markdown files or a similar format. You can create and edit your content directly in your IDE.

However, usually, content creators are non-technical people, so you need to integrate some kind of CMS for them, so they can easily create and edit content using a nice and simple GUI.

As a third step of the project creation workflow, Stackbit allows you to choose one of the supported CMSs, which will be used to manage the content on your site.

If you don't want to use any CMS, you can skip this step. It is always possible to add a CMS later.

Stackbit currently supports:

Forestry
Netlify CMS
Contentful
DatoCMS
Sanity

Prismic is marked as coming soon.

4. Deployment

The last step is to select a deployment method. That means:

Selecting a git repository, where your project will be created
Selecting a service which will be used for deployment

As a git repository hosting, you can currently use GitHub, but GitLab and Bitbucket are coming soon.

As a deployment method, there is currently offered just Netlify. It is a great service, which I currently use for my blog, you can read more details about it in this post:

Migration to JAM stack and Netlify from WordPress

21 May, 2018

How and Why I migrated from WordPress to static JAM Stack site deployed on Netlify.

GitHub Pages and GitLab pages are going to be supported soon, as well.

Once you authorize your GitHub and Netlify access, you're done. A git repo is created for you, and the project is automatically deployed.

Dashboard

When you finish creating your first project, it becomes available on your main dashboard, where you can see and manage all the projects. You have a single place from which you can edit your settings, navigate to your site, CMS, or git repository.

But the dashboard is not the only place you can manage your site from. If you go directly to your site and are logged in to Stackbit, you can see a special Stackbit button, where you can manage the site directly without going to your dashboard.

Medium import

A few years back, Medium got very popular as a blogging platform. These days, with the recent changes, many people are migrating back from Medium. Hosting your own static site for your blog is a viable alternative.

With Stackbit, migration from Medium is fortunately effortless. There is a dedicated page, where you can upload your Medium export archive, and it will automatically create a new Stackbit project for you with your data.

DEV.to integration

Services such as Medium are no doubt convenient to use, and you can reach a much larger audience than on your own. There is one major drawback, though. You don't really own your content and your audience. When such service goes out of business or changes its pricing model, you lose your content and audience. It is much better to have your own site so that you can build a stable audience, and you're safe from any changes of third-party services.

It would be great if you could combine the advantages of both approaches. It turns out you can! With Stackbit and DEV.TO integration.

DEV.to is an excellent service, focused purely on developers, which lets you publish your content to reach a wider audience. It already offers you a possibility to automatically publish to DEV.to using your RSS feed. So you still have your content hosted on your site, and it adds a canonical URL to your original site, so you do not cannibalize your SEO.

Now with Stackbit, it is possible also the other way around. You can publish your existing DEV.to content to your Stackbit site.

Beta

Stackbit is already publicly available and functional, but it is still running in open beta. Not all the features may be final, and there are many more features and supported services to be added soon. Go ahead and check their blog periodically to stay informed about the new features.

Conclusion

Stackbit is a very powerful tool, which lets you create a fully functional JAMStack site with all the bells and whistles just in minutes using a simple wizard. The main disadvantage of JAMStack - the high barrier of entry and accessibility to only technical people applies no more. Go ahead and give it a try!

Comparing files and folders in IntelliJ IDEA

Fri, 25 Oct 2019 22:12:03 GMT

IntelliJ IDEA offers numerous ways of comparing files, folders and code snippets and even synchronizing folder contents.

Comparing project files

Let's say there are two similar files in your project, and you need to compare them line by line. With IDEA, that's very easy. Just select both files in your project window (holding Ctrl for multi-selection).

Now you have two options:

Right click one of the files and select Compare Files
Press Ctrl + D

Now the new window opens, which contains two panels, each with one file. This is very similar to diff in Version Control Systems such as Git.

Each difference is color-coded:

No coloring means the content is the same
Blue means changes on the same line
Green means new content
Gray means removed content

You can click the arrow icons » and « to apply a particular change from one file to another.

This comparison works for images, too, although you cannot see and apply individual differences.

Comparing with non-project file

Another case is when you need to compare a file from your project with another file outside of it.

The process is again very similar. Select a single file in your project window and:

Right-click one of the files and select Compare With...
Press Ctrl + D

The last step is to browse for an external file to compare with. Now the comparison is the same as in the example above.

Comparing with the clipboard

Maybe you have a file in your project, and you need to compare it with some external content, which is not saved as a file on your machine. Maybe it is a code snippet from the web, for example, from stack overflow.

First, you need to open the file from your project in your editor. Then copy to clipboard the snipped you want to compare (Ctrl+C).

Now you have two options. Either compare the whole file against the clipboard or just a selection. If you want the whole file to be compared, just right-click anywhere in the editor and select Compare with Clipboard from the context menu. If you want just a selection instead, select some fragment of the file first and then right-click as before.

Custom comparison

What about the case when you want to compare two non-file code snippets from external sources? You can do this too! Just run Find Action via Ctrl + Shift + A and then search for Open Blank Diff Window.

This opens a brand new diff window with both panels blank, so you can copy and paste both snippets to be compared.

Comparing with the previous local version of the file

Even if you're not using any Version Control system, IDEA stores historical versions of your local files. You can right-click in your editor and select Local history → Show history.

Here you can browse older versions of your current file and see the difference between the old and the current version and apply any changes if required.

Compare with VCS

If you're using a Version Control System, you have several more comparison options. For example, if you're using Git, you can go to VCS → Git or right click your editor and select Git. Now you can:

Compare with the same repository version: Compares the current local file with the version in your remote repository
Compare with branch: Compares the local file with the same file in a different branch
Show history: Compares the local file with its previous versions

Comparing Folders

The comparison works not only for individual files but also for the whole directories. The process is the same as for files - just select two folders in your Project window and press Ctrl + D or right click and Compare Directories.

Here you can see a list of all the files present in both or in either one of the directories. You can easily spot which files are present in just one folder and which in both. These in both, you can compare as usual.

Synchronizing folders

The directory diff tool is useful not only for spotting differences in both directories, but also for synchronizing changes. You can apply changes for individual sections of each file as usual. But you can also mark files present only in one of the directories to be either kept or synchronized to the other directory. You can change the desired action for each file in the * column. Once you are satisfied, you can hit either Synchronize selected or Synchronize all.

Netlify Analytics Review: Google Analytics alternative?

Fri, 11 Oct 2019 22:12:03 GMT

Zero-impact server-side analytics for your Netlify projects. Works even with adblockers.

Netlify Analytics

Netlify is a cool service focused on building and deploying your static and JAM Stack sites. If you're interested you can read more about the service in one of my previous posts:

Migration to JAM stack and Netlify from WordPress

21 May, 2018

How and Why I migrated from WordPress to static JAM Stack site deployed on Netlify.

One of the new features recently announced by Netlify is Netlify Analytics. In its purpose, it is similar to Google Analytics - gather stats about people visiting your pages. Unique visitors, pageviews, that sort of stuff.

Unlike Google Analytics, it does not rely on JavaScript to gather and send this data. Instead, everything happens on the Netlify servers. That has some advantages we'll discuss in a moment. Now let's see how the Netlify Analytics dashboard looks like.

That's it: just this one screen, no other sub-views per category of per various metrics. Netlify's philosophy here is not to overwhelm users with a lot of data and keep it simple. Still, the product is new, and there are more features to come. It will never be as feature-rich as GA, though.

Advantages

Unlike Google Analytics and other similar services, Netlify Analytics runs on the server-side, which has some nice implications.

Better performance

Since everything happens server-side, there is zero impact on client performance. You don't need to include any external JavaScript, parse and execute it and make any calls to an external service. Google Analytics script currently has 43.4 kb (although it is much smaller compressed). It may not seem as much, but it can make a difference on low-end devices and with poor network connectivity.

Works with adblockers

Adblockers are really popular these days. What's problematic, is that most of them also block analytics tools. You lose information on all of your visitors, who use adblockers. According to the following report from 2018, globally 27% of desktop users on average use adblockers. But that's just average. It goes as high as 42% in Greece! That's huge. It means that a huge portion of your traffic can go untracked. It can get even worse, depending on your target audience. Likely, more tech-savvy users use adblockers more often. If you have a developer-targeted blog like me, the percentage is going to be way higher than the broad average.

Works with Javascript disabled

Since Netlify Analytics doesn't rely on Javascript, it works even if a client has JavaScript disabled. In the era of React, Angular, and other JS frameworks everywhere, the percentage is very low these days. Still, it may be useful to capture these visitors as well (assuming your page can actually run without JS).

Historical data when enabled

The good news is that Netlify already collects analytics data for you, even if you don't have analytics enabled. You just have to pay to view it. Once you do, you'll be able to view historical data up to 30 days back. It may take some time to import everything, though, so don't expect to see everything immediately.

Error & Not Found pages

By its nature, JS-powered tools such as Google Analytics, can show you only valid pages. Since Netlify Analytics is server-side, it can also capture requests to non-existent pages and resources. This may be handy to detect broken links and other ismilar issues.

Simplicity

GA is a very powerful tool, but it may be intimidating at first, if you're not familiar with it. For casual usage, it may be too complex. Netlify analytics is very simple and easy to understand, which is good.

Disadvantages

Although Netlify Analytics has some powerful features, it has, currently, also some serious flaws. This is to be expected as the project is still fresh and not mature yet. According to Netlify, there are fixes and enhancement to many of the disadvantages currently on the roadmap.

Accuracy

Netlify Analytics promises improved accuracy because it can track even users without javascript, those who have adblockers, and even missing resources. It's true to some degree. The problem is that it currently also tracks visits from bots, which can greatly affect your stats and provide irrelevant data.

Let's compare my stats on Netlify vs Google Analytics to illustrate this:

Unique visitors: 44K vs 50K ⟶ + 13.6%
Page views: 57K vs 439K ⟶ + 770 %

The Netlify data is supposed to be higher as it also detects users with adblockers, but this looks like way too much and is likely because of the bot activity.

Fortunately, according to Netlify, it is something they are already working on, and hopefully, it will be fixed soon. Currently, however, your stats include a lot of irrelevant data from bot visits.

Limited date range

One of the most significant shortcomings is a limited history of your data. Currently, you can see only the last 30 days of user activity. You don't have any means of determining how is your traffic changing in the a long term. Did all these new articles bring enough traffic, or is it stagnant? How did your traffic rise over the past few years?

According to Netlify, the date range is likely to be increased in the future, but is it ever going to full history, which GA already offers? Is it much better to have 180 days instead of 30 if your site is running for years?

Limited functionality

The feature set of Netlify Analytics is so far very limited; it's just one screen, which we saw in the image above. That's it. And it's not likely to be anywhere near to what GA offers anytime soon. Or ever. There a list of features which are currently offered:

Total pageviews
Total unique visitors
Total bandwidth used
Pageviews over the last 30 days: chart
Unique visitors over the last 30 days: chart
Top pages by pageviews
Top resources not found by the number of requests
Top sources of traffic by pageviews
Bandwidth used over the last 30 days: chart

If it is good enough for your case, that's great. However, it's likely you need more. There's not drill down per page, region, or device. No bounce rate, time spent on-page, or session flow. No demographics about users. Not to mention custom metrics.

Price

The biggest downside is pricing. Adding analytics costs $9 per month PER SITE. This can quickly ramp up if you're running multiple different sites on Netlify. The price seems quite steep, considering the biggest competitor, Google Analytics, has many more features and is completely free. I can imagine running and developing such kind of service can cost a lot of money. However, for a user, there needs to be a strong justification to choose a $9 service with fewer features over a free, more powerful alternative. It doesn't mean Netlify analytics is bad, but the alternatives may be more compelling considering the cost.

Also, the $9 price is only for pages with less than 250K monthly pageviews. If you have more, they have custom pricing, and you need to contact their sales team.

Conclusion

Netlify Analytics is a nice service, which has some powerful features, because of the fact, that it is running completely server-side. That means better performance and tracking of a portion of your traffic, which would otherwise not be visible. The setup is effortless and straightforward, and it's nicely integrated with Netlify.

It is still a new product and I'm expecting it to evolve and mature over time. Hopefully, some pain-points, such as bot tracking, will be fixed soon, and the service will be even better.

As for the price, it may not be justifiable on its own, but you have to take into consideration that Netlify provides a cool service with a generous free plan, and this is a way to make some profit by an optional product. Even though analytics are not perfect yet, I expect it to mature, and I'll be happy to pay $9 as a way to support a company offering a great product (Netlify as a whole), while still using the free plan.

If you're not too keen on supporting Netlify, it may be a better approach to wait some time until the product is more mature.

As for now, I'll still be using Netlify Analytics. However, I cannot really ditch GA either as I also want to have historical data. This way, I lose the performance benefit, and the only real remaining advantage is tracking users with adblockers and disabled JavaScript.

JavaFX Tutorial: CSS Styling

Thu, 10 Oct 2019 22:12:03 GMT

How to style JavaFX components using good old CSS.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Separating visuals

In the previous article about FXML, we learned how JavaFX achieves clean separation of concerns by dividing the user interface code into two parts. Components and their properties are declared in an FXML file, while the interaction logic is neatly separated in a controller.

Now there is a third part on top of this. FXML manages only what components are in your app, their properties, and how they are nested. It does not define the visuals of the component, though. That is - fonts, colors, backgrounds, paddings. To be honest, you can achieve it in FXML, but you shouldn't. Instead, visuals should be clearly separated in CSS stylesheets.

This way, your styling is independent and can be easily replaced or changed without affecting the rest of the application. You can easily even have multiple themes, which you can switch on demand.

CSS

You probably know CSS (Cascading Style Sheets) from the web, where it is used to style HTML pages. In JavaFX, this is very similar, although JavaFX uses a set of its own custom properties.

Let's see an example:

.button {
    -fx-font-size: 15px;
}

There are two essential concepts here. The first one is the selector. That's .button. This determines to which components the styling should be applied. There it is for ALL the buttons.

The second part is actual styling properties, which will be applied to all the components, which match our selector. Properties are everything inside the curly braces.

Each property has a specific value. In our example, we have a property -fx-font-size, which means how big the text will be. The value is 15px here but could be anything else we would desire.

To sum it up - we created a rule which says - all the buttons everywhere should have their text of size 15px.

Selectors

Now let's take a closer look at how selectors work in JavaFX. It pretty much the same as in regular CSS.

Class

Class in CSS represents multiple similar elements. For example, buttons or checkboxes. A selector, which should apply to all of the elements of the same class starts with a dot . followed directly by the class name. The convention is to separate individual words with a comma -. The following selector applies to all the elements with class label.

.label {
    // Some properties
}

Built-in classes

The good news is that all the built-in JavaFX components (such as Label or Button) have already a class assigned out of the box. If you want to target all the labels in your app, you don't have to add any custom classes to each of your labels. Each Label has by default label class.

It is easy to determine the class name from the component.

Take the name of the Java class of the component - eg. Label
Make the name lower-case
If it consists of multiple words, separate them by -

Some examples:

Label → label
CheckBox → check-box

When using such classes as selectors, don' forget to add .. That means the selector for the label class is .label.

Custom classes

If build-in classes are not enough, you can add your own custom classes to your components. You can have multiple classes separated by a comma:

<Label styleClass="my-label,other-class">I am a simple label</Label>

Or in Java:

Label label = new Label("I am a simple label");
label.getStyleClass().addAll("my-label", "other-class");

Adding classes this way does not remove the default class of the component (label in this case).

There is one special class called root. It means the root component of your scene. You can use it to style everything inside your scene (such as setting a global font). It is similar to using body tag selector in HTML.

ID

Another way of selecting components in CSS is to use the component's ID. It is a unique identifier of a component. Unlike classes, which can be assigned to multiple components, ID should be unique in a scene.

While classes are using . before the name in their selectors, IDs are marked with #.

#my-component {
  ...
}

In FXML, you can use fx:id to set the component's CSS id.

<Label fx:id="foo">I am a simple label</Label>

There is one caveat, though. This same ID is used to link to a component object declared in your controller with the same name. Since the id and the name of the field in controller need to match, fx:id needs to respect Java's naming restriction for field names. Even though the CSS naming convention dictates individual words separated by -, it is an invalid character for Java field names. For fx:id with multiple words, you need, therefore, to use a different naming convention such as CamelCase or use underscores.

<!--  This is not valid  -->
<Label fx:id="my-label">I am a simple label</Label>
<!--  This is valid  -->
<Label fx:id="my_label">I am a simple label</Label>
<Label fx:id="MyLabel">I am a simple label</Label>

In Java, you can just call the setId() method on your component.

Label label = new Label("I am a simple label");
label.setId("foo");

Properties

Although CSS used in JavaFX is very similar to the original web CSS, there is one big difference. The property names are different, and there is a lot of new properties specific to JavaFX. They are prefixed with -fx-.

Here are some examples:

-fx-background-color: Background color
-fx-text-fill: Text color
-fx-font-size: Text size

You can check the list of all the properties in the official styling guide.

Pseudo-classes

In addition to regular classes, which mark specific components, there are so-called pseudo-classes, which mark a state of a component. This can be, for example, a class for marking that a component has the focus or there is the mouse cursor over the component.

There's a whole bunch of built-in pseudo-classes. Let's take a look at Button. There are multiple pseudo-classes, you can use such as:

hover: mouse is over the button
focused: the button has the focus
disabled: the button is disabled
pressed: the button is pressed

The pseudo-classes start with : (e.g. :hover) in the CSS selectors. You need, of course, specify to which component your pseudo class belongs - e.g. button:hover. The following example shows a selector, which is applied for all buttons, which have focus:

.button:focused {
    -fx-background-color: red;
}

Unlike in CSS, which has just basic pseudo-classes for states like focus and hover, JavaFX has component-specific pseudo-classes, which relate to different states or properties of components.

For example:

Scrollbars have horizontal and vertical pseudo-classes
Cells have odd and even
TitledPane has expanded and collapsed

Custom pseudo-classes

In addition to build-in pseudo-classes, you can define and use your own.

Let's create our custom Label (inheriting from Label class). It will have a new boolean property called shiny. If it is true, we want our Label to have a shiny pseudo-class.

When the Label has the shiny pseudo-class, we'll set its background to gold:

.shiny-label:shiny {
    -fx-background-color: gold;
}

Now the class itself.

public class ShinyLabel extends Label {
    private BooleanProperty shiny;

    public ShinyLabel() {
        getStyleClass().add("shiny-label");

        shiny = new SimpleBooleanProperty(false);
        shiny.addListener(e -> {
            pseudoClassStateChanged(PseudoClass.getPseudoClass("shiny"), shiny.get());
        });
    }

    public boolean isShiny() {
        return shiny.get();
    }

    public void setShiny(boolean shiny) {
        this.shiny.set(shiny);
    }
}

There are several important parts here:

We have our boolean property BooleanProperty instead of regular boolean. This means it is observable, and we can listen to changes in its value.
We register a listener to be called every time the shiny value is changed using shiny.addListener()
When the value changes, we add/remove the shiny pseudo-class depending on the current value pseudoClassStateChanged(PseudoClass.getPseudoClass("shiny")undefined shiny.get()).
We add a custom class for all the labels shiny-label, instead we would have just the label class from our parent. This way, we can select only shiny labels.

Default stylesheet

Even if you don't provide any styles yourself, each JavaFX application already has some visual styling. There is a default stylesheet, which is applied to every application. It is called modena (since JavaFX 8, previously it used to be caspian).

This stylesheet can be found in:

jfxrt.jar\com\sun\javafx\scene\control\skin\modena\modena.css

Or you can check the file directly here. In the same directory, there is a whole bunch of images used by the stylesheet.

This stylesheet provides the default styling but takes the lowest priority compared to other types of stylesheets, so you can easily override it.

Scene stylesheet

In addition to the default stylesheet mentioned above, you can, of course, provide your own. The highest level on which you can apply styling is the whole scene. You can either provide that in your FXML:

<BorderPane xmlns="http://javafx.com/javafx"
            xmlns:fx="http://javafx.com/fxml"
            stylesheets="styles.css"
            ...
            >
  ...
</BorderPane>

Or in your Java code:

String stylesheet = getClass().getResource("/styles.css").toExternalForm();
scene.getStylesheets().add(stylesheet);

Note the toExternalForm() call. Scene expects stylesheet contents as a string, not the file, so we need to provide the contents of our stylesheet instead.

Parent stylesheet

In addition to having a stylesheet for a whole scene, sometimes it may be useful to have styling on layout level. That is - for an individual container such as VBox, HBox, or GridPane. The common parent of all layouts is Parent class, which defines methods for handling stylesheets on layout level. These styles apply only for the components in the given layout, not for the whole scene. Layout level styling takes precedence over scene level styling.

<HBox stylesheets="styles.css">
    ...
</HBox>

In Java, you need to load the stylesheet contents yourself, same as previously with scene:

HBox box = new HBox();
String stylesheet = getClass().getResource("/styles.css").toExternalForm();
box.getStylesheets().add(stylesheet);

Inline styles

So far, we've covered only cases of assigning an external stylesheet to a whole scene or layout. But it is possible to set individual style properties on the component level.

Here you don't have to bother with a selector as all the properties are set to a specific component.

You can provide multiple properties separated by semicolon:

<Label style="-fx-background-color: blue; -fx-text-fill: white">
  I'm feeling blue.
</Label>

In Java, you can use setStyle() method:

Label label = new Label("I'm feeling blue.");
label.setStyle("-fx-background-color: blue; -fx-text-fill: white");

Styling on component level takes precedence over both scene and parent (layout) styling.

Why to avoid them

Styling on component level may be convenient, but it is a quick and dirty solution. You give up the main advantage of CSS, which is separating styling from the styled components. You hardcode your visuals directly to the components now. You can no longer easily switch your stylesheets when needed, you cannot change themes.

Moreover, you no longer have a single central place where your styling is defined. When you need to change something across a set of similar components, you need to modify each of the components individually instead of editing just one place in your external stylesheet. Inline styling components should be therefore avoided.

Stylesheet priorities

You can provide styling on multiple levels - scene, parent, inline styles, and there is a default modena stylesheet. If you change that same property of the same component on multiple levels, JavaFX has a priority setting, which resolves what styles should be used. The list of priorities is - from highest to lowest:

Inline styles
Parent styles
Scene styles
Default styles

That means if you set the background color of a specific label both inline and on the scene level, JavaFX will use the value set in inline styles as it has higher priority.

JavaFX Tutorial: Advanced layouts

Fri, 04 Oct 2019 22:12:03 GMT

How to organize and position your GUI components in JavaFX application using advanced layouts.

In the previous article we covered some basic JavaFX layouts. Now it's time to go through the rest of the available layouts.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

AnchorPane

AnchorPane is an interesting and powerful layout. It allows you to define anchor points to the components inside. There are 4 types of anchors:

top
bottom
left
right

Each component can have any combination of anchors. From zero up to all four. Anchor point also defines a distance.

Anchoring means that the component keeps the defined distance from a particular edge of the layout (e.g., TOP). This distance is preserved even on resize of the layout.

For example: anchorRight=10 means that the component will keep distance 10 from the right edge of the layout.

You can combine two anchor points, which are not in the opposite direction, to anchor your component to a specific corner of the layout.

Anchor TOP = 10, RIGHT = 10 means that the component will stay in the top right corner of the layout in the distance 10 from both edges.

In the example above, the size of each component stays the same on resizing. However, if you define anchor points in the opposite directions, you can make your component grow/shrink on resizing.

You can have various combinations like this:

LEFT+RIGHT resizes horizontally
TOP+BOTTOM resizes vertically
All 4 anchors mean both horizontal and vertical resizing

Defining anchor points in FXML is easy. In the following example, there are all four, but you can include none or only these which you want.

<AnchorPane>
    <Button AnchorPane.topAnchor="10"
            AnchorPane.leftAnchor="10"
            AnchorPane.rightAnchor="10"
            AnchorPane.bottomAnchor="10">I am fully anchored!</Button>
</AnchorPane>

Now let's look how anchoring is achieved in Java:

AnchorPane anchorPane = new AnchorPane();
Button button = new Button("I am fully anchored!");
AnchorPane.setTopAnchor(button, 10d);
AnchorPane.setBottomAnchor(button, 10d);
AnchorPane.setLeftAnchor(button, 10d);
AnchorPane.setRightAnchor(button, 10d);
anchorPane.getChildren().add(button);

GridPane

GridPane is a layout that allows you to organize your components into a grid. Unlike TilePane, which is adding components one after another, here you need to specify the coordinates of the target location in your grid when adding a new component.

<GridPane hgap="10" vgap="10">
    <Label GridPane.rowIndex="0" GridPane.columnIndex="0">First</Label>
    ...
</GridPane>

In Java, when adding a new component, we specify first the ColumnIndex (x) and RowIndex(y).

    GridPane grid = new GridPane();
    grid.add(new Label("Hello!"), columnIndex, rowIndex);

Spacing

By default, grid cells have no spacing. The components are directly next to each other, with no margins. Spacing can be defined separately for rows and columns - that is: horizontally and vertically.

hgap sets horizontal spacing (between columns)
vgap sets vertical spacing (between rows)

<GridPane hgap="10" vgap="10">
    ...
</GridPane>

Spacing defined in Java:

GridPane grid = new GridPane();
grid.setHgap(10);
grid.setVgap(10);

Spanning multiple cells

Components in GridPane can span multiple rows and/or columns.

A component with rowspan is expanding to the bottom from its original cell. A component with colspan is expanding to the right.

<GridPane>
    <Label GridPane.columnSpan="2"           GridPane.rowSpan="2"           GridPane.rowIndex="0"            GridPane.columnIndex="0">        Foo!
    </Label>
</GridPane>

In Java, there are two ways of setting row and column span. You can either set it directly when adding a component to the grid:

grid.add(component, columnIndex, rowIndex, columnSpan, rowSpan);

Or through GridPane:

GridPane.setColumnSpan(component, columnSpan);
GridPane.setRowSpan(component, rowSpan);

Sizing

Even though in the initial example, all the cells were the same size, it does not necessarily have to be the case. The sizing of grid cells is the following:

Height of each row is equal to the highest element in the row
Width of each column is equal to the widest element in the column

Column and row constraints

As mentioned, by default, the columns and rows are sized based on the components inside. Fortunately, you can have better control over how individual columns and rows are sized.

There are ColumnContstraints and RowConstraints classes, which are used for this.

You have basically two options. Either set percentage of available space for individual rows and columns, or you set preferred width/height. In the latter case you can also define preferred behavior when the columns and rows are resized.

Percentage

This is quite straightforward. You can set a percentage of the available space to be occupied by the given row or column. When the layout is resized, the rows and columns are resized as well to match the new size.

<GridPane>
    <columnConstraints>
        <ColumnConstraints percentWidth="50" />
        <ColumnConstraints percentWidth="50" />
    </columnConstraints>
    <rowConstraints>
        <RowConstraints percentHeight="50" />
        <RowConstraints percentHeight="50" />
    </rowConstraints>
    ...
</GridPane>

The same example in Java:

GridPane gridPane = new GridPane();

ColumnConstraints col1 = new ColumnConstraints();
col1.setPercentWidth(50);
ColumnConstraints col2 = new ColumnConstraints();
col2.setPercentWidth(50);
gridPane.getColumnConstraints().addAll(col1, col2);

RowConstraints row1 = new RowConstraints();
row1.setPercentHeight(50);
RowConstraints row2 = new RowConstraints();
row2.setPercentHeight(50);
gridPane.getRowConstraints().addAll(row1, row2);

Absolute size

Instead of defining percentage size, you can define preferred and minimal size. In addition to that, you can specify how the row/column should behave on resize. Columns are using hgrow property, and rows have vgrow.

These properties can have three distinct values.

NEVER: Never grow or shrink on resizing. The default value.
ALWAYS: When resized, all the elements with this value are either stretched to fill the available space or shrank.
SOMETIMES: These elements are resized only if there are no other elements with ALWAYS.

<GridPane>
    <columnConstraints>
        <ColumnConstraints minWidth="50" prefWidth="100" />
        <ColumnConstraints minWidth="50" prefWidth="100" hgrow="SOMETIMES" />
    </columnConstraints>
    <rowConstraints>
        <RowConstraints minHeight="50" prefHeight="100" />
        <RowConstraints minHeight="50" prefHeight="100" vgrow="SOMETIMES" />
    </rowConstraints>
    ...
</GridPane>

The same example in Java:

 GridPane gridPane = new GridPane();

ColumnConstraints col1 = new ColumnConstraints();
col1.setMinWidth(50);
col1.setPrefWidth(100);
ColumnConstraints col2 = new ColumnConstraints();
col2.setMinWidth(50);
col2.setPrefWidth(100);
col2.setHgrow(Priority.SOMETIMES);
gridPane.getColumnConstraints().addAll(col1, col2);

RowConstraints row1 = new RowConstraints();
row1.setMinHeight(50);
row1.setPrefHeight(100);
RowConstraints row2 = new RowConstraints();
row2.setMinHeight(50);
row2.setPrefHeight(100);
row2.setVgrow(Priority.SOMETIMES);
gridPane.getRowConstraints().addAll(row1, row2);

You can also specify maxHeight and maxWidth for individual rows and columns.

BorderPane

BorderPane is a layout with five sections:

Top
Bottom
Right
Left
Center

You can assign components to the individual sections of the BorderPane:

<BorderPane>
    <top>
        <Label>TOP</Label>
    </top>
    <bottom>
        <Label>BOTTOM</Label>
    </bottom>
    <left>
        <Label>LEFT</Label>
    </left>
    <right>
        <Label>RIGHT</Label>
    </right>
    <center>
        <Label>CENTER</Label>
    </center>
</BorderPane>

Now the same example in Java:

Label top = new Label("TOP");
Label bottom = new Label("BOTTOM");
Label left = new Label("LEFT");
Label right = new Label("RIGHT");
Label center = new Label("CENTER");

BorderPane borderPane = new BorderPane();
borderPane.setTop(top);
borderPane.setBottom(bottom);
borderPane.setLeft(left);
borderPane.setRight(right);
borderPane.setCenter(center);

Sizing

All the regions except the center have a fixed size. The center then fills the rest of the space.

Top and Bottom regions are stretched across all the available horizontal space. Their height is based on the height of the component inside.

Left and right fill all the available vertical space (except what's occupied by top and bottom). Their width is dependent on the width of the component inside.

The center has a dynamic size and fills the rest of the space not occupied by other sections. Let's look at an example:

What's next

Now when we know how to use various layouts, we'll cover how to style JavaFX components using CSS.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

JavaFX Tutorial: Basic layouts

Tue, 01 Oct 2019 22:40:03 GMT

How to organize and layout your GUI components in JavaFX application.

This is the fourth article in the JavaFX series. In the previous article, I described how to use FXML and SceneBuilder to create your user interface. Now we'll cover layouts.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Layouts

Layouts, in a nutshell, are containers for components. This is useful as you can then position this container as a whole no matter what components are inside. Moreover, each scene can only hold one component, so you need a layout as a root component for your scene, so you can fit all the components you need. Of course, one layout is usually not enough, but you can nest layouts. That means you can put one layout inside another.

In addition to that, layouts also organize and position your components inside. Based on the layout used, child components can be positioned for example:

One after another horizontally
One after another vertically
One on top of each other as a stack
In grid

There are many more options. What's important is that a layout automatically updates the position of its children when it is resized. This way, you can have a consistent layout, even if your user resizes the application window.

HBox

This is one of the most straightforward layouts available. It just puts all the items inside horizontally in a row, one after another, from left to right.

In FXML, you can use HBox like this:

<HBox>
    <Button>1</Button>
    <Button>2</Button>
    <Button>3</Button>
    <Button>4</Button>
</HBox>

In Java you can use this:

HBox hbox = new HBox();
Button btn1 = new Button("1");
Button btn2 = new Button("2");
Button btn3 = new Button("3");
Button btn4 = new Button("4");
hbox.getChildren().addAll(btn1, btn2, btn3, btn4);

Spacing

Our elements are now neatly laid out horizontally in a row, one after another:

However, it does not look very good as they are right after each other with no spacing. Fortunately, we can define the spacing between components using spacing property of the HBox:

<HBox spacing="10">
     ...
</HBox>

Or in Java using setSpacing():

HBox hbox = new HBox();
hbox.setSpacing(10);

Padding

The elements are now spaced properly, however, there is still no padding between elements and the HBox itself. It can be useful to add padding to our HBox:

You can define each section of the padding separately - top, bottom, left and right.

<HBox>
    <padding>
        <Insets top="10" bottom="10" left="10" right="10"/>
    </padding>
    ...
</HBox>

The same thing can be achieved in Java:

HBox hbox = new HBox();
hbox.setPadding(new Insets(10, 10, 10, 10));

VBox

VBox is very similar to HBox, but instead of displaying the components inside horizontally in a row, it displays them vertically in a column:

You can still set the spacing and padding in the same way as with HBox.

In code, VBox is used exactly in the same way as HBox, just the name is different:

<VBox spacing="10">
    <padding>
        <Insets top="10" bottom="10" left="10" right="10"/>
    </padding>
    <Button>1</Button>
    <Button>2</Button>
    <Button>3</Button>
    <Button>4</Button>
</VBox>

And in Java:

VBox vbox = new VBox();
vbox.setPadding(new Insets(10, 10, 10, 10));
vbox.setSpacing(10);
Button btn1 = new Button("1");
Button btn2 = new Button("2");
Button btn3 = new Button("3");
Button btn4 = new Button("4");
vbox.getChildren().addAll(btn1, btn2, btn3, btn4);

StackPane

This layout is useful for stacking its components one on top of each other. The order of insertion determines the order of the items. That means the first item is on the bottom, the next is on top of it and so on.

This can be useful, for example, for having an image and then having some text or button on top of it.

The following example shows StackPane in FXML:

<StackPane>
    <ImageView>
        <Image url="/image.jpg"/>
    </ImageView>
    <Button>Click Me!</Button>
</StackPane>

The same example in Java:

StackPane stackPane = new StackPane();
Image image = new Image(getClass().getResourceAsStream("/image.jpg"));
ImageView imageView = new ImageView(image);
Button btn = new Button("Click Me!");
stackPane.getChildren().addAll(imageView, btn);

Item alignment

You can set alignment of the items in the stack to better adjust their positioning:

<StackPane alignment="BOTTOM_CENTER">
 ...
</StackPane>

Of course, you can do the same in Java:

StackPane stackPane = new StackPane();
stackPane.setAlignment(Pos.BOTTOM_CENTER);

Margin

If you want even more fine-grained control of the positioning, you can set margin for individual items in the stack:

<StackPane alignment="BOTTOM_CENTER">
    <ImageView>
        <Image url="/image.jpg"/>
    </ImageView>
    <Button>
        <StackPane.margin>            <Insets bottom="10"/>        </StackPane.margin>        Click Me!
    </Button>
</StackPane>

Or in Java:

StackPane stackPane = new StackPane();
Button btn = new Button("Click Me!");
stackPane.getChildren().add(btn);
StackPane.setMargin(btn, new Insets(0,0,10,0));

FlowPane

Flow Pane can work in two modes - either horizontal (the default) or vertical.

In horizontal mode, the items are displayed horizontally, one after another, similar to HBox. The difference is, once there is no more horizontal space available, it wraps to the next row under the first one and continues again. This way there can be many rows, not just one as with HBox.

The vertical mode is very similar, but (like VBox) it displays items vertically, from top to bottom. Once there is no more space, it adds another column and continues.

The following image illustrates these two modes:

Note that items don't necessarily have to have the same size as they do have in the image above.

Note how the position of the components is recalculated if you change the size of the container:

You can set the internal padding of this layout in the same way as for HBox and VBox. Spacing is a little bit different though. Instead of just one property for spacing, you need to have separate horizontal and vertical spacing as the items can be rendered in multiple rows/columns. For horizontal spacing use hgap, for vertical spacing use vgap instead.

FlowPane flowPane = new FlowPane();
flowPane.setOrientation(Orientation.VERTICAL);
flowPane.setVgap(10);
flowPane.setHgap(10);
flowPane.getChildren().addAll(...);

Example of FlowPane in FXML:

<FlowPane hgap="10" vgap="10" orientation="VERTICAL">
  ...
</FlowPane>

TilePane

This layout is very similar to FlowPane. The way it displays its components is almost identical. You can still have either horizontal or vertical mode and define vgap and hgap.

One crucial difference is in the sizing of the cells. FlowPane assigns only space necessary for each component. TilePane, on the other hand, makes the size of all cells the same depending on the biggest item. This way, all the controls are nicely aligned in rows/columns.

In the image above, there are the same components in the same order. You can clearly see the difference.

FlowPane puts controls directly one after another, no extra spacing
TilePane puts controls into cells with the same size based on the biggest element

Constructing TilePane is no different from FlowPane except for the name.

<TilePane vgap="10" hgap="10" orientation="VERTICAL" >

The same in Java:

TilePane tilePane = new TilePane();
tilePane.setVgap(10);
tilePane.setHgap(10);
tilePane.setOrientation(Orientation.VERTICAL);

What's next

In this article, we learned how to use several of the basic layout components in JavaFX. Still, there are more layouts to choose from. We'll cover these in the next article.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

JavaFX Tutorial: FXML and SceneBuilder

Tue, 01 Oct 2019 22:20:03 GMT

How to build GUI with JavaFX using FXML markup and SceneBuilder.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

The traditional way

In the previous article, we created a simple Hello World application. Just a quick refresher - the code looked like this.

@Override
public void start(Stage primaryStage) throws Exception {
    primaryStage.setTitle("Hello world Application");
    primaryStage.setWidth(300);
    primaryStage.setHeight(200);

    InputStream iconStream = getClass().getResourceAsStream("/icon.png");
    Image image = new Image(iconStream);
    primaryStage.getIcons().add(image);

    Label helloWorldLabel = new Label("Hello world!");
    helloWorldLabel.setAlignment(Pos.CENTER);
    Scene primaryScene = new Scene(helloWorldLabel);
    primaryStage.setScene(primaryScene);

    primaryStage.show();
}

You can see that the whole UI is assembled in Java code. Now, this is a very simple example, but as your application gets more complex and you introduce multiple levels of nested layouts and many components, the resulting code can be very hard to read. However, that's not all - the same class has code, which is responsible for structure, visuals, and behavior at the same time.

The class clearly does not have a single responsibility. Compare this, for example, with web front-end, where each page has neatly separated concerns:

HTML is structure
CSS is visuals
JavaScript is behavior

Introducing FMXL

All right, having all the code in one place is not a good idea. You need to structure it somehow, so it is easier to understand and more manageable.

There's actually a lot of design patterns for that. Usually, you would end up with a variation of Model-View-Whatever - that is something like Model View Controller, Model View Presenter, or Model View ViewModel.

You can spend hours discussing the pros and cons of different variants - let's not do this here. What's more important is that with Java Fx, you can use any of them.

It's because, in addition to the procedural construction of your UI, you can use declarative XML markup.

It turns out XML's hierarchical structure is a great way to describe a hierarchy of components in the user interface. HTML works pretty well, right?

This XML format specific to JavaFX is called FXML. Here you can define all your components and their properties and link it with a Controller, which is responsible for managing interactions.

Loading FXML files

So how can we change our startup method to work with FXML?

FXMLLoader loader = new FXMLLoader();
URL xmlUrl = getClass().getResource("/mainScene.fxml");
loader.setLocation(xmlUrl);
Parent root = loader.load();

primaryStage.setScene(new Scene(root));
primaryStage.show();

Here root represents the root component of your user interface, the other components are nested inside.

The load method has a generic return value, so you can load a more specific type than Parent. Then you can access component-specific methods. However, it makes your code more fragile. When you change your root component type in your FXML, the application will fail at runtime, not compile time. That's because now there is a mismatch in type declared in your FXML and in your Java FXML Loader.

Creating the FXML file

Now we know how to load an FXML file, yet we still need to create it. It needs to have extension .fxml. If you have a Maven project, you can put it in the resources folder or the FXMLLoader can load an external URL.

After we create the file, we need XML declaration on the first line:

<?xml version="1.0" encoding="UTF-8"?>

Imports

Before we can add individual components to our file, we need to make sure that they are properly recognized. That means adding import statements. This is very similar to import in Java classes. You can import individual classes or use wildcards as usual. Let's see an example of import section:

<?import java.lang.*?>
<?import java.util.*?>
<?import javafx.scene.*?>
<?import javafx.scene.control.*?>
<?import javafx.scene.layout.*?>

The good news is that instead of manually adding all of them, your IDE should be able to help you add imports in a similar way to adding them to Java classes.

Adding Components

Now it's time to add some components. In the previous article, we learned that each Scene could have only one child component. Let's add a simple label for now.

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.Label?>

<!--Just one component on root level is allowed-->
<Label>Hello World!</Label>

Of course, having a label as the root component is not very realistic. You would usually rather use some sort of layout, which is a container for multiple components and handles their positioning. We'll cover layouts later in the series, for now, let's just use simple VBox, which arranges its children vertically one under another.

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.Label?>
<?import javafx.scene.layout.VBox?>
<?import javafx.scene.control.Button?>

<VBox>
    <Label text="Hello world!"/>
    <Label text="This is a simple demo application."/>
    <Button text="Click me!"/>
</VBox>

FX Namespace

There is a couple of FXML elements and attributes, which are not accessible by default. You need to add an FXML namespace to make them available. This needs to be added to the root component:

<?xml version="1.0" encoding="UTF-8"?>
    ...

<VBox xmlns="http://javafx.com/javafx"      xmlns:fx="http://javafx.com/fxml">    ...
</VBox>

Now we can use some new elements from the fx namespace. Let's try adding unique ids to our components:

<Label fx:id="mainTitle" text="Hello world!"/>

The fx:id attribute is a unique identifier of a component, which can be used to reference the component from other parts of our FXML and even our Controller.

Scripting

Our application is now static. We have some labels and a button, but it does nothing dynamic.

Let's react on click on our button and change its caption from Click me! to Click me again!.

The first thing we need to do is to provide onAction handler to our button.

<Button fx:id="mainButton" text="Click me!" onAction="buttonClicked()"/>

Notice fx:id, this is an identifier, we'll use later to reference our Button.

Now we need to provide a function, which should be called. You can define it inside of <fx:script> tag. What's interesting is that you can use multiple scripting languages to write your script, surprisingly even JavaScript. But also Groovy or Clojure. Let's see an example in JavaScript:

<fx:script>
function buttonClicked() {
    mainButton.setText("Click me again!");
}
</fx:script>

You can see that we are referencing our Button component as mainButton, which is the id we declared using fx:id="mainButton".

You should also declare what scripting language you are using in your FXML file:

<?language javascript?>

Let's see the full example:

<?xml version="1.0" encoding="UTF-8"?>
<?language javascript?>
<?import javafx.scene.control.Label?>
<?import javafx.scene.layout.VBox?>
<?import javafx.scene.control.Button?>

<VBox xmlns="http://javafx.com/javafx"
      xmlns:fx="http://javafx.com/fxml">
    <Label fx:id="mainTitle" text="Hello world!"/>
    <Label fx:id="subTitle" text="This is a simple demo application."/>
    <Button fx:id="mainButton" text="Click me!" onAction="buttonClicked()"/>
    <fx:script>        function buttonClicked() {            mainButton.setText("Click me again!")        }    </fx:script></VBox>

Should I use this?

The example above showed us how to reference components using fx:id and how to add some basic behavior using scripting. Oddly enough, in JavaScript. However, is this something you should be actually doing?

The answer is - in most cases no. There are several problems with this approach. The reason why we introduced FXML was a separation of concerns - to decouple UI structure and behavior. With this scripting, the behavior is back again together with our UI structure. What's more - since we are no longer working with Java code but rather XML, we lost all the compile-time checks and type safety. Now all the problems will occur at runtime rather than at compile time. That's very fragile and error-prone.

Adding Controller

So what can we do to have a clean separation of concerns? We can link a Controller to our FXML file. It is a Java class, which is responsible for handling all the behavior and user interaction. Now we gained back our type safety and compile-time checks.

Your controller is a POJO, it does not need to extend or implement anything nor have any special annotations.

How do we link the controller class with our FXML though? There are basically two options.

In Java

You can instantiate your controller yourself (or use any other means of obtaining the instance such as Dependency Injection to obtain). Then simply assign it to your FXMLLoader.

FXMLLoader loader = new FXMLLoader();
loader.setController(new MainSceneController());

In FXML

You can specify the class of your controller as fx:controller attribute, which needs to be on the root component.

<VBox xmlns="http://javafx.com/javafx"
      xmlns:fx="http://javafx.com/fxml"
      fx:controller="com.vojtechruzicka.MainSceneController">    ...
</VBox>

If you declare your Controller class in FXML, it is automatically instantiated for you. This brings one limitation to this approach - you need to have no-args constructor in your Controller so that it can be easily instantiated.

To obtain the auto-instantiated Controller instance, you can get it from your FXML Loader:

FXMLLoader loader = new FXMLLoader();
loader.setLocation(getClass().getResource("/mainScene.fxml"));
MainSceneController controller = loader.getController();

Calling Controller methods

Now, when we have our controller, we can remove our script and have our button-click logic directly in our controller.

public class MainSceneController {
    
    public void buttonClicked() {
        System.out.println("Button clicked!");
    }
}

The next step is to register this method call as a handler for onAction event of our button. To reference methods from our controller, we need to use # before the method name:

<VBox xmlns="http://javafx.com/javafx"
      xmlns:fx="http://javafx.com/fxml" fx:controller="com.vojtechruzicka.MainSceneController">
    <Label fx:id="mainTitle" text="Hello world!"/>
    <Label fx:id="subTitle" text="This is a simple demo application."/>
    <Button fx:id="mainButton" text="Click me!" onAction="#buttonClicked"/></VBox>

When we click our button, it will call MainSceneController.buttonClicked(). Keep in mind that this reference works only if the method is public. If the access modifier is stricter, you need to annotate the method with @FXML annotation.

@FXML
private void buttonClicked() {
    System.out.println("Button clicked!");
}

Injecting components to Controller

So far we're just printing to the console. What if we want again to change the text of our button to Click me again!? How can we get references to components in our Controller?

Fortunately, it is easy. Remember these fx:id attributes?

<Button fx:id="mainButton" text="Click me!" onAction="#buttonClicked"/>

JavaFX tries to automatically map components with fx:id defined to fields on your controller with the same name.

Assume we have the button above with fx:id="mainButton". JavaFX tries to inject this button object to your controller to field with name mainButton:

public class MainSceneController {

    // Here is injected component with fx:id="mainButton"
    @FXML
    private Button mainButton;
    
}

Same as with methods earlier, your fields need to be either public or annotated with @FXML.

Now when we have a reference to our button, we can easily change its text:

public class MainSceneController {

    @FXML
    private Button mainButton;

    @FXML
    private void buttonClicked() {
        mainButton.setText("Click me again!");
    }
}

Scene Builder

Writing your GUI structure in XML may be more natural than in Java (especially if you are familiar with HTML). However, it is not very convenient still. The good news is that there is an official tool called Scene Builder to help you with building your UI. In a nutshell, it is a graphical editor for your GUI.

There are three main sections of the editor.

The left part shows available components, which you can drag and drop to the middle part. It also contains the hierarchy of all the components in your UI, so you can easily navigate it.
The middle part is your application rendered based on your FXML file.
On the right there is the current component inspector. You can edit various properties of the currently selected component here. Any component you select from the middle part of the hierarchy is shown in the inspector.

Standalone

Scene Builder can be downloaded as a standalone application, which you can use to edit your FXML files.

IntelliJ IDEA integration

Alternatively, Scene builder offers IDE integrations.

In IntelliJ IDEA, you can right-click any FXML file and click Open in SceneBuilder.

Alternatively, IDEA integrates SceneBuilder directly in your IDE. If you open an FXML file in IDEA, there are two tabs at the bottom of the screen

Text
SceneBuilder

For each such file, you can easily switch between editing your FXML file directly or through SceneBuilder.

You can configure the location of SceneBuilder executable in:

Settings → Languages & Frameworks → JavaFX → Path to SceneBuilder

What's next

In the next post in our series, we'll cover some basic layout we can use to organize our GUI components.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

JavaFX Tutorial: Hello world

Tue, 01 Oct 2019 22:15:03 GMT

Tutorial on how to build your first JavaFX application.

This is a second post in the JavaFX series. You can check the first post on how to set up your environment for JavaFx development.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Application composition

Each application consists of a hierarchy of some basic components. Stages, scenes, and nodes. Let's look at each of them.

Stage

Stage basically represents a window. Your application can have multiple stages, but needs at least one.

Scene

A scene represents the contents of a stage. Each stage can have multiple scenes, which you can switch. Imagine a theater stage switching multiple scenes during a play.

Node

Each scene can contain various components, which are called nodes. These can be controls like buttons or labels or even layouts, which can contain multiple nested components. Each scene can have one nested node, but it can be a layout, which can host multiple components. The nesting can be multiple levels deep - layouts can contain other layouts and regular components.

Summary

Each application can have multiple stages - windows. Each stage can switch multiple scenes. Scenes contain nodes - layouts and regular components.

You can visualize the hierarchy like this:

Now let's see a specific example - a real application.

Application Class

Time to start coding. If you followed the previous article, you already have all the required dependencies in place.

Each JavaFX application needs to have a main application class. That is - a class that extends javafx.application.Application.

Not only that, but you also need to override the abstract method from the Application class - public void start(Stage primaryStage) throws Exception.

Your main class can look something like this:

import javafx.application.Application;
import javafx.stage.Stage;

public class Main extends Application {

    @Override
    public void start(Stage primaryStage) throws Exception {
        // TODO implement me!
    }
}

Of course, we still need to implement the start method.

Main method

JavaFx does not necessarily need the main() method to start. You can package an executable jar using JavaFX Packager Tool. However, it is much more convenient to actually have the main method.

Not only is the application easier to start, but you can also pass command-line parameters to your application as usual.

Inside the main() method, we can launch our application using Application.launch().

public static void main(String[] args) {
    // Here you can work with args - command line parameters
    Application.launch(args);
}

You can see it is a static method in the Application class. We did not specify what our main class actually is. JavaFX is able to determine this automatically depending on the class, which calls this method.

Setting up a Stage

We are able to launch our app using main() method now. Still, nothing happens if we do so. We need a window to show. Windows are called stages, remember? As a matter of fact, we are already given the primary stage in the start method as an input parameter - public void start(Stage primaryStage). We can use this. The only problem is that it is hidden by default. Fortunately, we can easily show it using primaryStage.show().

@Override
public void start(Stage primaryStage) throws Exception {
    primaryStage.show();
}

Now when you run the application, you should see a window like this:

Not very impressive, right? First, let's add some nice caption to our window.

primaryStage.setTitle("Hello world Application");

To make it look even better, let's add a nice icon to the window top bar:

InputStream iconStream = getClass().getResourceAsStream("/icon.png");
Image image = new Image(iconStream);
primaryStage.getIcons().add(image);

You can add multiple icons. That is, multiple sizes of the same icon representing the application. Depending on the context, the best size for your application will be used.

Now you can configure the Stage object's properties and behaviour such as:

Setting position using setX() and setY()
Setting initial size using setWidth() and setHeight()
Limit maximum dimensions of the window using setMaxHeight() and setMaxWidth() or disable resizing altogether using setResizable(false)
Set window always on top using setAlwaysOnTop()
Set full screen using setFullScreen()
And many more

Adding a Scene

Now we have a window with some fancy title, but it is still empty. You already know, you cannot add components directly to a Stage (window). You need a scene first.

However, the scene constructor requires already its child node. Let's create a simple label first. Then we create a scene with this label as a child.

Label helloWorldLabel = new Label("Hello world!");
Scene primaryScene = new Scene(helloWorldLabel);

You can see that Scene only accepts one child component. What if we want more? You need to use a layout then, which is a component, that can have multiple children and arranges them on the screen depending on the layout used. We'll cover layouts later in the series.

To make it slightly more visually appealing, let's center the label vertically on the screen.

helloWorldLabel.setAlignment(Pos.CENTER);

Finally, we need to set the scene to the stage we already have:

 @Override
public void start(Stage primaryStage) throws Exception {
    primaryStage.setTitle("Hello world Application");
    primaryStage.setWidth(300);
    primaryStage.setHeight(200);

    InputStream iconStream = getClass().getResourceAsStream("/icon.png");
    Image image = new Image(iconStream);
    primaryStage.getIcons().add(image);

    Label helloWorldLabel = new Label("Hello world!");
    helloWorldLabel.setAlignment(Pos.CENTER);
    Scene primaryScene = new Scene(helloWorldLabel);
    primaryStage.setScene(primaryScene);
    primaryStage.show();
}

Now our window contains a scene with a label component.

What's Next

In the next step in the series, we'll cover how to write our GUI in XML rather in Java.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

JavaFX Tutorial: Getting started

Tue, 01 Oct 2019 22:13:03 GMT

How to set up and start working with JavaFX using Maven, Gradle, or JavaFX SDK.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Getting Java

JavaFX, of course, requires you to have JDK installed. Obtaining the required dependencies, however, varies based on which version of Java you have.

JavaFX was introduced as a part of the Java 8 release. However, it was later removed from JDK and moved to a separate module in Java 11.

This means, if you are targeting Java 8-10, you have all the required dependencies as a part of your JDK already. Hooray! If you are using a newer version of Java - that is 11+, you need to get the dependencies separately.

Maven

Obtaining and managing dependencies manually is quite inconvenient, and in a real application, you would rarely do so. It is much better to use a dependency management system such as Maven or Gradle. This way, you can just declare what dependencies you are using and what versions and it takes care of the rest.

Maven archetype

Of course, you can set up your Maven project by hand, from scratch. However, you may prefer a more convenient way of generating the base project structure and contents for you by Maven.

Maven has a concept of archetypes, which basically means you can generate different types of projects from a template. There are numerous archetypes for various types of projects, and fortunately, there is a couple for JavaFX. The archetype you can choose depends on which version of Java are you using.

You can read more about Maven archetypes in the following post:

Maven archetypes tutorial

19 September, 2019

#Maven

How to generate new projects from Maven archetypes, create your own and number of alternative tools.

Java 8 archetype

You can use com.zenjava:javafx-basic-archetype, or you can look for more archetypes yourself if this one does not suit you.

You can easily generate a project from your command line with Maven using the archetype above:

mvn archetype:generate -DarchetypeGroupId=com.zenjava -DarchetypeArtifactId=javafx-basic-archetype

Alternatively, you can create a new Maven project from an archetype directly in your IDE.

Java 11 archetype

For Java 11, you can use org.openjfx:javafx-archetype-simple.

To generate the project simply run:

mvn archetype:generate -DarchetypeGroupId=org.openjfx -DarchetypeArtifactId=javafx-archetype-simple

Manual Maven setup

If you want more control, you can, of course, set up your Maven project manually instead of generating it from an archetype.

To get started, you need two components. The first one is Maven Plugin for Java FX.

Simply add the following to your pom.xml:

    <build>
        <plugins>
            <plugin>
                <groupId>org.openjfx</groupId>
                <artifactId>javafx-maven-plugin</artifactId>
                <version>0.0.3</version>
                <configuration>
                    <mainClass>com.example.App</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>

Note that <mainclass> needs to point to your main class, which has the main method and extends javafx.application.Application. We'll cover it in the next article in the series.

The second part is adding a dependency for JavaFX controls:

<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-controls</artifactId>
    <version>11.0.2</version>
</dependency>

Gradle

Gradle currently does not support generating projects from archetypes directly.

You can use an unofficial Gradle Archetype Plugin and use Maven archetypes mentioned above.

Alternatively, you can generate your project using Maven from an archetype and then convert it to a Gradle project by using the following command in the directory containing your pom.xml:

gradle init

Manual Gradle setup

Similar to Maven manual setup, you need to add JavaFX plugin:

plugins {
  id 'application'
  id 'org.openjfx.javafxplugin' version '0.0.8'
}

And dependency to controls:

javafx {
    version = "11.0.2"
    modules = [ 'javafx.controls' ]
}

JavaFX SDK

There is yet another option to use JavaFX locally. You can download JavaFX SDK. It contains all the required libraries, which you can then link to your project in your IDE or add to classpath.

This may be useful when you are not familiar with Gradle or Maven and just for local development. When distributing your app, it gets inconvenient as you need to make sure you include all the required dependencies.

With this option, you can generate a non-Maven/Gradle project in your IDE, which contains all the essential files. In IntelliJ IDEA, you can simply go to:

File → New → Project → JavaFX

What's next

This article is the first one in the JavaFX Series. In the next one, we'll cover how to create and run your very first JavaFX application.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

How to deploy war files to Spring Boot Embedded Tomcat

Wed, 25 Sep 2019 22:12:03 GMT

How to deploy external WAR files to your Spring Boot Embedded Tomcat.

Deploying war

By default Spring Boot runs as a jar inside with embedded Tomcat (although you can deploy it as a regular WAR). Running with an embedded application server is great, but sometimes you may need to bundle another war with your embedded application. Maybe you have a legacy app you need to include and don't want to set up a regular Tomcat for this.

Fortunately, with Spring Boot, this is easy. The implementation differs depending on your version of Spring Boot.

Spring Boot 2.x

All you need to do is declare a bean in one of your @Configuration classes of type TomcatServletWebServerFactory. Then you need to override getTomcatWebServer() method. Adding a war is then as simple as running tomcat.addWebApp(). Please note in the example below that the webapps directory needs to be created as it does not exist by default. It is the directory where you normally put your wars to be deployed to your Tomcat.

@Bean
public TomcatServletWebServerFactory servletContainerFactory() {
    return new TomcatServletWebServerFactory() {
    
      @Override
      protected TomcatWebServer getTomcatWebServer(Tomcat tomcat) {
          // webapps directory does not exist by default, needs to be created
          new File(tomcat.getServer().getCatalinaBase(), "webapps").mkdirs();
    
          // Add a war with given context path
          // Can add multiple wars this way with different context paths
          tomcat.addWebapp("context-path", "path-to-your-war.war");
    
          return super.getTomcatWebServer(tomcat);
      }
    
    };
}

Instead of hardcoding your path to war and its context path, you can externalize them as properties and only load your war when these properties are present (using @ConditionalOnProperty).

You can either put these in your application.properties or pass them as command line parameters when running your app. This way, you can, for example, skip loading your war when developing locally or provide different artifacts on different environments.

@Bean
@ConditionalOnProperty(name = "external.war.file")
public TomcatServletWebServerFactory servletContainerFactory(@Value("${external.war.file}") String path,
                                                             @Value("${external.war.context}") String contextPath) {
    return new TomcatServletWebServerFactory() {

        @Override
        protected TomcatWebServer getTomcatWebServer(Tomcat tomcat) {
            new File(tomcat.getServer().getCatalinaBase(), "webapps").mkdirs();

            tomcat.addWebapp(contextPath, path);

            return super.getTomcatWebServer(tomcat);
        }

    };
}

If you want to deploy your war to /, you need to use an empty string as context root. To avoid conflicts with your Spring Boot application, you can change its context root in your application.properties by setting server.servlet.context-path.

Using dependencies from your fat jar

If you want to avoid duplicate dependencies, which are used by both of your artifacts, you can specify that your external war should use classloader of your fat jar.

Context context = tomcat.addWebapp("context-path", "path-to-your-war.war");
context.setParentClassLoader(getClass().getClassLoader());

Spring Boot 1.x

Spring Boot 2.x came with a lot of refactoring, and you need to use a different class to deploy your war when running Spring Boot 1.x. Notice also the try-catch block, which is necessary to catch a checked exception thrown by the method.

@Bean
public EmbeddedServletContainerFactory servletContainerFactory() {
    return new TomcatEmbeddedServletContainerFactory() {

        @Override
        protected TomcatEmbeddedServletContainer getTomcatEmbeddedServletContainer(
                Tomcat tomcat) {

            new File(tomcat.getServer().getCatalinaBase(), "webapps").mkdirs();
            
            try {
                tomcat.addWebapp("context-path", "path-to-your-war.war");
            } catch (ServletException e) {
                log.error("Unable to deploy war to embedded Tomcat");
            }

            return super.getTomcatEmbeddedServletContainer(tomcat);
        }

    };
}

If you want to change context path of your Spring Boot application, the process is the same as for 2.x except for the property name in application.properties is different - for version 1.x use server.context-path.

Adding support for JSPs

If your external non-Spring Boot war contains JSPs, you need to make sure you provide proper dependencies for them as the embedded Tomcat does not contain them by default.

For Maven, you can use:

<dependency>
    <groupId>org.apache.tomcat.embed</groupId>
    <artifactId>tomcat-embed-jasper</artifactId>
</dependency>
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>jstl</artifactId>
</dependency>

For Gradle use this instead:

compile "org.apache.tomcat.embed:tomcat-embed-jasper"
compile "javax.servlet:jstl"

Maven archetypes tutorial

Thu, 19 Sep 2019 22:12:03 GMT

How to generate new projects from Maven archetypes, create your own and number of alternative tools.

Archetypes

When starting a new project, it can be tedious and time-consuming to set up everything from scratch. Fortunately, Maven has built-in functionality which allows you to generate a project from a template. This template is called archetype.

There is a number of archetypes available which allow you to create various types of projects.

You can even create your own archetypes and share them with others.

Generating from command line

You can generate your project from an archetype in your command line using the following commad via Maven Archetype Plugin:

mvn archetype:generate 
-DarchetypeGroupId=org.springframework.boot 
-DarchetypeArtifactId=spring-boot-sample-simple-archetype 
-DarchetypeVersion=1.0.2.RELEASE

In the example above, you specify just identifiers of your archetype and the command starts in the interactive mode and asks you for all the required information such as groupId, artifactId and version of your new project. You enter these in your terminal, and the project is generated for you.

However, you can specify all these upfront, so no interaction is needed from your side. This can be useful, for example, when generating a project as a part of some automated script which should not have any user interaction.

mvn archetype:generate 
-DarchetypeGroupId=org.springframework.boot 
-DarchetypeArtifactId=spring-boot-sample-simple-archetype 
-DarchetypeVersion=1.0.2.RELEASE -DartifactId=my-app -DgroupId=com.example -Dversion=1.0-SNAPSHOT -DinteractiveMode=false

Generating from IDEA

Generating projects in IDEA from archetypes is easy. Just go to:

File → New → Project... → Maven

Here all you need to do is check Create from archetype and select your desired one.

However, the amount of archetypes listed is fairly limited. Fortunately, you can add any available archetype by clicking Add archetype.

Now you can continue with creating your Maven project as usual.

Creating your own archetype

Not only you can use existing archetypes, but you can also quite easily create your own.

From an existing project

The easiest way is to have an existing project and use the Maven Archetype Plugin to generate an archetype from it. It is actually quite easy.

mvn archetype:create-from-project

The resulting archetype is generated in target/generated-sources/archetype.

Before you can use it, though, you need to install the archetype in your local repository. Just go to the directory target/generated-sources/archetype and run mvn install.

From scratch

You can actually generate your own custom archetype using a Maven archetype. This way all the scaffolding is created for you.

mvn archetype:generate
-DgroupId=my.project.group.id
-DartifactId=my-project-artifact-id
-DarchetypeGroupId=org.apache.maven.archetypes
-DarchetypeArtifactId=maven-archetype-archetype

Now all you need to do is to copy over the files which should be part of your generated project. The target location of your files is described below.

Archetype configuration

POM file

In the artifact's root directory, there is a pom.xml file of the archetype. You can see the packaging maven-archetype. You can customize build of your archetype here as with any other pom.

However, there is another pom.xml file located under src\main\resources\archetype-resources which is the pom file of the generated project. Here you can make any changes, which should be presented in the resulting project's pom.

Source code

You can put any source files, which need to be part of the output project under

src/main/resources/archetype-resources/

That is:

Java code:
src/main/resources/archetype-resources/src/main/java

Test code:
src/main/resources/archetype-resources/src/test/java

Resources:
src/main/resources/archetype-resources/src/main/resources

Archetype metadata

Each archetype contains a special XML file with the archetype configuration, which can be found under:

src/main/resources/archetype-resources/META_INF/maven/maven-metadata.xml

Here you can configure the archetype itself - for example, files which should be included, properties needed, and so on. A simple version can look something like this:

<archetype-descriptor
        xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/1.0.0
        http://maven.apache.org/xsd/archetype-descriptor-1.0.0.xsd"
        xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        name="quickstart">
    <fileSets>
        <fileSet filtered="true" packaged="true">
            <directory>src/main/java</directory>
        </fileSet>
        <fileSet>
            <directory>src/test/java</directory>
        </fileSet>
    </fileSets>
</archetype-descriptor>

You can check configuration details in the official documentation.

Alternatives

Maven archetypes are a great built-in way of generating project scaffolding. However, there are more alternatives worth exploring, which may be better suited in some cases.

Gradle

If you prefer Gradle over Maven, working with archetypes gets a little trickier because Gradle currently does not support generating projects from archetypes directly.

There is an unofficial Gradle Archetype Plugin, which you can use to work with Maven archetypes.

As an alternative, you can generate your project first using Maven from an archetype and then convert it to a Gradle project by using the following command in the directory with your pom.xml:

gradle init

Spring Boot Initializr

When working with Spring Boot, you can still use Maven archetypes, but there is a better, way more powerful tool offered directly by Spring.

It is called Spring Initializr. It is a simple wizard, where you can define many options for your application and then generates your project based on your choices.

You can configure various options such as:

Language: Java, Kotlin or Groovy
Spring version
Java version
Maven / Gradle
Jar/War packaging
Dependencies such as DB, Security, Web, Actuator and many more

You can see there is a lot of configuration options to choose from. Also, you can see that unlike with Maven archetypes, you can generate your project even when using Gradle.

Instead of using the default web interface, there is even a more convenient way of generating your project directly in IntelliJ IDEA.

File → New Project → Spring Initializr

Yeoman

Yeoman is an interesting tool, which allows you to generate a project using one of their many generators.

What's interesting is that unlike Maven, it is not focused solely on the JVM ecosystem. You can generate a project for pretty much any language or framework and their combinations.

That means you can have a generator for an application with Java backend, React frontend and Docker integration. Or anything else you can think of as there are many generators available.

JHipster

JHipster is actually a Yeoman generator under a hood. It allows you to generate Spring Boot projects with Frontend in Either React, Angular or Vue.

There is much more, though. It optionally supports microservices and cloud deployment. It integrates sass, webpack, bootstrap, various databases, ELK, caching, Docker, WebSockets, and much more.

It is definitely worth checking if you want to easily generate your whole application front to back with a standardized opinionated stack.

Conclusion

Maven archetypes offer you an easy way to generate basic project scaffolding for various project types without the hassle of a manual approach. Still, there are some alternatives mentioned above which may be better in some cases such as Spring Boot Initializr or JHipster.

Deploying Spring Boot app as WAR

Sat, 20 Jul 2019 22:12:03 GMT

How to change your JAR Spring Boot app to be packaged and deployed as WAR without sacrificing direct execution capabilities of embedded app server.

WAR vs JAR

By default, Spring Boot applications are packaged as executable JAR files with embedded Tomcat. You can run them directly by java -jar command. Traditional Java web applications need a servlet container (application server) to run. You need to have such server installed, configured, and then deploy your applications to it. And you need to have such server prepared for each environment. With Spring Boot, this approach is inverted as the app server is directly in your JAR. This has many advantages, but sometimes you may need to have your Spring Boot app as a traditional WAR instead. For example, if you are tied by your company policies and need to deploy to a provided app server.

In this post, we'll examine how to package Spring Boot app as WAR, without sacrificing direct executability.

New applications

When you are creating a new app, the process is fortunately very easy. Instead of creating the application yourself, you can generate it with all the required settings and dependencies. There is an official tool called Spring Initializr.

By default, all the advanced options are hidden. You can set just the basics such as Spring version, language, or build tool. And of course all the dependencies.

You need to open the Options section to specify packaging.

In the advanced options section, there is Packaging selection. By default, there is Jar. This means you'll be able to run the JAR directly as it contains an embedded Tomcat application server.

You cannot deploy JARs to other applications servers (Tomcat, Jetty, JBoss, ...) to run them there. They only work with WARs. To be able to deploy your app to these, you need to change the packaging to WAR.

What's great is such WAR is still executable on its own, which is useful. For example, it's great for local development, even if you use a regular app server in production.

After you're done with the setup, you can click Generate project and a zip file with your app will be downloaded.

IDEA integration

Generating apps with Spring Initializr is way more convenient and less error-prone than creating them manually. There is still a bit of inconvenience as you need to go to an external web page, download a zip file and unpack it.

Fortunately, you can use Spring Initializr directly from your IDE. In IntelliJ IDEA you can go to:

File → New Project → Spring Initializr

Here you can specify all the options as in the web version but with less hassle.

Existing applications

When you already have existing Spring Boot application packaged as JAR, the process is slightly more complicated, but still straightforward. You need to make some changes manually.

Let's convert the app to WAR, which van be deployed to an application server such as Tomcat, while still keeping it executable.

Embedded Tomcat dependency

To make sure your embedded Tomcat dependencies are not clashing with what's already on your target Tomcat, you need to mark them as provided.

Maven

With Maven, simply add this dependency to your pom.xml file to the dependencies section.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
    <scope>provided</scope>
</dependency>

Gradle

With Gradle, the process is similar, just add the dependency to your dependencies section with provided scope.

providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'

SpringBootServletInitializer

Now you need to make sure the app properly runs as WAR. It is as simple as adding the following class to your app.

import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;

public class ServletInitializer extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(BootWarApplication.class);
    }

}

BootWarApplication.class is the class in your app annotated with @SpringBootApplication.

If you prefer, instead of a separate class, you can just make your @SpringBootApplication class extend SpringBootServletInitializer class and include the same configure method as above.

Change packaging

Now the last step is to make sure your app is properly packaged as WAR instead of JAR.

Maven

Simply update the packaging section in your pom.xml file from

<packaging>jar</packaging>

to WAR packaging

<packaging>war</packaging>

Gradle

In Gradle, add war plugin to your plugins section.

plugins {
    id 'org.springframework.boot' version '2.1.6.RELEASE'
    id 'java'
    id 'war'}

Building the WAR

The build process stays the same, no change here, simply run mvn package or gradle build and it will generate your WAR.

Now you can deploy to an application server of your choice.

Running the WAR

What's cool with this approach is that you can still run your WAR as an executable with embedded Tomcat. This way, you can have WAR deployment without sacrificing direct executability.

Simply run your archive as usual. Replace the last param with the real name of your WAR.

java -jar demo-1.0.0-SNAPSHOT.war