Create and Run Your First ZK Application with Spring Boot"

From Documentation
(28 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
__TOC__
 
__TOC__
  
=The zk-spring-boot Example=
+
== Starting from Scratch ==
The example project is located on [https://github.com/zkoss-demo/zk-spring-boot github/zkoss-demo/zk-spring-boot].
 
To use it all you need is a command line interface (and optional: git).
 
  
This example is based on the [https://spring.io/guides/gs/spring-boot/ Spring Boot - Getting Started Guide] extending it by adding the required ZK dependencies and necessary configuration in order to start a ZK project with the Spring Boot platform.
+
To get started follow these simple steps or clone/run one of the available demos.
 +
 
 +
'''1. Download/unzip a standard [https://start.spring.io/ Spring Initializr] project'''
 +
 
 +
(no addons needed, tested with version 2.0.4.RELEASE)
 +
 
 +
'''2. Add ZK's maven-repository and the zkspringboot-starter dependency'''
 +
 
 +
In pom.xml add: replace ${zkspringboot.version} with the [http://mavensync.zkoss.org/maven2/org/zkoss/zkspringboot/zkspringboot-starter/ latest version]
 +
 
 +
<source lang="xml">
 +
<repositories>
 +
<repository>
 +
<id>ZK CE</id>
 +
<name>ZK CE Repository</name>
 +
<url>http://mavensync.zkoss.org/maven2</url>
 +
</repository>
 +
</repositories>
 +
...
 +
<dependencies>
 +
...
 +
<dependency>
 +
<groupId>org.zkoss.zkspringboot</groupId>
 +
<artifactId>zkspringboot-starter</artifactId>
 +
<type>pom</type>
 +
<version>${zkspringboot.version}</version>
 +
</dependency>
 +
<dependencies>
 +
</source>
 +
 
 +
'''3. Create a simple zul file'''
 +
 
 +
e.g: src/main/resources/web/hello.zul
 +
 
 +
<source lang="xml">
 +
<zk>
 +
    <window title="Hello ZK - Spring Boot!" border="normal">
 +
        You are using ZK version <label value="${session.webApp.version}"/>
 +
    </window>
 +
</zk>
 +
</source>
 +
 
 +
'''4. Define a homepage'''
 +
 
 +
in src/main/resources/application.properties
 +
<source>
 +
zk.homepage=hello
 +
</source>
 +
 
 +
'''5. Run the application'''
 +
 
 +
execute the command (on windows omit the './' prefix)
 +
 
 +
<source>
 +
./mvnw spring-boot:run
 +
</source>
 +
 
 +
'''6. Open the URL'''
 +
 
 +
http://localhost:8080
 +
 
 +
Now you have a ZK application running on Spring boot. For further details and differences to a ''normal'' ZK web application read the details below.
 +
 
 +
== The ZK - Spring Boot Demos ==
 +
 
 +
The demo projects are located on [https://github.com/zkoss/zkspringboot/tree/master/zkspringboot-demos github/zkoss/zkspringboot].
 +
To run them all you need is a command line interface (and optional: git).
 +
 
 +
These examples are derived from the [https://spring.io/guides/gs/spring-boot/ Spring Boot - Getting Started Guide] replacing the '''springboot-starter-web''' dependency by '''zkspringboot-starter''' to enable convenient auto-configuration for the most common usage scenarios while allowing customization where needed.
  
 
== Differences to a "normal" ZK Web Application ==
 
== Differences to a "normal" ZK Web Application ==
Line 12: Line 78:
 
=== Configuration ===
 
=== Configuration ===
  
As Spring Boot prefers Java- over XML-configuration and doesn't require a classical src/main/webapp-folder (and no WEB-INF/).  
+
As Spring Boot prefers Java- over XML-configuration and doesn't require a classical src/main/webapp-folder (and no WEB-INF/).
 
Hence the ZK configuration files are moved to a different files/folders:
 
Hence the ZK configuration files are moved to a different files/folders:
  
'''zk.xml''' was moved to a classpath location:
+
'''zk.xml''' and '''zk-label.properties''' were moved to a classpath location:
  src/main/webapp/WEB-INF/zk.xml -> src/main/resources/metainfo/zk/zk.xml
+
  src/main/webapp/WEB-INF/zk.xml -> src/main/resources/'''metainfo/zk'''/zk.xml
 +
src/main/webapp/WEB-INF/zk-label.properties -> src/main/resources/'''metainfo'''/zk-label.properties
 +
 
  
 
'''web.xml''' configuration such as servlets/filters are configured the "Spring Boot Way" using java configuration
 
'''web.xml''' configuration such as servlets/filters are configured the "Spring Boot Way" using java configuration
  src/main/webapp/WEB-INF/web.xml -> src/main/java/zk/springboot/config/ZKCEConfig / ZKEEConfig
+
  src/main/webapp/WEB-INF/web.xml -> auto configuration is provided by the zkspringboot-starter dependency (configurable via [https://github.com/zkoss/zkspringboot#configuration-options-for-spring-boot-style-applicationproperties application.properties])
 
 
[https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKCEConfig.java ZKCEConfig.java] and [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKEEConfig.java ZKEEConfig.java] can be changed to fit your requirements, e.g. disable websocket filter (when used with an older ZK version < 8.5) or richlet filter if not needed.
 
  
Adding them to the Spring Boot main [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/Application.java Application] class can be done using the annotations [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKCEApplication.java @ZKCEApplication] or [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKEEApplication.java @ZKEEApplication.java]:
+
After adding the zkspringboot-starter dependency the @SpringBootApplicatio-annotation is sufficient to make initialize ZK.
  
<source lang="java" high="2">
+
<source lang="java" high="1">
 
@SpringBootApplication
 
@SpringBootApplication
@ZKEEApplication
 
 
public class Application  {
 
public class Application  {
 
public static void main(String[] args) {
 
public static void main(String[] args) {
Line 35: Line 100:
 
</source>
 
</source>
  
Also the DHtmLayoutServlet is obsolete in a jar deployment. It tried to locate zul files from the servlet context resources, which doesn't exist when deploying packaging a spring boot application as a jar file. That's why the configuration for this Servlet is commented out in this example. (In a war file it can be used as before.)
+
For a single-page-application all you need is to specify a view name as the zk.homepage parameter in the application.properties (or specify a richlet).
 +
 
 +
Multiple zul-files as entry points for your application are defined using Spring-MVC's @GetMapping annotatios.
  
Mappings to Zul-Files as entry points for your application can be resolved with the ViewResolver, which will forward your views to ZK's dHtmlUpdateServlet internally.
 
 
see:  
 
see:  
* [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKCEConfig.java#L28-L32 ZKCEConfig.java] -> View resolver
+
* [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/resources/application.properties application.properties] -> homepage / view-resolver / richlet config
* [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/Application.java#L19-L27 Application.java] -> application specific page mappings
+
* [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/java/org/zkoss/zkspringboot/demo/DemoApplication.java DemoApplication.java] -> application specific page mappings
  
 
=== Application structure ===
 
=== Application structure ===
  
In this example the zul files are located below the class web resource folder [https://github.com/zkoss-demo/zk-spring-boot/tree/master/src/main/resources/web/zul src/main/resources/web/zul/]  
+
In the zkspringboot-demo-jar example the zul files are located below the class web resource folder [https://github.com/zkoss-demo/zk-spring-boot/tree/master/src/main/resources/web/zul src/main/resources/web/zul/]  
  
You can configure any folder below '''src/main/resources/web''' in [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKCEConfig.java#L18 ZKCEConfig.java].
+
You can configure any folder below '''src/main/resources/web''' using the <code>zk.zul-view-resolver-prefix</code>-property [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/resources/application.properties in application.properties]. The extension .zul is added automatically by the default value of <code>zk.zul-view-resolver-suffix</code>.
  
zul files can be referenced like this:
+
By default this view resolver is enabled, and can be disabled via <code>zk.zul-view-resolver-enabled</code> (e.g. if no zul files are used (just richlets, or jsp's embedding zul files) or a custom implementation is preferred).
 +
 
 +
Inside the Zk application zul files (to be included) can be referenced like this:
 
<source lang="xml">
 
<source lang="xml">
 
     <include src="~./zul/mvvm-page1.zul"/>
 
     <include src="~./zul/mvvm-page1.zul"/>
Line 56: Line 124:
 
General resource folders are:
 
General resource folders are:
  
* [https://github.com/zkoss-demo/zk-spring-boot/tree/master/src/main/resources/static src/main/resources/static] Spring Boot's resource folder
+
* [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/resources/static src/main/resources/static] Spring Boot's resource folder
* [https://github.com/zkoss-demo/zk-spring-boot/tree/master/src/main/resources/web src/main/resources/web] ZK's class web resource folder  
+
* [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/resources/web src/main/resources/web] ZK's class-web-resource folder  
  
 
Spring Boot resources are referenced by urls starting with <code>'/'</code> ZK resources (including zul files) are prefixed with <code>'~./'</code>
 
Spring Boot resources are referenced by urls starting with <code>'/'</code> ZK resources (including zul files) are prefixed with <code>'~./'</code>
Line 67: Line 135:
 
</source>
 
</source>
  
Examples how to access resources from either resource folder ar:
+
Examples how to access resources from either resource folder are:
* from a zul file: [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/resources/web/zul/resources.zul src/main/resources/web/zul/resources.zul]
+
* from a zul file: [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/resources/web/zul/resources.zul src/main/resources/web/zul/resources.zul]
* global resources: [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/resources/metainfo/zk/lang-addon.xml src/main/resources/metainfo/zk/lang-addon.xml]
+
* global resources: [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/resources/metainfo/zk/lang-addon.xml src/main/resources/metainfo/zk/lang-addon.xml]
 
 
== Download/Clone the example project ==
 
 
 
With the git command line installed all you need is to clone the example repository:
 
  
    git clone https://github.com/zkoss-demo/zk-spring-boot.git
+
=== Zats Testing ===
  
Alternatively you can download the example as a [https://github.com/zkoss-demo/zk-spring-boot/archive/master.zip zip-package].
+
Since Zats is running its own embedded jetty, it can't use the same application startup mechanism as plain spring boot. In order to allow Zats tests, the Application configuration must be loaded from a separate web.xml (note it is in src/'''test'''/webapp so it doesn't affect the production deployment).  
  
Once cloned/unzipped open a command line in the project folder.
+
As of now you can specify your test context configuration class (e.g. <code>zk.springboot.Application</code>) as a [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/test/webapp/WEB-INF/web.xml context parameter inside web.xml]. The customized ContextLoaderListener ([https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-autoconfig/src/main/java/org/zkoss/zkspringboot/zats/ZatsSpringBootContextLoaderListener.java ZatsSpringBootContextLoaderListener.java]) reads this parameter and initializes the application context accordingly.
  
In order to get started immediately the project includes the [https://docs.gradle.org/current/userguide/gradle_wrapper.html gradle-wrapper] and [https://github.com/takari/maven-wrapper maven-wrapper].
+
E.g. the [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/test/java/org/zkoss/zkspringboot/demo/DemoPageTest.java DemoPageTest]-case refers to this web.xml to initialize the spring boot application inside Zats' embedded Jetty.  
  
During the first execution gradle/maven will download itself and all the required project dependencies automatically. This will initially take quite a few minutes while showing the overall progress. Subsequent executions will be faster as gradle/maven will cache downloaded resources. For additional information on gradle/maven please refer to their official documentation.
+
As usual, alternative test-configuration is possible if needed.
  
== Useful build tasks ==
+
(Feedback regarding a cleaner startup of a Spring Boot project in an alternative embedded container is welcome, to avoid extending/overriding Framework classes.)
  
'''NOTE''': Using the windows command line (''cmd'') you have to omit the "./" in front of the commands
+
== Download/Clone the example project ==
  
build self executable jar
+
With the git command line installed all you need is to clone the example repository (Alternatively download a [https://github.com/zkoss/zkspringboot/archive/master.zip zip-package]):
  
with gradle-wrapper
+
    git clone https://github.com/zkoss/zkspringboot
./gradlew clean build
+
    cd zkspringboot/zkspringboot-demos
  
with maven-wrapper
+
In order to get started immediately the project includes the [https://docs.gradle.org/current/userguide/gradle_wrapper.html gradle-wrapper] and [https://github.com/takari/maven-wrapper maven-wrapper].
./mvnw clean package
 
  
== Run the Project ==
+
During the first execution gradle/maven will download itself and all the required project dependencies automatically. This will initially take quite a few minutes while showing the overall progress. Subsequent executions will be faster as gradle/maven will cache downloaded resources. For additional information on gradle/maven please refer to their official documentation.
  
for gradle:
+
== Build / Run the Project ==
java -jar build/libs/zk-spring-boot-0.1.0.jar
 
  
for maven
+
Please follow the instructions in the [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/README.md README.md].
java -jar target/zk-spring-boot-0.1.0.jar
 
  
After a short startup time you'll see an output like this.
+
== Import the project into your IDE ==
  
... Started ServerConnector@5536379e{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
+
The project itself designed to work from command line and independent of any IDE. Since it's both a gradle or maven project you can import it into your favorite IDE using the standard plugins provided by the IDE.
... Jetty started on port(s) 8080 (http/1.1)
 
... Started Application in 4.328 seconds (JVM running for 4.987)
 
  
The test pages are now available under:
+
'''TIP''': The main class [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/java/org/zkoss/zkspringboot/demo/DemoApplication.java org.zkoss.zkspringboot.demo.DemoApplication] can be executed directly in your IDE for development and debugging.
  
http://localhost:8080/mvvm.zul (small MVVM example showing subnavigation and spring service integration)
+
Useful [https://github.com/zkoss/zkspringboot/blob/master/zkspringboot-demos/zkspringboot-demo-jar/src/main/java/org/zkoss/zkspringboot/demo/DevelopmentConfig.java DevelopmentConfig] can be enabled by activating the '''dev'''-profile as a VM argument in your run configuration.
  
http://localhost:8080/resources.zul (examples of accessing static resources the "springboot way" vs the "zk way")
+
    -Dspring.profiles.active=dev
 
 
http://localhost:8080/richlet/test (sample richlet - zk in pure java)
 
 
 
== Import the project into your IDE ==
 
  
The project itself designed to work from command line and independent of any IDE. Since it's both a gradle or maven project you can import it into your favorite IDE using the provided plugins.
+
This will disable resource caches allowing to replace zul/css/js/image files without restarting the application.
  
'''TIP''': The main class [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/Application.java zk.springboot.Application] can be executed directly in your IDE for development and debugging.
 
  
 
{{ZKInstallationGuidePageFooter}}
 
{{ZKInstallationGuidePageFooter}}

Revision as of 10:56, 10 February 2020


DocumentationZK Installation GuideQuick StartCreate and Run Your First ZK Application with Spring Boot
Create and Run Your First ZK Application with Spring Boot



Starting from Scratch

To get started follow these simple steps or clone/run one of the available demos.

1. Download/unzip a standard Spring Initializr project

(no addons needed, tested with version 2.0.4.RELEASE)

2. Add ZK's maven-repository and the zkspringboot-starter dependency

In pom.xml add: replace ${zkspringboot.version} with the latest version

	<repositories>
		<repository>
			<id>ZK CE</id>
			<name>ZK CE Repository</name>
			<url>http://mavensync.zkoss.org/maven2</url>
		</repository>
	</repositories>
	...
	<dependencies>
		...
		<dependency>
			<groupId>org.zkoss.zkspringboot</groupId>
			<artifactId>zkspringboot-starter</artifactId>
			<type>pom</type>
			<version>${zkspringboot.version}</version>
		</dependency>
	<dependencies>

3. Create a simple zul file

e.g: src/main/resources/web/hello.zul

<zk>
    <window title="Hello ZK - Spring Boot!" border="normal">
        You are using ZK version <label value="${session.webApp.version}"/>
    </window>
</zk>

4. Define a homepage

in src/main/resources/application.properties

zk.homepage=hello

5. Run the application

execute the command (on windows omit the './' prefix)

./mvnw spring-boot:run

6. Open the URL

http://localhost:8080

Now you have a ZK application running on Spring boot. For further details and differences to a normal ZK web application read the details below.

The ZK - Spring Boot Demos

The demo projects are located on github/zkoss/zkspringboot. To run them all you need is a command line interface (and optional: git).

These examples are derived from the Spring Boot - Getting Started Guide replacing the springboot-starter-web dependency by zkspringboot-starter to enable convenient auto-configuration for the most common usage scenarios while allowing customization where needed.

Differences to a "normal" ZK Web Application

Configuration

As Spring Boot prefers Java- over XML-configuration and doesn't require a classical src/main/webapp-folder (and no WEB-INF/). Hence the ZK configuration files are moved to a different files/folders:

zk.xml and zk-label.properties were moved to a classpath location:

src/main/webapp/WEB-INF/zk.xml -> src/main/resources/metainfo/zk/zk.xml
src/main/webapp/WEB-INF/zk-label.properties -> src/main/resources/metainfo/zk-label.properties


web.xml configuration such as servlets/filters are configured the "Spring Boot Way" using java configuration

src/main/webapp/WEB-INF/web.xml -> auto configuration is provided by the zkspringboot-starter dependency (configurable via application.properties)

After adding the zkspringboot-starter dependency the @SpringBootApplicatio-annotation is sufficient to make initialize ZK.

@SpringBootApplication
public class Application  {
	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}
}

For a single-page-application all you need is to specify a view name as the zk.homepage parameter in the application.properties (or specify a richlet).

Multiple zul-files as entry points for your application are defined using Spring-MVC's @GetMapping annotatios.

see:

Application structure

In the zkspringboot-demo-jar example the zul files are located below the class web resource folder src/main/resources/web/zul/

You can configure any folder below src/main/resources/web using the zk.zul-view-resolver-prefix-property in application.properties. The extension .zul is added automatically by the default value of zk.zul-view-resolver-suffix.

By default this view resolver is enabled, and can be disabled via zk.zul-view-resolver-enabled (e.g. if no zul files are used (just richlets, or jsp's embedding zul files) or a custom implementation is preferred).

Inside the Zk application zul files (to be included) can be referenced like this:

    <include src="~./zul/mvvm-page1.zul"/>
    <apply templateURI="~./zul/mvvm-page1.zul"/>

General resource folders are:

Spring Boot resources are referenced by urls starting with '/' ZK resources (including zul files) are prefixed with '~./'

e.g.

    <image src="/img/zklogo1.png"/>      <!-- src/main/resources/static/img/zklogo1.png -->
    <image src="~./img/zklogo1.png"/>    <!-- src/main/resources/web/img/zklogo3.png -->

Examples how to access resources from either resource folder are:

Zats Testing

Since Zats is running its own embedded jetty, it can't use the same application startup mechanism as plain spring boot. In order to allow Zats tests, the Application configuration must be loaded from a separate web.xml (note it is in src/test/webapp so it doesn't affect the production deployment).

As of now you can specify your test context configuration class (e.g. zk.springboot.Application) as a context parameter inside web.xml. The customized ContextLoaderListener (ZatsSpringBootContextLoaderListener.java) reads this parameter and initializes the application context accordingly.

E.g. the DemoPageTest-case refers to this web.xml to initialize the spring boot application inside Zats' embedded Jetty.

As usual, alternative test-configuration is possible if needed.

(Feedback regarding a cleaner startup of a Spring Boot project in an alternative embedded container is welcome, to avoid extending/overriding Framework classes.)

Download/Clone the example project

With the git command line installed all you need is to clone the example repository (Alternatively download a zip-package):

   git clone https://github.com/zkoss/zkspringboot
   cd zkspringboot/zkspringboot-demos

In order to get started immediately the project includes the gradle-wrapper and maven-wrapper.

During the first execution gradle/maven will download itself and all the required project dependencies automatically. This will initially take quite a few minutes while showing the overall progress. Subsequent executions will be faster as gradle/maven will cache downloaded resources. For additional information on gradle/maven please refer to their official documentation.

Build / Run the Project

Please follow the instructions in the README.md.

Import the project into your IDE

The project itself designed to work from command line and independent of any IDE. Since it's both a gradle or maven project you can import it into your favorite IDE using the standard plugins provided by the IDE.

TIP: The main class org.zkoss.zkspringboot.demo.DemoApplication can be executed directly in your IDE for development and debugging.

Useful DevelopmentConfig can be enabled by activating the dev-profile as a VM argument in your run configuration.

   -Dspring.profiles.active=dev

This will disable resource caches allowing to replace zul/css/js/image files without restarting the application.



Last Update : 2020/02/10

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.