Project setup

Project generation

To build the basic frame of the project, we generate a new Maven project using the linkki Spring archetype. There are two ways to do that:

1. Generating the project from the command line

We can generate the project using Maven on the command line. In order to do that, we execute the command

mvn archetype:generate \
-DarchetypeGroupId=org.linkki-framework.archetypes \
-DarchetypeArtifactId=linkki-archetype-spring-application-vaadin8 \
-DarchetypeVersion=1.1.1

We are prompted to choose several values for the project. You can choose freely which group ID, artifact ID, version and package name you want to use. The value for ApplicationName should be set to "BusinessPartner" and the theme-name to "business-partner".

Once the generation is completed, you can import the new project into your favored IDE.

2. Generating the project in Eclipse

Alternatively, when using Eclipse we can use the wizard for new Maven Projects. Start the wizard by selecting File - New - Project - Maven - Maven Project. When selecting the archetype, choose

  • Group Id org.linkki-framework.archetypes

  • Artifact Id linkki-archetype-spring-application-vaadin8 and

  • Version 1.1.1.

dialogselectarchetype
Figure 1. Selecting the archetype

In the next step, set the project’s group ID, artifact ID, version and package name however you want. The property ApplicationName should be set to "BusinessPartner" and theme-name to "business-partner".

dialogmavenproject
Figure 2. Generate project in Eclipse

Initial project structure

The created project contains a HelloPmo class, a BusinessPartnerPage, a MainView that we will modify later and fundamental units for our application such as the BusinessPartnerUI, the BusinessPartnerApplicationConfig and the BusinessPartnerApplication.

initialprojectstructure
Figure 3. Structure of the generated project
BuinessPartnerUI

The BusinessPartnerUI is the entry point of the application’s UI. For further information have a look at the Vaadin application overview documentation.

BusinessPartnerApplication

The BusinessPartnerApplication contains the main method that runs the application.

MainView

This view will show the browser window containing the search bar and the search result table later. Note that this class is annotated with the Spring annotation @SpringView. To get a better understanding for the annotation, have a look at the section "Spring Views" in the Vaadin Spring Tutorial. The string constant NAME is chosen to be empty to make this view our starting view.

To get a better understanding of the other classes this archetype creates, refer to the section Components in the chapter Application Framework of the linkki Documentation.

Example application

The project as-is is already a runnable web application. Try starting the BusinessPartnerApplication as a Java application. Once startup is completed, open the URL http://localhost:8080/ in a browser and you should see the example application below.

exampleapplication
Figure 4. linkki example application

Getting ready

Now that we have the basic frame of a linkki web application using Spring Boot, we are almost done with the initial project setup. Before we move on, we remove some elements of the example application:

  • The classes HelloPmo and BusinessPartnerPage are not needed and thus can be deleted. We will build our own UI classes. The packages however will be needed later.

  • We switch to the MainView and delete its constructor.

We also need to include the domain model. To do that, we simply add the dependency linkki-sample-model in the pom.xml.

<dependency>
	<groupId>org.linkki-framework.tutorial</groupId>
	<artifactId>sample-model</artifactId>
	<version>1.1.1</version>
</dependency>

This project includes the model classes BusinessPartner and Address describing a business partner. The Validation class completes the model by providing validation functionality.

The model project also provides an interface BusinessPartnerRepository with a default implementation InMemoryBusinessPartnerRepository that stores business partners.

We have to provide an instance of this repository as a Java Bean, so that the Spring framework can inject it where we need it later. We can accomplish this by adding a createBusinessPartnerRepository method to our Application class and marking it with the Spring @Bean annotation.

BusinessPartnerApplication.java
    @Bean
    public BusinessPartnerRepository createBusinessPartnerRepository() {
        return InMemoryBusinessPartnerRepository.newSampleRepository();
    }

Now the initial project setup is done. If we run the application now, we get an almost empty browser window. All we can see is a blue menu bar on the top of the window with a little question mark on it. This opens a dialog that contains some basic application information that can be configured in the BusinessPartnerApplicationConfig.

emptyapplication
Figure 5. Empty linkki application

Let’s begin with the step-by-step tutorial.