Vojtech Ruzicka's Programming Blog

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 problems, 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
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

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"), 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

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: 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

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: 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

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: 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

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

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

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

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

Configuring IntelliJ IDEA code style per folder

Tue, 09 Jul 2019 22:12:03 GMT

EditorConfig

When working in a team, it is a good practice to make sure your code style is consistent across your team. Often it is not as important what your specific rules are as much as that everybody sticks with the same conventions. This makes your codebase much cleaner, easier to read, and maintain.

There are various approaches to this. One popular tool is Prettier. It is an opinionated code formatter, which can reformat your code to match certain rules. You can then run it directly in your IDE, as a part of CI or before each commit using Git Hooks.

Another popular and widespread tool is EditorConfig. The approach is slightly different from Prettier. You create .editorconfig file directly in your project with your desired settings. Your IDE then detects this file and loads its configuration. Many Editors are supported out of the box, and there are plugins for many more.

An example file can look something like this:

# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true

# Matches multiple files with brace expansion notation
# Set default charset
[*.{js,py}]
charset = utf-8

# 4 space indentation
[*.py]
indent_style = space
indent_size = 4

# Tab indentation (no size specified)
[Makefile]
indent_style = tab

# Indentation override for all JS under lib directory
[lib/**.js]
indent_style = space
indent_size = 2

# Matches the exact files either package.json or .travis.yml
[{package.json,.travis.yml}]
indent_style = space
indent_size = 2

What is useful is that you can have .editorconfig file in each directory with different settings. This can be helpful with multi-module or multi-language projects. Unfortunately, the amount of supported properties is quite limited. Mostly indentation, line endings, or character encoding.

Editor config is powerful because, unlike in your IDE, you can configure settings per each directory. Also, it is a great tool for sharing the same settings among your team members with zero setup. Since .editorconfig can be kept under version control, you can just clone a project, and you are good to go as the configuration is already included.

There is one significant limitation, though. Since the list of supported options is fairly limited, there is still a whole lot of settings not covered by EditorConfig. Each IDE has a huge list of its own config properties, which cannot be shared with EditorConfig.

Traditionally, if you wanted to share these, it would involve tedious exporting and importing for each team member. Fortunately, IDEA offers several different options on how to synchronize IDE Settings.

IntelliJ IDEA Tips & Tricks: Synchronization and Sharing of Settings

24 January, 2018

#IDEA

Did you know IDEA offers two ways of synchronization of you settings among multiple instances of your IDE? You can use it when working on multiple computers or to share unified settings in your team.

It is powerful and handy, but it is not a zero-setup approach as with Editor Config. You need to make sure each person sets up their synchronization.

Extended EditorConfig Support in IDEA

IDEA supports EditorConfig out of the box for quite some time. However, since version 2019.2 it offers extended support which also covers IDEA-specific settings, which are not part of the core EditorConfig spec.

This way, you can have both zero-setup configuration per folder and sharing of IDEA specific settings. How does it work?

Creating .editorconfig file

First, you need to create a .editorconfig file inside your project. You can do it in the same way as with any other file. Just right-click your desired directory and select:

New → EditorConfig File

Before the file is created, IDEA shows the following dialog where you can customize its contents.

Root file

The first checkbox root=true allows you to mark your config file as a root file. What does it mean?

You can have multiple config files in your project, each in a different directory. Whenever you open a file in your IDE, it checks whether there is also .editorconfig file located in the same directory. If not, it goes up through the directory structure to search for one. It does not stop until it finds a .editorconfig file, which contains root=true. Your topmost config file should always contain root=true.

This means it can locate and load multiple config files during its search. Config from all the files found is applied. Files deeper in the hierarchy take priority over these higher in the hierarchy. This means a deeper file can extend and override whatever is in the files above.

Property sets

Now it is time to select what configuration properties should be included in your new file.

You can select standard core properties, which are supported with every EditorConfig compliant IDE by checking EditorConfig standard. However, you can also check IDEA-specific config properties for various languages supported by IDEA, such as Java, Kotlin, or HTML.

Let's try Java. Contents of the file should now contain a whole bunch of IDEA/Java-specific settings. Almost 250 new settings!

[*.java]
ij_java_align_consecutive_assignments = false
ij_java_align_consecutive_variable_declarations = false
ij_java_align_group_field_declarations = false
ij_java_align_multiline_annotation_parameters = false
ij_java_align_multiline_array_initializer_expression = false
ij_java_align_multiline_assignment = false
ij_java_align_multiline_binary_operation = false
ij_java_align_multiline_chained_methods = false
ij_java_align_multiline_extends_list = false
ij_java_align_multiline_for = true
ij_java_align_multiline_method_parentheses = false
ij_java_align_multiline_parameters = true
ij_java_align_multiline_parameters_in_calls = false
ij_java_align_multiline_parenthesized_expression = false
ij_java_align_multiline_resources = true
ij_java_align_multiline_ternary_operation = false
ij_java_align_multiline_throws_list = false
ij_java_align_subsequent_simple_methods = false
ij_java_align_throws_keyword = false
ij_java_annotation_parameter_wrap = off
ij_java_array_initializer_new_line_after_left_brace = false

And many more. Notice that each of these lines has a prefix of ij_. This way, you can easily distinguish regular settings from IDEA-specific ones.

Insert as comments

IDEA supports a lot of different configuration options, nearly 250 just for Java. Instead of inserting all you may prefer hand-picking just some of them.

You can select Add properties as comments. This way, all the supported properties are inserted commented-out. You still can see all the supported options, but you can uncomment just the ones you want to be applied.

Preview Mode

When tinkering with various configuration options, it is useful to check how are these reflected in a real code file. Fortunately, this is easy.

Next to each configuration section such as [Java] or [*], you can see a small eye icon.

When you click it, you can select a file, which will be used to preview your changes. Whenever you make changes to the config file, it will be reflected in your preview file.

Note that all these changes are preview-only and will not change the contents of your file.

Overrides visualization

In each .editorconfig, declared properties are evaluated from top to bottom. Which means that if you declare some property below the same property, which is already declared above, it will take priority.

For example, you can have settings for all files [*] on the top of your config file and then section for Java files only [*.java], which overrides some of the general config properties. In such case, IDEA offers you a nice visualization with icons in the gutter area. Similar to the case when you override methods from a parent class.

A tooltip offers an explanation of what section is overriding or overridden. By clicking the icon, you can navigate to that section. This works both inside one file as well as across the whole hierarchy.

Settings priority

As described above, you can have multiple .editorconfig files. This can be useful for having different settings for different packages or modules. Or to have different setting for production and test code. Or for different languages. To sum it up:

The settings from one config file are applied to all its subdirectories.
If there is a different setting in a subdirectory, it takes priority over settings from parent directories
Topmost config file must have root=true
Editor config settings have priority over your IDE settings
If a setting is not found in .editorconfig, it is taken from your IDE settings

Syncing plugins

While extended EditorConfig support is very powerful, it is not a full-fledged replacement for good old IDE Settings synchronization, which can also sync your IDE plugins.

Conclusion

EditorConfig in IDEA just got way more powerful. It does not support only original EditorConfig options, but a whole lot of IDEA-specific options as well. This way, you can easily share unified IDE configuration among your team members with zero-setup. No more import/export of settings or tedious setup of IDE Settings Sync. Moreover, you can now have different configuration options for each directory separately.

History of Java interface feature changes

Fri, 05 Jul 2019 22:12:03 GMT

Java interface changed a lot through the years. What were the changes during its evolution?

Original interfaces

Interfaces in Java 1.0 were pretty simple compared to what they are now. They could include only two types of items - constants and public abstract methods.

Constant fields

Interfaces can contain fields, same as regular classes with a few distinctions:

Fields must be assigned a value
Fields are considered public static final
Public static and final modifiers don't need to be explicitly stated

public interface MyInterface {
    int MY_CONSTANT = 9;
}

Even though it is not explicitly stated, MY_CONSTANT field is considered a constant which is public, static and final. You can add these modifiers anyway, but it is redundant.

Abstract methods

The most important members of an interface are its methods. Interface methods have its differences from ordinary class methods as well:

Methods don't have bodies
Implementation is provided by classes implementing the interface
Methods are considered public abstract even if not explicitly stated
Cannot be final as abstract and final is an invalid combination

public interface MyInterface {
    int doSomething();
    String doSomethingCompletelyDifferent();
}

Nesting

Java 1.1 introduced the concept of classes within classes. It comes in two flavors: static and non-static. Interfaces can contain other interfaces and classes.

Even if not explicitly stated, such interfaces and classes are considered public and static.

public interface MyInterface {
    class MyClass {
        //...
    }

    interface MyOtherInterface {
        //...
    }
}

Enums and Annotations

In Java 5, two more types were introduced - Enums and Annotations. They can also be placed inside interfaces.

public interface MyInterface {
    enum MyEnum {
        FOO, BAR;
    }

    @interface MyAnnotation {
        //...
    }
}

Generics

Java 5 introduced the concept of Generics. In a nutshell, generics allow you to used type parameters instead of explicit types. This way, you can write code, which works with various number of types without sacrificing type safety or providing an implementation for each individual type.

In interfaces, from Java 5, you can define type parameters and then use them instead of the return type of a method or a method parameter type.

The following interface Box<T> works no matter whether you use it to store Strings, Integers, Lists, Shoes, or any other type.

interface Box<T> {
    void insert(T item);
}

class ShoeBox implements Box<Shoe> {
    public void insert(Shoe item) {
        //...
    }
}

Static methods

Since Java 8, there you can include static methods in your interfaces. It works in a very different way than interfaces pre-Java 8. Originally methods in interfaces were all abstract, meaning you provide only the signature but not implementation. The implementation is the responsibility of classes implementing your interface.

With static methods in interfaces, you need to provide also implementation of the method's body. To include such method, simply use static keyword as usual. Static methods are considered public by default.

public interface MyInterface {
    
    // This works
    static int foo() {
        return 0;
    }

    // This does not work, 
    // static methods in interfaces need body
    static int bar();
}

Static method inheritance

Unlike regular static methods, static methods in interfaces are not inherited. This means that if you want to call such method, you need to do it directly on the interface instead of an implementing class.

MyInterface.staticMethod();

This behavior is very useful for preventing multiple inheritance issues. Imagine you have a class implementing two interfaces. Each of the interfaces has a static method with the same name and signature. Which one should take priority?

Why is it useful

Imagine you have an interface and a whole bunch of helper methods which operate with classes implementing this interface.

Traditionally there used to be an approach of a companion class. In addition to the interface, there would be a utility class with a very similar name holding the static methods belonging to the interface.

You can find examples directly in the JDK. Interface java.util.Collection and corresponding utility class java.util.Collections.

With static methods in interfaces, this approach is obsolete and no longer necessary or recommended. You can have everything in one place together.

Default methods

Default methods are similar to static methods in a way that that you need to provide method body. To declare a default method simply use default keyword.

public interface MyInterface {
    default int doSomething() {
        return 0;
    }
}

Unlike static methods, default methods are inherited by classes implementing the interface. What's important, the implementing class can choose to override the default behavior provided by the interface.

There is one exception, though. You cannot have default methods in your interface with the same signature as Object's toString, equals and hashCode. Check Brian Goetz's answer on the following page to understand the rationale behind the decision - Allow default methods to override Object's methods.

Why is it useful

Implementation directly in interfaces. It doesn't look quite right. So why was this functionality introduced in the first place?

There is one problem with interfaces. Once you expose your interfaces to other people, it is very hard to change them. Once you specify your API and others start using it, it is pretty much set in stone. Unless you want to break all your users.

Java, traditionally, takes backward compatibility very seriously. Default methods provide a way to extend existing interfaces with new methods. What's crucial is that default methods already provide some implementation. That means that classes implementing your interface does not need to implement any new methods and are still compatible. Of course, they can decide to later override default methods if the implementation is not fitting. So in a nutshell, you can provide new functionality to existing classes implementing your interface while preserving binary compatibility.

Conflicts

Let's assume we have one class implementing two interfaces. These interfaces have each a default method with the same name and signature.

interface A {
    default int doSomething() {
        return 0;
    }
}

interface B {
    default int doSomething() {
        return 42;
    }
}

class MyClass implements A, B {
}

Now the same default method with the same signature is inherited from two different interfaces. Each interface has a different implementation.

So how does our class know which of the two different implementations should it use?

It doesn't. The code above results in a compilation error. If you need to make it work, you need to override the conflicting method in your class.

interface A {
    default int doSomething() {
        return 0;
    }
}

interface B {
    default int doSomething() {
        return 42;
    }
}

class MyClass implements A, B {

    // Without this the compilation fails    
    @Override
    public int doSomething() {
        return 256;
    }
}

Private methods

With Java 8 and the introduction of default and static methods, interfaces could suddenly contain not only method signatures but also implementation. When writing such implementations, it is a good practice to compose more complicated methods out of several simpler methods. Such code is easier to reuse, maintain, and understand.

Usually, you would use mostly private methods for such purpose because they are implementation detail and should not be visible and usable from the outside.

However, in Java 8, you cannot have private methods in interfaces. That means you could either:

Use long, complex and hard to understand method bodies.
Use helper methods which are part of the interface. This breaks encapsulation and pollutes public API of the interface and implementing classes.

Fortunately, since Java 9, you can use private methods in interfaces. They have the following characteristics:

have method body, are not abstract
can be static or non-static
are not inherited by implementing classes and interfaces
can call other methods from the interface
- private can call private, abstract, default or static methods
- private static can call only static and static private methods

public interface MyInterface {

    private static int staticMethod() {
        return 42;
    }

    private int nonStaticMethod() {
        return 0;
    }
}

Chronological order

Here is a chronological list of the changes by Java version:

Java 1.1

Nested classes
Nested interfaces

Java 5

Generics
Nested enums
Nested annotations

Java 8

Default methods
Static methods

Java 9

Private methods

Java 13 Text Blocks

Sun, 23 Jun 2019 22:12:03 GMT

Java 13 finally brings support for multi-line string literals after dropping similar functionality from Java 12.

String literals in Java

Declaring a string literal in Java is easy:

String myString = "Behold, a string literal!";

Nothing new, right? Traditional string literals have, however, some inconvenient limitations.

First of all, the whole literal needs to be on just one line. This is ok for simple short strings, but for longer ones, you need to resort to concatenating multiple string literals. If you want also to include line breaks, you need to add \n.

String myString = "This is my string\n" +
        "which I want to be \n" +
        "on multiple lines.";

This is cumbersome and hard to read. The other problem is that various characters cannot be represented directly, but need to be escaped, such as " or \. This makes your strings even harder to read and work with.

String path = "Open \"C:\\Program Files\\Java\\jdk1.8.0_152\"";

This gets especially messy in cases such as regular expressions. How to handle this issue though?

Other JVM languages

As usually, Java is late to introduce a functionality which is already common in many other languages, even those on JVM. Kotlin, Scala or Groovy already support multiline strings literals using """ notation instead of usual ". Look at the following example in Kotlin.

val text = """
This is my cool string,
which I want to span
multiple lines.
It can have backslash \
and even double-quotes "
"""

As you can notice, not only is it multiline, but also you don't need to escape your characters anymore. This is called Raw String literal, which means all the characters are interpreted as is and no escaping is necessary.

Raw String literals in Java

In Java 12, there was originally proposal to include Raw String Literals (JEP-326). The behavior was very similar to the example in Kotlin above. But instead of using """ as in other JVM languages, it used backtick ` notation. The concept was slightly unusual in a way that you could use any number of backticks and the same amount of backticks at the end. This way it was not necessary to escape backticks inside a spring literal no matter how many consecutive backticks were present.

`This uses a single backtick`
``This can contain a backtick `, see?``
```I can use any number of backticks```

One problem with raw string literals is usually indentation. Every character in the multiline raw string literal is interpreted as is - including indentation, which is supposed to be there just for better code readability rather than part of the literal itself. Consider the following example:

  public static void main(String[] args) {
      String myString =
      `This is my string
      which I want to be
      on multiple lines.`;
      System.out.println(myString);
  }

If you print it, all the lines except the first will have indentation present.

This is my string
        which I want to be
        on multiple lines.

You would need to fix this manually, possibly with newly proposed String methods align() and indent(). Not very practical, but it's something you would have to endure if using raw strings.

You can read more about original Raw String Literals proposal in the following article:

Java Raw String Literals

26 November, 2018

#Java

Java finally brings support for raw strings. They can span multiple lines and you don't need to escape special characters. Especially useful for regular expressions.

This proposal was, however dropped before the final release of Java 12 and is now considered obsolete.

While we can expect that for any language feature, there will be a nontrivial volume of "I would have preferred it differently" feedback, in reviewing the feedback we have received, I am no longer convinced that we've yet got to the right set of tradeoffs between complexity and expressiveness, or that we've explored enough of the design space to be confident that the current design is the best we can do. By withdrawing, we can continue to refine the design, explore more options, and aim for a preview that actually meets the requirements of the Preview Feature process (JEP 12).

Multiline String literals in Java

After the withdrawal of the original proposal, the discussion was restarted and resulted in a brand new proposal, which will be introduced in Java 13 as a Preview Feature. Its called JEP 355: Text Blocks (Preview).

It is not supposed to be an implementation of Raw String Literals, but rather multiline String literals, which will still allow escapes, although you'll not be required to use all of them. On top of that, it will not be necessary to handle all the indentation issues, which was necessary with Raw String Literals.

Preview Feature

Text blocks will be only available as a preview feature in Java 13. 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.

You'll need to download JDK 13. In IntelliJ, go to File → Project Structure and make sure you have JDK 13 selected under Project SDK. To enable Text Blocks as a preview feature, be sure to select 13 (Preview) - Text blocks under Project language level.

When building your app manually, you need to specify that preview features should be turned on by providing the following params to javac:

javac --release 13 --enable-preview ...

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

java --enable-preview ...

Text Blocks

Unlike the declined Raw String Literals, Text Blocks are surrounded by three double quotes """, same as in Groovy or Kotlin. It is more in sync with plain String literals and other JVM languages.

String myBlock =  """
                  line 1
                  line 2
                  line 3
                  """

There is no runtime difference between Text Block and String literal. Both result in an instance of String. If they have the same value, they'll get interned as usual and end up as the same instance. Everywhere you can use String literal, you can also use Text Block.

Processing

Unlike regular String literals, Texts block are processed by the compiler in three steps:

Line ends are normalized
Excess whitespace is removed
Escaped characters are interpreted

Line end normalization

Windows and UNIX-based operating systems have different characters to represent line endings.

Windows uses Carriage Return \r and Line Feed \n, while Unix-based systems use just Line Feed. The problem is that Text Blocks use new line characters directly from the source code, instead of using \n such as regular string literals. That means that source code created on Unix would have Strings with different line endings when compiled on windows. The Strings would look identical to the naked eye but would have different line endings.

To prevent this, Java compiler takes all the line endings in Text Blocks and normalizes them to Line Feed \n. What is important is that this is done before evaluating escaped characters. That means that if you explicitly need to include Carriage Return using \r, you can, as it is evaluated after line ending normalization and would not be affected.

Indentation removal

Remember the example with Raw String Literals and indentation? Raw string literals interpret all the characters including indentation. So whitespace which was supposed just to make your source code easier to read actually becomes part of your strings. In the vast majority of the cases, this is not desired behavior.

Fortunately, Java compiler removes unwanted whitespace when compiling Text Blocks.

All the trailing whitespace is removed from the end of the lines.
Leading common whitespace is removed from the start of each line.

What does this mean exactly? Let's look at the following code:

public static void main(String[] args) {
    String html = """
                  <html>
                    <body>
                      <p>Hello, world</p>
                    </body>
                  </html>
                  """;
}

The HTML code snippet contains a whole lot of whitespace, but it does not really belong to it. It just makes it well aligned within the source file. What is significant is the relative indentation inside the block.

In other words: If every line in the snipped starts with 22 whitespaces, we can ignore them. These 22 spaces are common whitespace prefix, which can be ignored and only what is on top of that should be kept.

Let's replace common prefix with .. All of these spaces will be discarded. Only spaces marked with - will be kept as they exceed the common whitespace prefix.

        String html = """
......................<html>
......................--<body>
......................----<p>Text Blocks are awesome!</p>
......................--</body>
......................</html>
......................""";

The result will be:

<html>
  <body>
    <p>Text Blocks are awesome!</p>
  </body>
</html>

Note that in this step only direct whitespace is removed. If you have whitespace in a form of escaped characters such as \n or \t, it will not be removed.

Escaping

Text Blocks are not raw strings and you can still use escapes. However, you don't need to bother with the most common ones.

New line \n is no longer needed as Text Blocks are multi-line by nature.
You don't need to escape " double quotes as they no longer mark String literal ending

String myBlock =  """
                  First line
                  Second Line with " quotes
                  """

Since the quoting is allowed, you technically can include \n and \", but it is not necessary and it is discouraged. You still do need to escape slash \\. But in general Text Blocks involve a lot less escaping than good old String literals. All the escape sequences, which can be used in String literals, can be also used for Text Blocks. Check the Java spec for the full list.

Interpreting escaped characters as the last of the three steps is important as your escapes are not affected by line ending normalization and whitespace removal.

New String Methods

As part of Text Blocks proposal, there are three new Methods of String class.

translateEscapes() - translates escape sequences in the string escept for unicode ones.
stripIndent() - strips away common whitespace from the beginning of each line.
formatted(Object... args) - Convenience method, equivalent of String.format(string, args)

Conclusion

Text Blocks offer a convenient way of working with multi-line string literals.
To create a Text Block simply surround your string with """.
You can use Text Blocks anywhere you can use String Literals
Line endings are normalized to LF
Extra whitespace is stripped from the beginning and the end of each line. Only relative indentation is preserved.
It is a preview feature in Java 13, which needs to be explicitly enabled
Raw String literals proposal was withdrawn from Java 12; Text Blocks got introduced later instead

Detecting vulnerable dependencies in IntelliJ IDEA

Fri, 07 Jun 2019 22:12:03 GMT

Dependencies with security vulnerabilities

Making sure your application is as secure as possible is very important. Having security vulnerabilities can lead to serious consequences if they are exploited. You should always make sure your own code is as safe as possible.

However, the core code of your application, which you write yourself, is only the tip of an iceberg. These days, the vast majority of the deployed code is not what you write yourself, but rather various third-party libraries and frameworks. Even the simplest web applications usually have hundreds of thousands of lines of code, which are brought with third-party dependencies.

It is very hard to make big and complex frameworks secure. Not only are they very complicated, but they also depend on numerous dependencies of their own. It is not a question IF your libraries contain security vulnerabilities, but rather WHEN they are discovered. Once discovered, they are usually fixed quickly, and the next version is released.

The problematic part is that applications are not that fast with adopting new versions with security fixes. It can take months or even years to upgrade. First of all, you have to know there is a new version. Then you have to know whether to upgrade or not. Were there important security fixes or just some minor bugfixes? Is the fix important enough to justify upgrading cost, especially if there were changes breaking the backward compatibility?

Detecting vulnerabilities automatically

In the past, detecting vulnerable dependencies was difficult. There were public databases of security vulnerabilities, but you had to check them manually. Needless to say that only a minority of developers bothered to check. It was just too much trouble.

Fortunately, later, automatic tools became available, which could scan your dependencies and cross-check with vulnerability databases. One example can be OWASP Dependency Check. Later, even more powerful services appeared, most notably Snyk.

Snyk – Detecting dependencies with known vulnerabilities

22 November, 2017

#Security

How to detect and fix security vulnerabilities in your dependencies using Snyk?

It can be integrated with your Continuous Integration to break the build if critical vulnerabilities are found. What's more, it can even monitor your app, and once a new version fixing your vulnerabilities is released, it will automatically create a Pull request with the new version. How cool is that?

Detection directly in your IDE

Having a check for security vulnerabilities integrated as a part of your CI process is important and necessary, but it comes a bit late in the development pipeline.

It would be much better if you could check locally when adding a new dependency whether there are no security issues. This way, you could discover potential problems much earlier in the process. Snyk offers a CLI tool, which you can use, but for regular checking it can be too cumbersome, and you have to remember to run it every time.

Fortunately, Snyk recently released also IntelliJ IDEA plugin, which monitors your dependencies and can show you security vulnerabilities directly in your IDE.

Snyk plugin

The plugin is available for free for both the Community and Ultimate editions.

The Snyk Plugin is available directly from the plugin marketplace. You can access it using Settings → Plugins.

Once you install it and restart your IDE, a new tab is available:

It shows all the dependencies with known security vulnerabilities, which your app uses. You can expand individual dependencies to explore the transitive dependencies, which introduce the vulnerability.

If there is a new version, which fixes the dependency, Snyk suggests a version to upgrade to, which is very useful. You can click the name of a dependency, and Snyk automatically navigates you to the place, where it is declared in you pom.xml.

Finally, you can click the details link of each vulnerability, which navigates you to a web page in the Snyk vulnerability database with a detailed description of this particular vulnerability. You can then evaluate yourself how critical it is, what can you do to mitigate it a whether it applies in your case or not.

Maven only

Unfortunately, currently (as of 6/2019), the plugin supports only Maven and not Gradle. If you are using Gradle, you can stick With CLI or CI check, which does support it. However, according to Snyk, Gradle support is planned. Hopefully, it will be available soon.

UPDATE: Eclipse support

Since 7/2019 there is an IDE plugin not only for IntelliJ IDEA, but also for Eclipse.

Conclusion

Snyk IDEA plugin offers a simple, yet powerful way to detect security vulnerabilities in your dependencies directly in your IDE. This way, you can discover vulnerable libraries early in the development process without the need to wait for Continuous Integration check. This, however, does not mean you should depend only on the plugin. You should still have CI check in place as a safeguard and continuous monitoring, which Snyk offers, to make sure you discover new vulnerabilities and their fixes once they are available.

IDEA EduTools: Learning directly in your IDE

Sun, 05 May 2019 22:12:03 GMT

With IntelliJ IDEA Edu Tools plugin you can study various programming courses directly in your IDE and work on all the assignments. Alternatively, you can create courses yourself to share with others.

Getting started

Installation

If you already have IntelliJ IDEA installed, all you need to do is to install EduTools plugin. Just go to File → Settings → Plugins → Marketplace and search for EduTools. Then click Install and restart your IDE when finished. The plugin is available both for Ultimate and Community edition.

Alternatively, you can download IntelliJ IDEA EDU, which is basically the Community Edition bundled with the EduTools plugin. If you are using Python, JetBrains also offers Pycharm EDU.

Starting a course

Now, after the plugin is installed, it is time to start using it. All the interactions with the plugin are handled through

File → Learn and Teach

There are several options there, including integration with third-party educational services, such as Coursera, Stepik or Hyperskill. We'll cover these later, let's start simply by browsing available courses in the course repository:

File → Learn and Teach → Browse Courses

Some courses are gray, which means they are not yet approved by JetBrains. To start a course, simply select it and click Join. The join button offers an alternative action to view the course as an Educator. This allows you to access also solutions and tests, which verify whether each task is successfully completed.

Let's open a course in a normal way, as a student for now. Instead of project files as usual, you see all the chapters and the individual tasks contained in them.

As you can see, that IDEA tracks your progress and shows you what is already finished (green), what is failed (red) and what is yet to be completed (empty checkboxes).

You may select and solve individual tasks in any order. After selecting a task, you can see the task code in your editor and the description of what should you change to complete the task.

Once you are finished with your task, you can verify your solution by clicking the Check button. It runs predefined unit tests under the hood and based on the result it lets you know whether you passed or not.

You can either view the solution or just compare the expected output with what you have. Both these features show you a nice version control system-like diff so you can easily identify the differences.

Integrations

The amount of courses available in the repository is still somewhat limited, so it is great that EduTools offers integration with several third-party services, which offer their own courses.

Stepik

Stepik is an online educational platform, where you can either study the available courses or publish your own.

You can log-in in IDEA to your Stepik account. This has several advantages. You'll get access to a broader range of courses and now your progress is automatically synchronized with your Stepik account.

That means that you can study either in IDEA or Stepik web editor and your progress is tracked either way. It also acts as an online backup of your progress, because normally IDEA stores your progress just in a local folder.

You can access Stepik courses in IDEA from:

File → Learn and Teach → Start Stepik Course

Hyperskill

Hyperskill is another service integrated by EduTools. It is actually developed by Stepik. It is a very interesting tool with a slightly different focus. Instead of various independent courses, you build a number of projects. There is a big Knowledge map of various linked topics for each domain, where you can track your progress.

To open a Hyperskill project, go to:

File → Learn and Teach → Start Hyperskill Project

Coursera

Coursera integration is a bit sporadic right now. There's just "Kotlin for Java Developers" by JetBrains, where you can solve your weekly assignments in IDEA. You can access Coursera assignments in: File → Learn and Teach → Start Coursera Assignment.

Checkio

CheckiO offers tasks to improve your programming skills in Javascript and Python. It motivates you through gamification. You solve coding tasks to gain XP and level up to unlock new locations and challenges. There is also a nice social aspect where you can share your solutions and compare with others, have discussions and upvote your favorites.

You can access CheckiO courses through the course browser:

File → Learn and Teach → Browse Courses → Js CheckiO
File → Learn and Teach → Browse Courses → Py CheckiO

Your progress in synchronized with the web as usual.

Creating courses

So far, we've discussed only consuming courses created by someone else. What's great about EduTools is that it allows you to easily create your own tasks and courses. It can be a powerful tool when teaching programming.

This can be useful for hands-on tasks during the lessons, as homework assignments or even self-study material. It's good that it allows students to work with a real IDE with all the support it offers and it will teach them how to use it. They can check their solution automatically without the need to submit their code for review. And as a part of the task description, you can provide any theoretical background information necessary.

New course

The plugin has all you need to create the course directly in IDEA. Simply go to:

File → Learn and Teach → Create New Course

Then fill some basic information about the course:

Currently, you can select one of the supported languages (more are to come):

Java
Kotlin
JavaScript
Python
Scala
Rust

Creating tasks

Now when the course is created it's time to make individual tasks. It's pretty simple. Each task consists of three parts.

First is the description of the task. It is in the form of HTML file, so you can even provide some rich formatting, tables and so on.

The second part is the actual code. There are not two versions of files - starting state and final state. You just provide the final solution, which is expected. Then you can select certain parts of the code and Right Click → Add Answer Placeholder.

That means you mark specific sections of the code as hidden to the students and instead show some text like "TODO implement here".

Finally, you need to provide a way for the students to verify their solutions. This is done via one or more unit tests, which you can provide. As long as they pass, the students can move on to the next task.

Gradle

For Java, Kotlin and Scala each course uses Gradle under the hood and you can access and edit build.gradle file, which is bundled with the course. That means you can utilize the power Gradle gives you. And you are not limited to vanilla Java/Kotlin/Scala, but can also bring various third-party dependencies.

Once you are finished creating the course, it is time to share it with your students. You have basically two options.

You can export your course as an archive, which can be later imported to IDEA by your students.

File → Course Creator → Generate Course Archive

The import is performed from the Course Browser dialog. The other option is to go public and publish your course to Stepik available for everyone:

File → Course Creator → Upload Course to Stepik

Conclusion

EduTools offer you to study various programming courses and solve coding puzzles directly in your favorite IDE. No more clumsy web editors. It integrates well with various third-party educational services and it can synchronize your progress.

You are not limited to third-party courses, though. You can easily create your own courses and use them as a teaching material on your courses.

Analyzing dependencies in IntelliJ IDEA

Tue, 30 Apr 2019 22:12:03 GMT

How to analyze dependencies in IDEA using Dependency Structure Matrix and other tools.

Dependency Matrix

This functionality is available only in IntelliJ IDEA Ultimate, not Community edition.

IDEA offers a useful tool to analyze internal dependencies in your project called the Dependency Structure Matrix. It can be used to analyze not only dependencies between packages, but also individual classes.

This can be very important as tightly coupled classes, and modules or even cyclic dependencies mean that your code is very hard to refactor and reuse.

Dependency Structure Matrix (or DSM for short) can help you visualize your dependencies and look for potential problems. First, make sure to build your project. Then, to launch the analysis go to Analyze → Analyze Dependency Matrix.... You need IDEA Ultimate edition and DSM Analysis bundled plugin enabled.

After the analysis is done, you'll see something similar to this:

To better understand the matrix, look at the following image.

IDEA skips the column labels to save the precious space, but it behaves as if they were there.

Each row and column represent the package. Each cell represents an intersection of a row and column - that is two packages. The number in the cell represents a number of dependencies one package has on another. That means one class from the source package using another class from the destination package. The darker the cell is, the more dependencies. If there are more than 99 dependencies, it shows ... instead of the number.

As long as the dependencies are blue, it is good as they are one way only. Cyclical dependencies would be shown in red, which is not good. But we'll see that later.

Visual aids

The matrix is a powerful tool, which can show a lot of information at once. However, it may be difficult to read at first, if you're not used to working with it. Especially with the columns hidden. Fortunately, there are visual aids, which can help you to better understand the dependencies.

If you hover your mouse cursor over a cell, it shows you with tooltip what is the dependency direction there.

This can be useful, but there is more. You can click any package on the left (not an individual cell with dependency numbers), and IDEA will show you some more useful info.

The row is highlighted, as well as the corresponding column representing the same package. On top of that, you can see that some other packages are highlighted by either yellow on green.

Yellow highlights packages on which the selected package depends
Green marks packages which depend on the selected package

In addition to selecting a whole package, you can also click individual cells. The color coding is the same, there is just one new concept. The purple cell represents dependencies between the same two packages but in the other direction.

We need to go deeper

So far we were working only on package level. This is no doubt useful, but often you need to go into more detail. Which means investigating also dependencies between single classes.

In the DSM view, it is simple, you can expand your packages to see their contents. This way you can see dependencies for all the potential sub-packages or even individual classes.

Cyclic dependencies

So far, we covered only uni-directional dependencies. But something you should be really careful about are cyclic dependencies. In the DSM view, they are marked in red:

You can see that class Owner has 15 dependencies on class Pet, while Pet has 5 dependencies on Owner.

Taking Action

DSM view in IDEA is not only a useful tool to visualize dependencies, but you can also take many useful actions directly from the context menu when right-clicking a cell or package.

You can even refactor your classes directly from the DSM view. If you click a cell with dependencies, you can call Find usages for dependencies. It will look for all the places in one of your classes/packages where the other class/package is used.

Let's look at an example to be more specific. We can find all the places in the service package, where anything from the vet package is used. The results are classified by type:

Now you can inspect the occurrences one by one and check whether you could improve the flow of your dependencies.

Analyzing Maven dependencies

This functionality is available only in IntelliJ IDEA Ultimate, not Community edition.

So far we covered only internal dependencies in your own code. However, you can run into all sorts of trouble also with external dependencies. That is your third-party libraries. It can get messy as you don't have only direct dependencies, but your libraries have dependencies of their own (transitive dependencies). You can encounter many problems such as dependency version conflicts of the same artifact or even cyclic dependencies. Maven offers you to generate dependency tree representation, which can help you in analyzing potential issues. You can simply call:

mvn dependency:tree -Dverbose -DoutputFile=dependencies.txt

It will output your dependency tree in plain text format, which can look something like this (here is the full example):

--- maven-dependency-plugin:3.0.2:tree (default-cli) @ spring-boot-actuator-example ---
com.vojtechruzicka:spring-boot-actuator-example:jar:1.0.0-SNAPSHOT
+- org.springframework.boot:spring-boot-starter-actuator:jar:2.0.3.RELEASE:compile
|  +- org.springframework.boot:spring-boot-starter:jar:2.0.3.RELEASE:compile
|  |  +- org.springframework.boot:spring-boot:jar:2.0.3.RELEASE:compile
|  |  +- org.springframework.boot:spring-boot-autoconfigure:jar:2.0.3.RELEASE:compile
|  |  +- org.springframework.boot:spring-boot-starter-logging:jar:2.0.3.RELEASE:compile
|  |  |  +- ch.qos.logback:logback-classic:jar:1.2.3:compile
|  |  |  |  \- ch.qos.logback:logback-core:jar:1.2.3:compile
|  |  |  +- org.apache.logging.log4j:log4j-to-slf4j:jar:2.10.0:compile
|  |  |  |  \- org.apache.logging.log4j:log4j-api:jar:2.10.0:compile
|  |  |  \- org.slf4j:jul-to-slf4j:jar:1.7.25:compile
|  |  +- javax.annotation:javax.annotation-api:jar:1.3.2:compile
|  |  \- org.yaml:snakeyaml:jar:1.19:runtime

In addition to plain text, it offers various other formats as output, which are better suited for representing dependency graph such as graphml or tgf.

You can specify some other parameters to help you with your investigation, but for larger projects, it can be cumbersome to work with dependency tree output directly.

UPDATE: Be careful with verbose parameter when using maven 3.x as under the hood it still uses Maven 2 algorithm and may give you inconsistent results.

Fortunately, IDEA offers a nice GUI tool to work with Maven dependency graphs. This tool is in IntelliJ for quite some time, but as of version 2019.1, it received some needed enhancements, which make it much more useful in projects with large dependency graphs.

To show the graph, go inside a pom.xml file and press Shift + Ctrl + Alt + U (or ⌥ + ⇧ + ⌘ + U on Mac). Alternatively Right click → Diagrams → Show Dependencies.

You'll see zoomed out dependency graph, where it is not possible to see individual item names unless you zoom in. Looking for individual items manually can be a lot of pain. Fortunately, you can use Find as usual using Ctrl + F.

We are able to locate a specific dependency easily now, but still, a lot of unrelated dependencies making the graph hard to read. Let's look into how to filter the dependencies to get rid of unwanted noise.

The first option is to show only direct neighbors. That is, only direct dependencies of the current item and only items that directly depend on the selected item.

Note that this works not only for single items, but you can select multiple items while holding Shift.

Another way to filter is to display the dependency chain leading from the root to the selected item(s).

IDEA does highlight conflicts for you in red. Still, it may be difficult to find if there is something wrong in a huge dependency tree. Fortunately, you can filter problematic parts only:

In the example above, you can see there is a conflict between JUnit versions. There is an explicit dependency to JUnit 3.8.1 and a different version transitively taken through spring-boot-starter-test.

Maven Helper plugin

If the graphical dependency tree is not your thing, there is an alternative for you. It's Maven Helper Plugin by Vojtech Krasa. It uses hierarchical text representation of dependencies, similar to mvn dependency:tree but with a nice dependency browser.

It is also a good alternative if you are using IDEA Community Edition or have an older version of IDEA, where the Maven dependency graph is way less useful.

To use the Dependency Analyzer offered by the plugin, simply open any pom.xml file. At the bottom of your editor, there is a new tab added by the editor called Dependency Analyzer.

In the left panel, you can browse your dependencies (viewed either as list or tree). The right panel shows how selected dependency got into your application through the dependency chain. You can easily switch the view to show just conflicts.

Analyzing Gradle dependencies

Since version 2019.2, IDEA can finally show you dependency diagram not only for Maven, but also for Gradle. Yay! It works pretty much the same as Maven dependency diagram.

Just go to your build.gradle file and then press Shift + Ctrl + Alt + U (or ⌥ + ⇧ + ⌘ + U on Mac). Or Right click → Diagrams → Show Dependencies.

Conclusion

When you create an application, properly structuring your dependencies is very important as architecture with tight and tangled dependencies can be very hard to maintain, extend and modify. Fortunately, IDEA can help with a Dependency Structure Matrix, which provides a useful graphical view of your internal dependencies.

In addition to that, you need to make sure your external dependencies are covered as well, which you can achieve by utilizing a dependency graph for your dependency management system, such as Maven.

Try with resources in Java

Tue, 23 Apr 2019 22:12:03 GMT

Try with resources offers an easy and foolproof way to make sure all your resources are properly closed. It manages closing automatically instead of explicitly using try-finally.

Traditional try-catch-finally

With traditional try-catch, you can execute a block of code and handle any exceptions which may occur:

try {
    // Do something
} catch (Exception e) {
    // React to exceptions if they occurr
    // in the try block
}

Often it is useful to have also a finally block. It executes after try/catch, no matter whether there was an exception or not. It is very useful, especially when working with resources, which need proper cleanup after being used. When you use some resources, which are locked by your program (such as files or sockets and more), you need to make sure you release them after you're done.

You need to do the cleanup no matter whether all ends well or whether there is an exception.

try {
    // Open a resource
    // Try to use a resource
} catch (Exception e) {
    // React to exceptions if they occur
    // in the try block
} finally {
    // Close the resource when we're done
}

Finally is a nice way to clean everything after we are done, but has its own limitations. There can be multiple places where an exception may occur. That is when opening the resource, using it and even closing. That can result in a lot of boilerplate code, which is hard to read and error prone. We are talking about nested try-catch statements combined with null checks and more.

Most importantly, you need to remember to actually close all the resources and in the right order. That is, resources can have dependencies on each other, which you need to respect.

Fortunately, since Java 7, there is an easier way to manage resources automatically with try-with-resources, which will close all the resources properly for you in the right order.

Try with resources

Using try-with-resources is easy. Instead of just plain:

try {
    // Do something
} finally {
    // Close my resource
}

You create the resource directly after try keyword in parentheses, like this:

try (MyResource resource = new MyResource()) {
    // Do something
} // Resource is automatically closed after this block ends

You basically create a resource, which exists only inside the try block and cannot be accessed afterward. When the try block ends, the resource is automatically closed for you.

Now you ask what kind of resources you can use in try-with-resources and how does JVM know how to close them?

It is actually pretty simple. You can use all the resources, which implement Closeable or AutoCloseable interface. It has only one method called close() which is automatically called for you once the try block finishes. That means it is easy to provide your own custom resources. You can check all the classes implementing Closeable or AutoCloseable in their JavaDoc.

Note that in the example above, we used a simple case of try-with-resources using just try block. Of course, you can include both catch and finally blocks as well. In such case, the catch and finally blocks are executed after all the resource have been closed.

Decompiled example

Let's look at a simple example using try-with-resources, which uses two resources and has just one operation:

try (FileReader fileReader = new FileReader("C:\\foo.txt");
             BufferedReader bufferedReader = new BufferedReader(fileReader)) {

    bufferedReader.readLine();
}

If we decompile this using Fernflower decompiler, we get something similar to this:

FileReader fileReader = new FileReader("C:\\foo.txt");
Throwable var2 = null;

try {
    BufferedReader bufferedReader = new BufferedReader(fileReader);
    Throwable var4 = null;

    try {
        bufferedReader.readLine();
    } catch (Throwable var16) {
        var4 = var16;
        throw var16;
    } finally {
        $closeResource(var4, bufferedReader);
    }
} catch (Throwable var18) {
    var2 = var18;
    throw var18;
} finally {
    $closeResource(var2, fileReader);
}

It is an interesting example of how try-with-resources works under the hood. You can check the official specs for more detail.

Multiple resources

Inside the head of try-with-resources, you can declare more than one resource.

try (FileReader fileReader = new FileReader("C:\\foo.txt");
     BufferedReader bufferedReader = new BufferedReader(fileReader)) {
            // Read some data!
}

All the resources in the () parentheses are automatically closed for you. What's good to know is what is the order of closing. The resources are closed in the reverse order of their declaration to avoid any dependency issues.

That is, if we have three resources like this:

try (resource1; resource2; resource3) {
}

They are created in order of:

resource1
resource2
resource3

However, they are closed in the reverse order:

resource3
resource2
resource1

Java 9 improvements

Try with resources was introduced in Java 7. Until Java 9 you were forced to declare the resources and assign them a value in the parentheses right after try. This is a lot of text and noise, which makes try-with-resources hard to read, especially when using multiple resources.

try (FileReader fileReader = new FileReader("C:\\foo.txt"); 
     BufferedReader bufferedReader = new BufferedReader(fileReader)) {
    // Read some data!
}

Fortunately, since Java 9, you can just reference the name of the existing resource instead of its declaration and assignment. This is much more readable.

FileReader fileReader = new FileReader("C:\\foo.txt");
BufferedReader bufferedReader = new BufferedReader(fileReader);
        
try (fileReader; bufferedReader) {
    // Read some data!
}

It is not shorter, but when you check try-with-resources, you can immediately see which resources it uses without all the noise.

The limitation is, though that all the resources used need to be final of effectively final.

Implementing your own resources

The good news is that you can create your own resources, which can be used in try-with-resources. All you need to do is to implement either java.io.Closeable or java.lang.AutoCloseable.

How are they different? Closeable is older, available since Java 5, AutoCloseable was introduced in Java 7 along with try-with-resources. Since Java 7, Closeable actually extends AutoCloseable.

public interface AutoCloseable {
    void close() throws Exception;
}

public interface Closeable extends AutoCloseable {
    void close() throws IOException;
}

As you can see, they are very similar. The signature of the close() method is different only in the exception thrown. AutoCloseable can throw any Exception while Closeable throws IOException.

Note that when implementing an interface you can change the method signature in a way that it throws a different exception. Or no exception at all. According to the JavaDoc, it is highly recommended to do so in this case. Declare more specific exception in your implementation of close() method or no exception at all if it cannot fail.

There is one more difference, which you cannot see from the method's signature but from JavaDoc only. Closeable is required to be idempotent, AutoCloseable not (although it is highly recommended).

That means you should make sure calling close() multiple times would not cause any trouble.

IntelliJ IDEA integration

As usual, IDEA offers a nice support for try with resources feature. When you are using a resource, which implements AutoCloseable interface, you can surround it with try-with-resources. Just press Alt + Enter to open intention actions popup:

Using the same keyboard shortcut, IDEA allows you to convert traditional try-catch-finally to try-with-resources.

Alternatively, you can do the reverse operation using the same shortcut - convert try-with-resources to good old try-catch-finally.

Conclusion

Try with resources is a useful alternative to traditional try-catch-finally when working with resources, which need to be properly closed. The resource management is automatically handled for you. You can still use catch and finally blocks, as usual, they get executed after the resources are closed.

If you are on Java 9 and later, you don't need to declare your resources directly in the try header, but you can use previously declared resources, which are final or effectively final.

If you want to use your own resources, you can just implement Closeable or AutoCloseable interface and implement the close() method.

Java By Comparison Book Review

Sat, 13 Apr 2019 22:12:03 GMT

This book aims to teach you how to write cleaner, more elegant code in Java. It covers 70 issues of various topics with before and after comparison in a concise, easy to read and understand way.

Authors

The book was written by three authors: Simon Harrer, Jörg Lenhard and Linus Dietz.

The authors are teachers of Java programming courses. When they were evaluating students' assignments, they had to provide the same feedback for the same common issues over and over. A checklist with common issues and proper solutions would help a lot as they could only reference an item from this list when evaluating the assessments. That's how the idea for this book was born. It is a list of common issues and code smells in Java and what can you do to fix them.

Concept

The idea is simple. The book contains 70 independent items. Similar items are grouped into categories, such as comments, testing or exception handling. Each item covers a specific issue, such as "Always Catch Most Specific Exception".

Each item is not just a recommendation or a best practice. Instead, it starts with a problematic snippet of code, which works but has some smells. Then there is a description of what is exactly wrong and why.

On the next page there is a the original snippet, fixed according to a proposed best practice and an explanation of what changed and why is it better.

What is really useful is that the layout of the book consistently keeps each item just on two pages - on the left you can see the problem and on the right the solution. This makes it really easy to compare both at the same time.

I find this format very suitable. First of all, you have specific examples with code, both before and after applying the recommended best practices, which is way easier to understand than just an abstract recommendation. Having the problem presented first also gives you a nice opportunity to think about what's wrong before you are given the answer. This leads to better understanding and deeper learning than just reading recommended best practice outright.

Each item is independent of each other, which makes it easy to skip what you already know. You don't necessarily need to read this book front to back. This makes the book an ideal reference for mentoring and code reviews as you can easily point others just to a specific item.

Even though the items are technically independent, some code examples are further polished over the course of multiple items, which gives a better sense of continuity and understanding how multiple issues relate to each other.

Since each item needs to fit to exactly two pages, the writing style is concise and to the point, while still being easy to understand.

Audience

This book can be very useful to developers with various skill levels for different reasons.

If you are just starting with programming and Java and you're still struggling with basic concepts and syntax, this book may not be for you yet. In fact, at the beginning of the book there is a FizzBuzz test, which is supposed to determine whether you are ready for this book or not. If you are still in very early stages of learning Java and programming, you may want to wait a bit with this book until you grasp basic concepts. Only after learning some basics, you can understand how to write code which not only works, but is also clean and elegant.

You'll get most of this book as a junior Java developer or a person who is switching to Java from another language.

For intermediate devs, this still is useful. You can use the book as a refresher for what you already know and there should still be much to learn from it. Moreover, since the items are independent, you can just skip some items.

As a senior developer, you may not learn much yourself, but the book is a great resource when mentoring others or when doing code review. You can just point them to a specific item when reviewing their code.

The book works with Java 8, so it does not really matter if you're not familiar with all the newer versions of Java.

The book consists of 70 items divided into 9 chapters.

The first two chapters cover basic Java constructs such as iteration, conditions, enums, constants and more. Generally how to write cleaner code, which is less error-prone and easier to understand.

The third chapter covers comments. It guides you through which comments are useless and do more harm than good. Then what should be commented and how. On top of that, some JavaDoc specific advice.

The fourth chapter is dedicated to naming. It is very important to make sure your code is readable and easy to understand. And of course, as we know, "There are only two hard things in Computer Science: cache invalidation and naming things.".

The fifth chapter is focused on excepting handling.

The sixth chapter covers unit testing with JUnit 5. I was pleasantly surprised to see a topic like this in the book as it is not part of the core Java, but of course, it is very important nonetheless. And it is nice to show to beginners early on that testing is important.

The next chapter describes the object-oriented design. The topic is so broad that this book cannot meaningfully cover it on just a few pages.

Lambda expressions and streams are the topics of the eight chapter. It is a nice introduction to the topic with several useful good practices.

The last chapter breaks the usual format and offers a taste of other development areas, which you will encounter in the real world. There is static code analysis, continuous integration, team collaboration, logging, concurrency and more. If you already have some work experience, it may not be anything new. However, it offers a nice intro to the real world development if you are still preparing for your first job.

Conclusion

I really enjoyed this book and I wish I had a book like this when I was starting with Java. It can be a great resource early in your career. It is easy to read, short, easy to understand and can be a good book to read before more heavy-weight titles such as Effective Java or Clean Code, which can be intimidating and harder to grasp when you are just starting.

In your early days, it can also be useful as an introduction (although very brief) to some related real-world topics such as testing, continuous integration or static code analysis. Overall I do recommend this book especially for junior developers, who will benefit from it the most.

Free Samples

To help you decide whether this book is worth getting and reading, there are several free content examples available for free for you to check:

Useful Links

Java 13 Enhanced Switch

Sun, 07 Apr 2019 22:12:03 GMT

Java 12 introduced a whole lot of useful improvements to the good old switch, which makes it way more useful.

There will be syntax changes in Java 13, introducing the new yield statement. This article was updated to reflect it.

Traditional switch

Good old switch is available in Java from the very beginning, and little has changed since then until now. Java's switch follows closely the design of C and C++ including the weird parts.

Fall-through

Most notably, the infamous fall-through behavior. What does it mean? Let's look at a simple switch first:

switch (errorCode) {
    case 404:
        System.out.println("Not found!");
        break;
    case 418:
        System.out.println("I am a teapot!");
        break;
    case 500:
        System.out.println("Internal server error!");
        break;
    default:
        System.out.println("Unknown code!");
}

Nothing fancy, you supply an HTTP result code, and it prints what does it mean. For each code provided, only the corresponding block is executed. As long as you remember to include break.

When a case is matched and executed, the switch automatically continues to the next case unless there is a break statement.

Let's look at an example. Let's pretend we forgot to include a break in the case 404:

switch (errorCode) {
    case 404:
        System.out.println("Not found!");
        // missing break here !!!    case 418:
        System.out.println("I am a teapot!");
        break;
    case 500:
        System.out.println("Internal server error!");
        break;
    default:
        System.out.println("Unknown code!");
}

When we pass 404 to the switch, the first case is a match and the block inside is executed. Because there is no break, the execution continues to the case 418: block even though the input is clearly not 418. In this block, there is break, so the switch finally ends. The output is, however, the following:

Not found!
I am a teapot!

Not what we intended, right? While fall-through behavior can be useful sometimes, more often than not, it is just a result of accidentally missed break. Switch statements are therefore error-prone. In more complicated scenarios, when there is a missing break, you may be in doubt whether it is an error or it was intentional. It can be useful in low-level code, which is performance-sensitive, but in the high-level code, it can be dangerous.

Single value cases

One of the unfortunate limitations of the switch is that in each case, there can be just a single value. This forces you to rely on fall-through if you want to have the same behavior for multiple values.

switch (errorCode) {
    case 400:
    case 404:
    case 405:
        System.out.println("Something is wrong with the request!");
        break;
    case 500:
    case 501:
    case 505:
        System.out.println("Something is wrong with the server!");
        break;
}

What would be much simpler is specifying multiple values per case:

case 400, 404, 405:
    System.out.println("Something is wrong with the request!");

Unfortunately, the old traditional switch does not support this.

Enhanced Switch

Java 12 brought a whole lot of improvements to the traditional switch as Java Enhancement Proposal 325: Switch Expressions (Preview). It solves most of the issues of the traditional switch and is prerequisite of pattern matching, which is to be provided in the future.

Preview Feature

Enhanced switch functionality is, however, currently only available 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.

First, make sure you actually have JDK 13 installed. Then, in IntelliJ IDEA you can enable preview features under File → Project Structure.

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

javac --release 13 --enable-preview ...

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

java --enable-preview ...

Multiple values in a case

We already covered that one value per case is problematic and it limits you. Fortunately, with an enhanced switch, there is no longer such limitation. You can simply provide multiple comma-separated values:

switch (errorCode) {
    case 400, 404, 405:
        System.out.println("Something is wrong with the request!");
        break;
    case 500, 501, 505:
        System.out.println("Something is wrong with the server!");
        break;
}

Nice, concise and much easier to read than multiple cases with fall-through, right? So far, so good. Note that we still use break statements.

Switch expression

The traditional switch is a statement. In addition to that, the new switch also adds the possibility of switch expression.

What is the difference? In a nutshell, the statement is imperative to do some logic. The expression returns some value.

Take for example the if-else statement. If some condition is met, it executes if block. If the condition is not met, it executes else block:

if(condition) {
    // do something
} else {
    // do something else
}

The same if-else logic can be achieved with the ternary operator as an expression, which returns some value if the condition is met and a different value otherwise:

x = condition ? 1 : 2;

With the switch it is similar. The traditional switch is a statement. It directs the control flow based on your input. However, you can use the new switch also as an expression. That is, based on your input, it can directly return some value.

String message = switch (errorCode) {
    case 404:
        yield "Not found!";
    case 500:
        yield "Internal server error!";
    default:
        throw new IllegalArgumentException("Unexpected value: " + errorCode);
};

As you can see, we can now use the result of a switch expression and assign it to a variable.

Notice a few differences to the regular switch statement. First of all, it needs to end with a semicolon. Then, there is a new keyword yield. It is similar to the return statement. But for switch expression instead. It marks value to be returned from a switch branch. Because yield terminates the switch expression, you don't need to have break after it.

The yield statement is targeted to be introduced in Java 13. For Java 12, you should use break instead. See History Section below.

Null Pointer Exception Safety

There is another significant difference. Unlike with regular switch, the switch expression needs to cover all the possible input values.

Let's look at the previous example. The errorCode input is an integer. It has, of course, many possible values. Two first cases cover 404 and 500, the rest of the values is covered with the default branch.

That means that all possible integer values are covered. No matter what the input is, the switch always returns something. Or throws an exception explicitly. Let's try to remove the default branch just as a test.

String message = switch (errorCode) {
    case 404:
        yield "Not found!";
    case 500:
        yield "Internal server error!";
    // default:
    //    throw new IllegalArgumentException("Unexpected value: " + errorCode);
};

This will result in the following error:

Error:(11, 26) java: the switch expression does not cover all possible input values

So with switch expression, you have to cover all the possible inputs. Either by providing case for all the possible values (which can be easy for enums) or by providing default case.

This has some nice implications. The regular switch is error-prone when you forget to include one of the values, for example when using enums. Or when you later add another enum item but forget to update your switch statements. This cannot happen with switch expression as you would get compile error. Also, you cannot get null pointer exception as a result of the switch expression.

Switch with arrows

So far we've seen some nice improvements to the good old switch. One of the major nuisances was not covered though. Even with multi-value case blocks, we still had to make sure we included break properly otherwise we could face some nasty fall-through bugs.

Fortunately, the new switch can prevent this. There is a new type of syntax available using ->.

switch (errorCode) {
      case 404 -> System.out.println("Not found!");
      case 500 -> System.out.println("Internal server error!");
}

This syntax can be used for both switch statement and switch expression. In the example above we are using a simple switch statement. In the case of -> switch you don't need to include break and it does not have fall-through behavior. And you can still use multiple values per one case.

It's more concise, easier to read and fool-proof — no more nasty errors.

Now you have two options: if you want to use fall-through behavior, you use the switch with case:, otherwise, you can use the switch with case ->. Whatever approach you use, you need to stick with it for all the case branches in one switch. This results in an error:

// Invalid: both 'case:' and 'case ->' in the same switch
switch (errorCode) {
    case 404 -> System.out.println("Not found!");
    case 500: System.out.println("Internal server error!");
}

Scope

One of the issues with the traditional switch is its scope. The whole switch statement is a single scope. That means if you declare a variable in one of the case branches, it exists in all the subsequent branches until the end of the switch.

switch (errorCode) {
    case 404:
        System.out.println();
        String message = "Not found!";
        break;
    case 500:
        // Cannot declare 'message', it already exists
        String message = "Internal server error!";
        break;
}

This is, of course, needed for the proper working of fall-through behavior. If you want to threat individual case branches as separate scope, you need to introduce a {} block, which is treated as a separate scope:

switch (errorCode) {
    case 404: {
        // This variable exists just in this {} block
        String message = "Not found!";
        break;
    }
    case 500: {
        // This is ok, {} block has a separate scope
        String message = "Internal server error!";
        break;
    }
}

With switch using -> there is no confusion with scoping. On the right side of -> there can be either a single statement/expression, throw statement or a {} block. As a consequence of this, any local variables you want to declare and then use needs to be enclosed in a {} block, which has its own scope, so no more variable clashing.

IntelliJ IDEA support

The good news is that IDEA already has nice support for the extended switch.

In the example below, you can see a quick-fix for replacing the traditional switch with a switch expression. Note that IDEA also automatically adds a default branch, so all the possible inputs are covered.

IDEA also warns you when your switch is not compliant, such as in a case where you don't cover all the possible input values. Moreover, it offers you a quick fix:

If idea detects you have multiple case branches with the same behavior, it will warn you and offer you to merge these branches together:

History

The enhanced switch was originally introduced with Java 12 as JEP-325 - a preview feature, which needs to be explicitly enabled. This was to gather feedback and gain more time for potential further refinement.

For Java 13, there was another proposal introduced - JEP-354, which changed the syntax of returning value from a switch expression.

The original syntax in Java 12 used break keyword followed by the value to be returned.

String message = switch (errorCode) {
    case 404:
        break "Not found!";
    case 500:
        break "Internal server error!";
    default:
        throw new IllegalArgumentException("Unexpected value: " + errorCode);
};

In Java 13, this syntax changes to yield:

String message = switch (errorCode) {
    case 404:
        yield "Not found!";
    case 500:
        yield "Internal server error!";
    default:
        throw new IllegalArgumentException("Unexpected value: " + errorCode);
};

Having a break with return value was a bit confusing and hard to tell apart from regular labeled break. It was harder to visually distinguish a switch statement from switch expression. Now it is much easier to tell them apart:

Switch statement only uses break and never yield
Switch expression only uses yield and never break

The original proposal in Java 13 was break-with, which would be the first hyphenated keyword in Java so far. But it was later replaced with yield.

Future enhancements

As part of the JEP-325 specification, there is also mentioned another improvement, which is not currently implemented (as of Java 13), but may be introduced in the future.

As a target of opportunity, we may expand switch to support switching on primitive types (and their box types) that have previously been disallowed, such as float, double, and long.

Currently, the switch allows input values only of types char, int, byte, short, their object wrappers (Character, Byte, Short, Integer) and String (since Java 7).

Summary

In Java 13 enhanced switch is a preview feature, which needs to be explicitly enabled
You can now use case for multiple values
In addition to the traditional switch statement, you can use switch expression, which returns a value
To return a value from a switch expression you can use:
- break in Java 12
- yield in Java 13
Switch expression must cover all possible input values of given input type
You can use new -> syntax which does not have fall-through and does not require a break
You cannot combine case: and case -> in one switch
Both switch expressions and switch statements can use both case syntax (-> or :)

Vojtech Ruzicka's Programming Blog

Commitlint: validate your commit conventions automatically

Commit conventions

Githooks & Husky

Easy git hooks with Husky

Commitlint

Local setup

Husky

Commitlint

Convention configuration

Verifying the setup

Continous Integration

Travis

Commitlint GitHub action

Commit message wizard

Prompt CLI

Commitizen

Custom configuration

Example repo

Conclusion

Stackbit: build JAMStack sites in a few clicks

JAMStack

Migration to GatsbyJS and JAM stack from WordPress

Building Static sites

Stackbit

Creating a new site

1. Selecting a theme

2. Selecting a static site generator

3. Selecting a CMS

4. Deployment

Migration to JAM stack and Netlify from WordPress

Dashboard

Medium import

DEV.to integration

Beta

Conclusion

Comparing files and folders in IntelliJ IDEA

Comparing project files

Comparing with non-project file

Comparing with the clipboard

Custom comparison

Comparing with the previous local version of the file

Compare with VCS

Comparing Folders

Synchronizing folders

Netlify Analytics Review: Google Analytics alternative?

Netlify Analytics

Migration to JAM stack and Netlify from WordPress

Advantages

Better performance

Works with adblockers

Works with Javascript disabled

Historical data when enabled

Error & Not Found pages

Simplicity

Disadvantages

Accuracy

Limited date range

Limited functionality

Price

Conclusion

JavaFX Tutorial: CSS Styling

Separating visuals

CSS

Selectors

Class

Built-in classes

Custom classes

ID

Properties

Pseudo-classes

Custom pseudo-classes

Default stylesheet

Scene stylesheet

Parent stylesheet

Inline styles

Why to avoid them

Stylesheet priorities

Further reading

JavaFX Tutorial: Advanced layouts