Maven Setup"

From Documentation
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{ZKInstallationGuidePageHeader}}
 
{{ZKInstallationGuidePageHeader}}
  
= How to Use ZK Maven Repository =
+
= How to Use Maven with ZK=
  
 
This chapter describes how to use the Maven repository hosted by ZK. (We assume you have known [https://maven.apache.org/ Maven])
 
This chapter describes how to use the Maven repository hosted by ZK. (We assume you have known [https://maven.apache.org/ Maven])
 
Here introduces you with a simple example of using ZK maven repository in your maven build environment.
 
Here introduces you with a simple example of using ZK maven repository in your maven build environment.
  
== Add ZK Maven repository to your pom.xml file ==
+
=Choosing ZK Edition=
By default, while resolving project dependencies Maven will only look into Maven central repository [http://repo1.maven.org/maven2]. In order to use ZK Maven repository add the following <repositories> element into pom.xml under the root <project> element.
 
  
<source lang="xml">
+
ZK has 3 editions:  
<repositories>
 
    <repository>
 
      <id>ZK CE</id>
 
      <name>ZK CE Repository</name>
 
      <url>https://mavensync.zkoss.org/maven2</url>
 
    </repository>
 
  </repositories>
 
</source>
 
 
 
Note that ZK Maven repository URL is [https://mavensync.zkoss.org/maven2 https://mavensync.zkoss.org/maven2].
 
 
 
== Adding ZK library dependencies ==
 
 
 
Depending upon your project requirements your project might depend on various ZK libraries. You can declare these dependencies in the pom.xml file and Maven can resolve them by automatically connecting to [http://mavensync.zkoss.org/maven2 ZK Maven repository] Here is how you can declare a dependency for the main ZK library and zul library for your project.
 
 
 
<source lang="xml">
 
<dependency>
 
<groupId>org.zkoss.zk</groupId>
 
<artifactId>zkbind</artifactId>
 
<version>8.5.0</version>
 
</dependency>
 
<dependency>
 
<groupId>org.zkoss.zk</groupId>
 
<artifactId>zul</artifactId>
 
<version>8.5.0</version>
 
</dependency>
 
<dependency>
 
<groupId>org.zkoss.zk</groupId>
 
<artifactId>zkplus</artifactId>
 
<version>8.5.0</version>
 
</dependency>
 
<dependency>
 
<groupId>org.zkoss.zk</groupId>
 
<artifactId>zhtml</artifactId>
 
<version>8.5.0</version>
 
</dependency>
 
</source>
 
 
 
For Maven to successfully resolve these dependencies '''groupid''' and '''artifactid''' must match with those published on ZK Maven repository as they constitute what is known as Maven repository coordinates. For a complete list of all ZK library groupid and artifactid combinations please take a look at a [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Repository_without_IDE#Sample_of_pom.xml|sample pom.xml]] file that lists dependencies for all publically available ZK libraries on ZK Maven repository.
 
 
 
=Sample of pom.xml=
 
Here is a sample pom.xml for a simple Java project that uses the ZK maven repository.
 
 
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" 
 
xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>zk.app</groupId>
 
  <artifactId>MyZKMavenApp</artifactId>
 
  <version>0.0.1-SNAPSHOT</version>
 
  <repositories>
 
    <repository>
 
      <id>ZK CE</id>
 
      <name>ZK CE Repository</name>
 
      <url>https://mavensync.zkoss.org/maven2</url>
 
    </repository>
 
    <repository>
 
      <id>ZK EVAL</id>
 
      <name>ZK Evaluation Repository</name>
 
      <url>https://mavensync.zkoss.org/eval</url>
 
    </repository>
 
  </repositories>
 
  <dependencies>
 
....
 
  </dependencies>
 
</project>
 
</source>
 
 
 
 
 
== Required Dependencies ==
 
The following are required dependencies you need to include one of them in your pom.xml according to which ZK edition you use.
 
 
 
===ZK CE===
 
<source lang="xml">
 
<dependencies>
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zul</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
</dependencies>
 
</source>
 
 
 
===ZK PE===
 
<source lang="xml">
 
<dependencies>
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zkex</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
</dependencies>
 
</source>
 
 
 
===ZK EE===
 
<source lang="xml">
 
<dependencies>
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zkmax</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
</dependencies>
 
</source>
 
 
 
== Optional Dependencies ==
 
  
The following dependencies are optional and available for all editions. You can include them according to your needs.
+
* '''CE''' (compact edition). Suits for personal use.
 +
* '''PE''' (professional edition)
 +
* '''EE''' (enterprise edition)
  
<source lang='xml'>
+
Please check [http://www.zkoss.org/product/edition.dsp the description about ZK Editions] to know the differences among them and find the proper edition for you.
<dependencies>
 
<!-- It's available since ZK 8. If you want to use shadow component/template injection, include this -->
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zuti</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
<!-- If you want to use data binding, include this -->
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zkbind</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
<!-- If you want to use zk xhtml component set, include this -->
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zhtml</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
<!-- If you want to use third party framework e.g. hibernate, spring, you can include this -->
 
    <dependency>
 
      <groupId>org.zkoss.zk</groupId>
 
      <artifactId>zkplus</artifactId>
 
      <version>${zk.version}</version>
 
    </dependency>
 
</dependencies>
 
</source>
 
 
 
== Check Available ZK Version ==
 
Please visit each edition's corresponding ZK Maven repository with a browser to check the available ZK versions.
 
 
 
=Choose Right Maven Repository=
 
 
 
ZK has three editions: '''CE''', '''PE''' and '''EE'''. They are hosted in different Maven repository.
 
I will guide you through how to choose the right edition and set up the right ZK Maven repository.
 
 
 
==Steps for choosing the right edition==
 
Here are the steps for choosing the right edition of ZK:
 
 
 
Decide which edition to use:
 
*There are three editions of ZK: '''CE''', '''PE''' and '''EE'''
 
*For more information, please refer to [http://www.zkoss.org/product/edition.dsp description about ZK Editions] and the following section that summarizes the jar files.
 
 
 
 
 
==Summary of JAR files==
 
 
 
There're something you need to know about ZK's edition and package(s).
 
{| class='wikitable'
 
|-style="text-align:center;"
 
!scope="col"|
 
! width="100px"|CE
 
!width="100px" |PE
 
!width="100px" |EE
 
!scope="col"|Description
 
|- style="text-align:center;"
 
|zk.jar
 
|V
 
|V
 
|V
 
| ZK core functions, such as ZK Loader and Update Engine.
 
|-style="text-align:center;"
 
|zul.jar
 
|V
 
|V
 
|V
 
| ZK XUL components (<nowiki>http://www.zkoss.org/2005/zul</nowiki>)
 
|-style="text-align:center;"
 
|zhtml.jar
 
|V
 
|V
 
|V
 
| ZK XHTML components (<nowiki>http://www.w3c.org/1999/xhtml</nowiki>)
 
|-style="text-align:center;"
 
|zcommon.jar
 
|V
 
|V
 
|V
 
|The common library that ZK depends on
 
|-style="text-align:center;"
 
|zcommons-el.jar
 
|V
 
|V
 
|V
 
|ZK EL expressions (renamed as zel.jar since 6.0)
 
 
 
|-style="text-align:center;"
 
|zel.jar
 
|V
 
|V
 
|V
 
|ZK EL expressions (since 6.0)
 
 
 
|-style="text-align:center;"
 
|zkbind.jar
 
|V
 
|V
 
|V
 
|data binding, required when developing with MVVM
 
 
 
|-style="text-align:center;"
 
|zweb.jar
 
|V
 
|V
 
|V
 
|The Web library that ZK depends on
 
|-style="text-align:center;"
 
|zkplus.jar
 
|V
 
|V
 
|V
 
|ZK extra utilities integrated easily with other frameworks.
 
|-style="text-align:center;"
 
|zkex.jar
 
|
 
|V
 
|V
 
|ZK additional components and features for PE
 
 
 
|-style="text-align:center;"
 
|zkmax.jar
 
|
 
|
 
|V
 
|ZK additional components and features for EE
 
 
 
|-style="text-align:center;"
 
|zuti.jar
 
|
 
|
 
|V
 
| shadow components for EE
 
 
 
|-style="text-align:center;"
 
|zml.jar
 
|V <br />(only ZK 3)
 
|V
 
|V
 
|ZK XML components for generating XML output
 
|}
 
This will be helpful when you modify your dependencies of projects.
 
  
 
=Add ZK Maven Repository to Your Projects=
 
=Add ZK Maven Repository to Your Projects=
  
According to which ZK edition you use and add the corresponding repository to your project's pom.xml.
+
According to which ZK edition you use, add the corresponding repository to your project's pom.xml.
  
 
== CE (Freely avaialable under LGPL)==
 
== CE (Freely avaialable under LGPL)==
Line 279: Line 33:
  
 
== PE-eval / EE-eval (60-days free evaluation)==
 
== PE-eval / EE-eval (60-days free evaluation)==
*https://mavensync.zkoss.org/eval/
+
The evaluation version has the exactly same features as the official (non-evaluation) ones. You use it to develop a POC and try ZK features before you adopt the official ones. This can eliminate the potential technical problems in advance.
 +
 
 +
 
 
<source lang="xml">
 
<source lang="xml">
 
  <repositories>
 
  <repositories>
Line 288: Line 44:
 
   </repositories>
 
   </repositories>
 
</source>
 
</source>
*'''Note:''' Version number appending with ''-Eval'' has released since Jul. 18 2014. If you use it, please specify version to ''*-Eval'' for all of ZK dependencies. For example:
+
*'''Note:''' Version number appending with ''-Eval'' has released since Jul. 18 2014. If you use it, please specify the version to ''*-Eval'' for all of ZK dependencies. For example:
 +
 
 
<source lang="xml">
 
<source lang="xml">
 
<dependency>
 
<dependency>
Line 381: Line 138:
 
<version>0.0.1-SNAPSHOT</version>
 
<version>0.0.1-SNAPSHOT</version>
 
<properties>
 
<properties>
<!-- please check available version in the repository and specify it -->
+
<!-- please check the available version in the repository and specify the latest stable or according to your needs -->
<zk.version>9.1.0</zk.version>
+
<zk.version>10.0.0</zk.version>
<zkspring.version>3.2.0</zkspring.version>
+
<zkspring.version>4.0.2</zkspring.version>
<zats.version>2.0.0</zats.version>
+
<zats.version>10.0.0</zats.version>
 
<zkjsp.version>2.6.0</zkjsp.version>
 
<zkjsp.version>2.6.0</zkjsp.version>
<zkcalendar.version>2.1.5</zkcalendar.version>
+
<zkcalendar.version>3.1.2</zkcalendar.version>
<zkgmap.version>3.0.4</zkgmap.version>
+
<zkgmap.version>4.0.3</zkgmap.version>
 
</properties>
 
</properties>
 
<packaging>war</packaging>
 
<packaging>war</packaging>
Line 542: Line 299:
 
</source>
 
</source>
  
= Create a Maven Project with a Command Line=
 
Before starting, you need to [https://maven.apache.org/download.cgi install maven] and [https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html set up] first.
 
  
*Go to your new project folder, then run the following command:
+
= Adding ZK library dependencies =
<source lang='text'>
+
 
mvn archetype:generate -DarchetypeCatalog=https://mavensync.zkoss.org/maven2/
+
Depending upon your project requirements your project might depend on different ZK edition. You can declare these dependencies in the pom.xml file, and Maven can resolve them by automatically connecting to [http://mavensync.zkoss.org/maven2 ZK Maven repository]. Here is how you can declare a dependency for the main ZK library and zul library for your project.
 +
 
 +
== EE ==
 +
<syntaxhighlight lang="xml">
 +
<dependency>
 +
<groupId>org.zkoss.zk</groupId>
 +
<artifactId>zkmax</artifactId>
 +
<version>${zk.version}</version>
 +
</dependency>
 +
</syntaxhighlight>
 +
== PE ==
 +
<syntaxhighlight lang="xml">
 +
<dependency>
 +
<groupId>org.zkoss.zk</groupId>
 +
<artifactId>zkex</artifactId>
 +
<version>${zk.version}</version>
 +
</dependency>
 +
</syntaxhighlight>
 +
== CE ==
 +
<syntaxhighlight lang="xml">
 +
<dependency>
 +
<groupId>org.zkoss.zk</groupId>
 +
<artifactId>zul</artifactId>
 +
<version>${zk.version}</version>
 +
</dependency>
 +
</syntaxhighlight>
 +
 
 +
== Optional ==
 +
<syntaxhighlight lang='xml'>
 +
<dependency>
 +
<groupId>org.zkoss.zk</groupId>
 +
<artifactId>zkplus</artifactId>
 +
<version>${zk.version}</version>
 +
</dependency>
 +
<dependency>
 +
<groupId>org.zkoss.zk</groupId>
 +
<artifactId>zhtml</artifactId>
 +
<version>${zk.version}</version>
 +
</dependency>
 +
</syntaxhighlight>
 +
 
 +
For Maven to successfully resolve these dependencies '''groupid''' and '''artifactid''' must match with those published on ZK Maven repository as they constitute what is known as Maven repository coordinates. For a complete list of all ZK library groupid and artifactid combinations please take a look at a [[ZK_Installation_Guide/Setting_up_IDE/Maven/Use_ZK_Maven_Repository_without_IDE#Sample_of_pom.xml|sample pom.xml]] file that lists dependencies for all publically available ZK libraries on ZK Maven repository.
 +
 
 +
=Sample of pom.xml=
 +
Here is a sample pom.xml for a simple Java project that uses the ZK maven repository.
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" 
 +
xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
  <modelVersion>4.0.0</modelVersion>
 +
  <groupId>zk.app</groupId>
 +
  <artifactId>MyZKMavenApp</artifactId>
 +
  <version>0.0.1-SNAPSHOT</version>
 +
  <repositories>
 +
    <repository>
 +
      <id>ZK CE</id>
 +
      <name>ZK CE Repository</name>
 +
      <url>https://mavensync.zkoss.org/maven2</url>
 +
    </repository>
 +
    <repository>
 +
      <id>ZK EVAL</id>
 +
      <name>ZK Evaluation Repository</name>
 +
      <url>https://mavensync.zkoss.org/eval</url>
 +
    </repository>
 +
  </repositories>
 +
  <dependencies>
 +
....
 +
  </dependencies>
 +
</project>
 
</source>
 
</source>
Then just answer the questions the plugin asks you to create a project.
 
* The plugin will first ask you to choose the archetype from the zk catalog, please just enter the number of the archetype
 
* It will then ask users to enter the values for ''groupId'', the ''artifactId'' and the ''version'' of the project to create the base package for the sources.
 
* It will then ask for confirmation of the configuration and perform the creation of the project.
 
* In the following example, webapp archetype (number 3) is selected, and ''groupId'' is set to '''com.foo''', ''artifactId'' to '''mywebapp''', ''version'' to '''0.8.0''' and ''package'' to '''com.foo'''.
 
  
'''NOTE''': in case your maven installation uses the latest maven-archetype-plugin version 3.0.1 you'll have to use the following command (using 2.4 as a fallback - [https://issues.apache.org/jira/browse/ARCHETYPE-519 ARCHETYPE-519]):
 
  
  $ mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://mavensync.zkoss.org/maven2/
+
== Required Dependencies ==
 +
The following are required dependencies you need to include in your pom.xml according to the ZK edition you use.  
  
 +
===ZK CE===
 +
<source lang="xml">
 +
<dependencies>
 +
    <dependency>
 +
      <groupId>org.zkoss.zk</groupId>
 +
      <artifactId>zul</artifactId>
 +
      <version>${zk.version}</version>
 +
    </dependency>
 +
</dependencies>
 +
</source>
  
  $ mvn archetype:generate -DarchetypeCatalog=https://mavensync.zkoss.org/maven2/
+
===ZK PE===
  [INFO] Scanning for projects...
+
<source lang="xml">
  [INFO] Searching repository for plugin with prefix: 'archetype'.
+
<dependencies>
  [INFO] ------------------------------------------------------------------------
+
    <dependency>
  [INFO] Building Maven Default Project
+
      <groupId>org.zkoss.zk</groupId>
  [INFO]    task-segment: [archetype:generate] (aggregator-style)
+
      <artifactId>zkex</artifactId>
  [INFO] ------------------------------------------------------------------------
+
      <version>${zk.version}</version>
  [INFO] Preparing archetype:generate
+
    </dependency>
  [INFO] No goals needed for project - skipping
+
</dependencies>
  [INFO] [archetype:generate {execution: default-cli}]
+
</source>
  [INFO] Generating project in Interactive mode
 
  [INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.
 
  archetypes:maven-archetype-quickstart:1.0)
 
  Choose archetype:
 
  1: https://mavensync.zkoss.org/maven2/ -> zk-archetype-component (An archetype
 
  that generates a starter ZK component project)
 
  2: https://mavensync.zkoss.org/maven2/ -> zk-archetype-extension (An archetype
 
  that generates a starter ZK extension project)
 
  3: https://mavensync.zkoss.org/maven2/ -> zk-archetype-webapp (An archetype that
 
  generates a starter ZK CE webapp project)
 
  4: https://mavensync.zkoss.org/maven2/ -> zk-ee-eval-archetype-webapp (An
 
  archetype that generates a starter ZK EE-eval webapp project)
 
  Choose a number: : 3
 
  Define value for property 'groupId': : com.foo
 
  Define value for property 'artifactId': : mywebapp
 
  Define value for property 'version': 1.0-SNAPSHOT: 0.8.0
 
  Define value for property 'package': com.foo:
 
  [INFO] Using property: zk-version-since = 6.0.1
 
  Confirm properties configuration:
 
  groupId: com.foo
 
  artifactId: mywebapp
 
  version: 0.8.0
 
  package: com.foo
 
  zk-version-since: 6.0.1
 
  Y:
 
  [INFO] ------------------------------------------------------------------------
 
  [INFO] BUILD SUCCESSFUL
 
  [INFO] ------------------------------------------------------------------------
 
  [INFO] Total time: 29 seconds
 
  [INFO] Finished at: Fri Jun 22 16:55:27 CST 2012
 
  [INFO] Final Memory: 13M/150M
 
  [INFO] ------------------------------------------------------------------------
 
  
== Run the Project ==
+
===ZK EE===
The project created by archetypes above should have a maven jetty plugin configured, you can just run the project with the command below:
+
<source lang="xml">
 +
<dependencies>
 +
    <dependency>
 +
      <groupId>org.zkoss.zk</groupId>
 +
      <artifactId>zkmax</artifactId>
 +
      <version>${zk.version}</version>
 +
    </dependency>
 +
</dependencies>
 +
</source>
 +
 
 +
== Optional Dependencies ==
 +
 
 +
The following dependencies are optional. If it has no label, it means it's available for all editions. If it has a "EE" and "Since 8.0.0" label, it means it's only available for the EE edition on or after version 8.0. You can include them only if you need to use these features.
 +
 
 +
<source lang='xml'>
 +
<!-- To use data binding, include this -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>zkbind</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
<!-- To use zk xhtml component set, include this -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>zhtml</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
<!-- To use third-party framework-related utilities e.g. hibernate, spring, you can include this -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>zkplus</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
</source>
 +
 
 +
 
 +
 
 +
{{ZK_EE}}
 +
{{versionSince| 8.0.0}}
 +
 
 +
<source lang='xml'>
 +
<!-- It's available since ZK 8. To use shadow component/template injection, include this -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>zuti</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
</source>
 +
 
 +
 
 +
{{ZK_EE}}
 +
{{versionSince|9.5.0}}
 +
 
 +
<source lang='xml'>
 +
<!-- For WCAG compliance, include this -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>za11y</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
</source>
 +
 
 +
 
 +
{{ZK_EE}}
 +
{{versionSince| 10.0.0}}
 +
 
 +
<source lang='xml>
 +
<!-- To use client MVVM, include this dependency. Available since ZK 10 -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>client-bind</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
<!-- To use stateless components, include this dependency. Available since ZK 10 -->
 +
<dependency>
 +
    <groupId>org.zkoss.zk</groupId>
 +
    <artifactId>stateless</artifactId>
 +
    <version>${zk.version}</version>
 +
</dependency>
 +
</source>
 +
 
 +
== Check Available ZK Version ==
 +
Please visit each edition's corresponding ZK Maven repository with a browser to check the available ZK versions. As of April 2024, the latest version is <code>10.0.0</code>.
 +
 
 +
==Summary of JAR files==
  
mvn jetty:run
+
There's something you need to know about ZK's edition and package(s).
 +
{| class='wikitable'
 +
|- style="text-align:left;"
 +
!scope="col"|
 +
! style="text-align:center; width:100px;" |CE
 +
! style="text-align:center; width:100px;" |PE
 +
! style="text-align:center; width:100px;" |EE
 +
! scope="col" style="text-align:left;" |Description
 +
|- style="text-align:left;"
 +
|zk.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK core functions, such as ZK Loader and Update Engine.
 +
|- style="text-align:left;"
 +
|zul.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK XUL components (<nowiki>http://www.zkoss.org/2005/zul</nowiki>)
 +
|- style="text-align:left;"
 +
|zhtml.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK XHTML components (<nowiki>http://www.w3c.org/1999/xhtml</nowiki>)
 +
|- style="text-align:left;"
 +
|zcommon.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| The common library that ZK depends on
 +
|- style="text-align:left;"
 +
|zcommons-el.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK EL expressions (renamed as zel.jar since 6.0)
 +
|- style="text-align:left;"
 +
|zel.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK EL expressions (since 6.0)
 +
|- style="text-align:left;"
 +
|zkbind.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| data binding, required when developing with MVVM
 +
|- style="text-align:left;"
 +
|zweb.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| The Web library that ZK depends on
 +
|- style="text-align:left;"
 +
|zkplus.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK extra utilities integrated easily with other frameworks.
 +
|- style="text-align:left;"
 +
|zkex.jar
 +
|
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| ZK additional components and features for PE
 +
|- style="text-align:left;"
 +
|zkmax.jar
 +
|
 +
|
 +
| style="text-align:center;" |V
 +
| ZK additional components and features for EE
 +
|- style="text-align:left;"
 +
|zuti.jar
 +
|
 +
|
 +
| style="text-align:center;" |V
 +
| shadow components for EE
 +
|- style="text-align:left;"
 +
|client-bind.jar
 +
|
 +
|
 +
| style="text-align:center;" |V
 +
| Client MVVM for EE
 +
|- style="text-align:left;"
 +
|stateless.jar
 +
|
 +
|
 +
| style="text-align:center;" |V
 +
| core of stateless components for EE
 +
|- style="text-align:left;"
 +
|stateless-immutable.jar
 +
|
 +
|
 +
| style="text-align:center;" |V
 +
| immutables of stateless components for EE
 +
|- style="text-align:left;"
 +
|zml.jar
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| style="text-align:center;" |V
 +
| (only ZK 3) ZK XML components for generating XML output
 +
|}
 +
 
 +
This will be helpful when you modify your dependencies of projects.
  
 
= BOM =
 
= BOM =

Latest revision as of 08:07, 6 June 2024




How to Use Maven with ZK

This chapter describes how to use the Maven repository hosted by ZK. (We assume you have known Maven) Here introduces you with a simple example of using ZK maven repository in your maven build environment.

Choosing ZK Edition

ZK has 3 editions:

  • CE (compact edition). Suits for personal use.
  • PE (professional edition)
  • EE (enterprise edition)

Please check the description about ZK Editions to know the differences among them and find the proper edition for you.

Add ZK Maven Repository to Your Projects

According to which ZK edition you use, add the corresponding repository to your project's pom.xml.

CE (Freely avaialable under LGPL)

 <repositories>
    <repository>
      <id>ZK CE</id>
      <url>https://mavensync.zkoss.org/maven2</url>
    </repository>
  </repositories>

PE-eval / EE-eval (60-days free evaluation)

The evaluation version has the exactly same features as the official (non-evaluation) ones. You use it to develop a POC and try ZK features before you adopt the official ones. This can eliminate the potential technical problems in advance.


 <repositories>
    <repository>
      <id>ZK PE/EE Evaluation</id>
      <url>https://mavensync.zkoss.org/eval/</url>
    </repository>
  </repositories>
  • Note: Version number appending with -Eval has released since Jul. 18 2014. If you use it, please specify the version to *-Eval for all of ZK dependencies. For example:
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>zk</artifactId>
    <version>8.5.0-Eval</version>
</dependency>

PE / EE (premium users only)

If you are our customer or ZOL licensed user you can contact info@zkoss.org to apply for a premium maven account to use ZK PE/EE (or any other licensed ZK product) maven repository.

 <repositories>
    <repository>
      <id>ZK EE</id>
      <url>https://maven.zkoss.org/repo/zk/ee</url>
    </repository>
  </repositories>

Login authentication

Licensed Professional and Enterprise customers will be given a set of user names and password upon your request. According to the official doc of Apache Maven, users can create global settings for maven.

  • Location (if not-existed, you can create it manually)
    • The Maven install: $M2_HOME/conf/settings.xml
    • A user's install: ${user.home}/.m2/settings.xml
  • Servers Element
  • If you add ZK PE or ZK EE as your repository, you need to add login authentication like following example
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
 		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 		xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
 		http://maven.apache.org/xsd/settings-1.0.0.xsd">
	<servers>
		<server>
			<id>ZK EE</id><!-- Same as your repository name -->
			<!-- Your premium user name and password -->
			<username>ryanwu</username> 
			<password>2k055ecret</password> 
		</server>
	</servers>
</settings>

Sample of pom.xml for licensed Professional Package

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>zkpe</groupId>
	<artifactId>sample</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<properties>
		<!-- please check available version in the repository and specify it -->
		<zk.version>9.1.0</zk.version>
	</properties>
	<packaging>war</packaging>
	<name>The sample Project</name>
	<description>The sample Project</description>
	<repositories>
		<repository>
			<id>ZK CE</id>
			<name>ZK CE Repository</name>
			<url>https://mavensync.zkoss.org/maven2</url>
		</repository>
		<repository>
		    <id>ZK EE</id>
		    <url>https://maven.zkoss.org/repo/zk/ee</url>
		</repository>
	</repositories>
	<dependencies>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkex</artifactId>
			<version>${zk.version}</version>
		</dependency>
	</dependencies>
</project>

Sample of pom.xml for licensed Enterprise Package

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>zkee</groupId>
	<artifactId>sample</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<properties>
		<!-- please check the available version in the repository and specify the latest stable or according to your needs -->
		<zk.version>10.0.0</zk.version>
		<zkspring.version>4.0.2</zkspring.version>
		<zats.version>10.0.0</zats.version>
		<zkjsp.version>2.6.0</zkjsp.version>
		<zkcalendar.version>3.1.2</zkcalendar.version>
		<zkgmap.version>4.0.3</zkgmap.version>
	</properties>
	<packaging>war</packaging>
	<name>The sample Project</name>
	<description>The sample Project</description>
	<repositories>
		<repository>
			<id>ZK CE</id>
			<name>ZK CE Repository</name>
			<url>https://mavensync.zkoss.org/maven2</url>
		</repository>
		<repository>
			<id>ZK EE</id>
			<url>https://maven.zkoss.org/repo/zk/ee</url>
		</repository>
	</repositories>
	<dependencies>
		<!-- ZK EE -->
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkmax</artifactId>
			<version>${zk.version}</version>
		</dependency>

		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkplus</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zhtml</artifactId>
			<version>${zk.version}</version>
		</dependency>
	        <!-- available since ZK 8 -->
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zuti</artifactId> 
			<version>${zk.version}</version>
		</dependency>


		<!-- ZK Spring -->
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkspring-core</artifactId>
			<version>${zkspring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkspring-security</artifactId>
			<version>${zkspring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkspring-webflow</artifactId>
			<version>${zkspring.version}</version>
		</dependency>

		<!-- ZK JSP -->
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zuljsp</artifactId>
			<version>${zkjsp.version}</version>
		</dependency>

		<!-- ZK Calendar -->
		<dependency>
			<groupId>org.zkoss.calendar</groupId>
			<artifactId>calendar</artifactId>
			<version>${zkcalendar.version}</version>
		</dependency>

		<!-- ZK Google Maps -->
		<dependency>
			<groupId>org.zkoss.zkforge</groupId>
			<artifactId>gmapsz</artifactId>
			<version>${zkgmap.version}</version>
		</dependency>

		<!-- ZK additional Theme/s more themes -> https://maven.zkoss.org/repo/zk/ee/org/zkoss/theme/ -->
		<dependency>
			<groupId>org.zkoss.theme</groupId>
			<artifactId>breeze</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.theme</groupId>
			<artifactId>deepsea</artifactId>
			<version>${zk.version}</version>
		</dependency>
 
		<!-- or add the whole theme pack
		<dependency>
			<groupId>org.zkoss.theme</groupId>
			<artifactId>theme-pack</artifactId>
			<version>${zk.version}</version>
		</dependency>
		 -->
		<!-- ZATS Mimic -->
		<dependency>
			<groupId>org.zkoss.zats</groupId>
			<artifactId>zats-mimic-ext7</artifactId>
			<version>${zats.version}</version>
			<scope>test</scope>
		</dependency>
	</dependencies>
</project>

Trouble Shooting

If you have problems switching from the evaluation repository to the licensed one, please check the followings:

Purge local repository evaluation cache

1. Add purge-local-repository plugin in pom.xml

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-dependency-plugin</artifactId>
				<version>2.6</version>
				<executions>
					<execution>
						<id>purge-local-dependencies</id>
						<phase>clean</phase>
						<goals>
							<goal>purge-local-repository</goal>
						</goals>
						<configuration>
							<manualIncludes>
								<manualInclude>org.zkoss.zk:zkex</manualInclude>
								<manualInclude>org.zkoss.zk:zkmax</manualInclude>
							</manualIncludes>
						</configuration>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
  • line 16: ZK PE
  • line 17: ZK EE


2. Invoke maven clean to delete local zkex & zkmax repository

mvn clean


Adding ZK library dependencies

Depending upon your project requirements your project might depend on different ZK edition. You can declare these dependencies in the pom.xml file, and Maven can resolve them by automatically connecting to ZK Maven repository. Here is how you can declare a dependency for the main ZK library and zul library for your project.

EE

<dependency>
	<groupId>org.zkoss.zk</groupId>
	<artifactId>zkmax</artifactId>
	<version>${zk.version}</version>
</dependency>

PE

<dependency>
	<groupId>org.zkoss.zk</groupId>
	<artifactId>zkex</artifactId>
	<version>${zk.version}</version>
</dependency>

CE

<dependency>
	<groupId>org.zkoss.zk</groupId>
	<artifactId>zul</artifactId>
	<version>${zk.version}</version>
</dependency>

Optional

<dependency>
	<groupId>org.zkoss.zk</groupId>
	<artifactId>zkplus</artifactId>
	<version>${zk.version}</version>
</dependency>
<dependency>
	<groupId>org.zkoss.zk</groupId>
	<artifactId>zhtml</artifactId>
	<version>${zk.version}</version>
</dependency>

For Maven to successfully resolve these dependencies groupid and artifactid must match with those published on ZK Maven repository as they constitute what is known as Maven repository coordinates. For a complete list of all ZK library groupid and artifactid combinations please take a look at a sample pom.xml file that lists dependencies for all publically available ZK libraries on ZK Maven repository.

Sample of pom.xml

Here is a sample pom.xml for a simple Java project that uses the ZK maven repository.

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"   
xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>zk.app</groupId>
  <artifactId>MyZKMavenApp</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <repositories>
    <repository>
      <id>ZK CE</id>
      <name>ZK CE Repository</name>
      <url>https://mavensync.zkoss.org/maven2</url>
    </repository>
    <repository>
      <id>ZK EVAL</id>
      <name>ZK Evaluation Repository</name>
      <url>https://mavensync.zkoss.org/eval</url>
    </repository>
  </repositories>
  <dependencies>
....
  </dependencies>
</project>


Required Dependencies

The following are required dependencies you need to include in your pom.xml according to the ZK edition you use.

ZK CE

<dependencies>
    <dependency>
      <groupId>org.zkoss.zk</groupId>
      <artifactId>zul</artifactId>
      <version>${zk.version}</version>
    </dependency>
</dependencies>

ZK PE

<dependencies>
    <dependency>
      <groupId>org.zkoss.zk</groupId>
      <artifactId>zkex</artifactId>
      <version>${zk.version}</version>
    </dependency>
</dependencies>

ZK EE

<dependencies>
    <dependency>
      <groupId>org.zkoss.zk</groupId>
      <artifactId>zkmax</artifactId>
      <version>${zk.version}</version>
    </dependency>
</dependencies>

Optional Dependencies

The following dependencies are optional. If it has no label, it means it's available for all editions. If it has a "EE" and "Since 8.0.0" label, it means it's only available for the EE edition on or after version 8.0. You can include them only if you need to use these features.

<!-- To use data binding, include this -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>zkbind</artifactId>
    <version>${zk.version}</version>
</dependency>
<!-- To use zk xhtml component set, include this -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>zhtml</artifactId>
    <version>${zk.version}</version>
</dependency>
<!-- To use third-party framework-related utilities e.g. hibernate, spring, you can include this -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>zkplus</artifactId>
    <version>${zk.version}</version>
</dependency>


  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 8.0.0

<!-- It's available since ZK 8. To use shadow component/template injection, include this -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>zuti</artifactId>
    <version>${zk.version}</version>
</dependency>


  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 9.5.0

<!-- For WCAG compliance, include this -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>za11y</artifactId>
    <version>${zk.version}</version>
</dependency>


  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 10.0.0

<!-- To use client MVVM, include this dependency. Available since ZK 10 -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>client-bind</artifactId>
    <version>${zk.version}</version>
</dependency>
<!-- To use stateless components, include this dependency. Available since ZK 10 -->
<dependency>
    <groupId>org.zkoss.zk</groupId>
    <artifactId>stateless</artifactId>
    <version>${zk.version}</version>
</dependency>

Check Available ZK Version

Please visit each edition's corresponding ZK Maven repository with a browser to check the available ZK versions. As of April 2024, the latest version is 10.0.0.

Summary of JAR files

There's something you need to know about ZK's edition and package(s).

CE PE EE Description
zk.jar V V V ZK core functions, such as ZK Loader and Update Engine.
zul.jar V V V ZK XUL components (http://www.zkoss.org/2005/zul)
zhtml.jar V V V ZK XHTML components (http://www.w3c.org/1999/xhtml)
zcommon.jar V V V The common library that ZK depends on
zcommons-el.jar V V V ZK EL expressions (renamed as zel.jar since 6.0)
zel.jar V V V ZK EL expressions (since 6.0)
zkbind.jar V V V data binding, required when developing with MVVM
zweb.jar V V V The Web library that ZK depends on
zkplus.jar V V V ZK extra utilities integrated easily with other frameworks.
zkex.jar V V ZK additional components and features for PE
zkmax.jar V ZK additional components and features for EE
zuti.jar V shadow components for EE
client-bind.jar V Client MVVM for EE
stateless.jar V core of stateless components for EE
stateless-immutable.jar V immutables of stateless components for EE
zml.jar V V V (only ZK 3) ZK XML components for generating XML output

This will be helpful when you modify your dependencies of projects.

BOM

ZK provides a "bill of materials" (BOM) which can be used by your projects simplify a pom.xml. You can use it as a parent POM or import it like:

	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.zkoss.zk</groupId>
				<artifactId>zk-bom</artifactId>
				<version>9.0.1-Eval</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

For a complete example, you can reference pom.xml of this project. You can also read a spring boot document to understand BOM usage.

Version History

Last Update : 2024/06/06


Version Date Content
N/A July 2014 Self-signed certificate related section removed as EE maven repository is certified since Feb. 2014



Last Update : 2024/06/06

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