Create and Run Your First ZK Application with Spring Boot"

From Documentation
(21 intermediate revisions by the same user not shown)
Line 8: Line 8:
 
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.
 
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.
  
== Differences to a normal ZK Web Application ==
+
== Differences to a "normal" ZK Web Application ==
  
 
=== Configuration ===
 
=== Configuration ===
  
As Spring Boot prefers Java- over XML-configuration and doesn't require a classical src/main/webapp-folder (and no WEB-INF/) the ZK configuration is moved to a different folder:
+
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
  
'''zk.xml''' was moved to a classpath location:
 
src/main/webapp/WEB-INF/zk.xml -> src/main/resources/metainfo/zk/zk.xml
 
  
 
'''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 -> src/main/java/zk/springboot/config/ZKCEConfig / ZKEEConfig
 +
  
 
[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.
 
[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 @Import annotation:
+
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]:
  
 
<source lang="java" high="2">
 
<source lang="java" high="2">
 
@SpringBootApplication
 
@SpringBootApplication
@Import(ZKEEConfig.class) /*ZK EE config includes CE*/
+
@ZKEEApplication
 
public class Application  {
 
public class Application  {
 
public static void main(String[] args) {
 
public static void main(String[] args) {
Line 34: Line 38:
 
</source>
 
</source>
  
Also the DHtmLayoutServlet is obsolete it tries 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.)
+
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.)
 
 
The current alternative is a @RequestMapping which will forward requests to zul files ('''/**/*.zul''') to ZK's dHtmlUpdateServlet internally.
 
see: https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/main/java/zk/springboot/config/ZKCEConfig.java#L21-L37
 
  
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/] (you can choose/configure any folder below src/main/resources/web).
+
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.
  
That gives 2 different resource folders
+
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-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-demo/zk-spring-boot/tree/master/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
 
 
Examples how to access resources from either resource folder ar:
 
* 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]
 
* 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]
 
 
=== Application structure ===
 
=== Application structure ===
  
When deploying the application as a 'fat' jar (self executable jar)
+
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/]
  
== Download/Clone the example project ==
+
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].
  
With the git command line installed all you need is to clone the example repository:
+
zul files can be referenced like this:
 +
<source lang="xml">
 +
    <include src="~./zul/mvvm-page1.zul"/>
 +
    <apply templateURI="~./zul/mvvm-page1.zul"/>
 +
</source>
  
    git clone https://github.com/zkoss-demo/zk-spring-boot.git
+
General resource folders are:
  
Alternatively you can download the example as a [https://github.com/zkoss-demo/zk-spring-boot/archive/master.zip zip-package].
+
* [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-demo/zk-spring-boot/tree/master/src/main/resources/web src/main/resources/web] ZK's class web resource folder
  
Once cloned/unzipped open a command line in the project folder.
+
Spring Boot resources are referenced by urls starting with <code>'/'</code> ZK resources (including zul files) are prefixed with <code>'~./'</code>
  
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.
 +
<source lang="xml">
 +
    <image src="/img/zklogo1.png"/>      <!-- src/main/resources/static/img/zklogo1.png -->
 +
    <image src="~./img/zklogo1.png"/>    <!-- src/main/resources/web/img/zklogo3.png -->
 +
</source>
  
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.
+
Examples how to access resources from either resource folder ar:
 +
* 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]
 +
* 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]
  
== Useful build tasks ==
+
=== 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).
  
'''NOTE''': Using the windows command line (''cmd'') you have to omit the "./" in front of the commands
+
(Feedback regarding a cleaner startup of a Spring Boot project in an alternative embedded container is welcome, to avoid extending/overriding Framework classes.)
  
build self executable jar
+
As of now you can specify your test context configuration class (e.g. <code>zk.springboot.Application</code>) as a [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/test/webapp/WEB-INF/web.xml#L12 context parameter inside web.xml]. The customized ContextLoaderListener ([https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/test/java/zk/springboot/test/config/ZatsSpringBootContextLoaderListener.java ZatsSpringBootContextLoaderListener.java]) reads this parameter and initializes the application context accordingly.
  
with gradle-wrapper
+
The [https://github.com/zkoss-demo/zk-spring-boot/blob/master/src/test/java/zk/springboot/test/PageTest.java#L17 PageTest] case refers to this web.xml to initialize the spring boot application inside Zats' embedded Jetty.  
./gradlew clean build
 
  
with maven-wrapper
+
As usual, alternative test-configuration is possible if needed.
./mvnw clean package
 
  
== Run the Project ==
+
== Download/Clone the example project ==
  
for gradle:
+
With the git command line installed all you need is to clone the example repository:
java -jar build/libs/zk-spring-boot-0.1.0.jar
 
  
for maven
+
    git clone https://github.com/zkoss-demo/zk-spring-boot.git
java -jar target/zk-spring-boot-0.1.0.jar
 
  
After a short startup time you'll see an output like this.
+
Alternatively you can download the example as a [https://github.com/zkoss-demo/zk-spring-boot/archive/master.zip zip-package].
  
... Started ServerConnector@5536379e{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
+
Once cloned/unzipped open a command line in the project folder.
... 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:
+
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].
  
http://localhost:8080/mvvm.zul (small MVVM example showing subnavigation and spring service integration)
+
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.
  
http://localhost:8080/resources.zul (examples of accessing static resources the "springboot way" vs the "zk way")
+
== Build / Run the Project ==
  
http://localhost:8080/richlet/test (sample richlet - zk in pure java)
+
Please follow the instructions in the [https://github.com/zkoss-demo/zk-spring-boot/blob/master/README.md README.md].
  
 
== Import the project into your IDE ==
 
== 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.
+
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 [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.
 
'''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 06:31, 16 August 2018


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



The zk-spring-boot Example

The example project is located on 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 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.

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 -> src/main/java/zk/springboot/config/ZKCEConfig / ZKEEConfig


ZKCEConfig.java and 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 Application class can be done using the annotations @ZKCEApplication or @ZKEEApplication.java:

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

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.)

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:

Application structure

In this 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 in ZKCEConfig.java.

zul files 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 ar:

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).

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

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.

The PageTest 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.

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

Alternatively you can download the example as a zip-package.

Once cloned/unzipped open a command line in the project folder.

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 zk.springboot.Application can be executed directly in your IDE for development and debugging.



Last Update : 2018/08/16

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