From Documentation

Revision as of 08:22, 14 December 2010 by Char (Talk | contribs)
Jump to: navigation, search






Contents

How to Use ZK Maven Repository

This chapter describes how to use the Maven repository hosted by ZK. Here I introduce you a simple example for using ZK maven repository in your maven build environment.

Setup a simple Maven Web application project

Here I will create a simple Web application project using Maven archetype plugin and archetype:generate goal. Refer to the Maven reference book for more information on archetype[1]

mvn archetype:generate -DgroupId=org.zkoss.simpleweb -DartifactId=zk-simple-webapp -DpackageName=org.zkoss.sample -Dversion=1.0-SNAPSHOT

Execute above command on your command line, select archetype #15, and then enter "Y" to confirm and it will generate the create a simple web application project with default maven defined structure for you.

Upon creation of this project navigate to project directory and you can see a default pom.xml file already generated by Maven. It will look something like this

<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.zkoss.simpleweb</groupId>
  <artifactId>zk-simple-webapp</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>zk-simple-webapp</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Add ZK Maven repository to your pom.xml file

By default while resolving project dependencies Maven will only look into Maven central repository [2]. In order to use ZK Maven repository add following <repositories> element into pom.xml under root <project> element.

 <repositories>
    <repository>
      <id>zk repository</id>
      <url>http://mavensync.zkoss.org/maven2</url>
    </repository>
  </repositories>

Note that ZK Maven repository URL is http://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 pom.xml file and Maven can resolve them by automatically connecting to ZK Maven repository Here is how you can declare a dependency for main ZK library and zul library for your project.

    <dependency>
      <groupId>org.zkoss.zk</groupId>
      <artifactId>zk</artifactId>
      <version>5.0.4</version>
    </dependency>
    <dependency>
      <groupId>org.zkoss.zk</groupId>
      <artifactId>zul</artifactId>
      <version>5.0.4</version>
    </dependency>

In order 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 sample pom.xml for a simple Java project that uses the ZK maven repository.

<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/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>org.zkoss.simple</groupId>
	<artifactId>zksample</artifactId>
	<packaging>war</packaging>
	<version>1.0-SNAPSHOT</version>
	<name>zksample</name>
	<properties>
		<zk.version>5.0.4</zk.version>
		<zkel.version>1.1.0</zkel.version>
		<commons-lang.version>2.4</commons-lang.version>
		<bsh.version>2.0b4</bsh.version>
		<commons-fileupload.version>1.2.1</commons-fileupload.version>
		<commons-io.version>1.3.1</commons-io.version>
		<commons-logging.version>1.1.1</commons-logging.version>
		<servlet.version>2.4</servlet.version>
		<jgroovy.version>1.5.6</jgroovy.version>
		<jruby.version>1.1.2</jruby.version>
		<jython.version>2.2.1</jython.version>
		<js.version>1.7R1</js.version>
		<jasperreports.version>3.7.0</jasperreports.version>
		<jfreechart.version>1.0.13</jfreechart.version>
		<filters.version>2.0.235</filters.version>
		<ckez.version>3.3.2_50</ckez.version>
		<timelinez.version>2.3.1_50</timelinez.version>
		<timeplotz.version>1.1_50</timeplotz.version>
		<gmapsz.version>2.0-3</gmapsz.version> <!-- Should 2.5x BUT maven @zkoss not update -->
		</properties>
	<repositories>
		<repository>
			<id>zk repository</id>
			<url>http://mavensync.zkoss.org/maven2</url>
		</repository>
           <!-- If Using ZK EE or ZK PE Respository (not evaluation version), you need to add login info into ~/.m2/settings.xml -->
		<repository>
			<id>ZK PE Evaluation</id>
			<url>http://mavensync.zkoss.org/zk/pe-eval</url>
		</repository>
		<repository>
			<id>ZK EE Evaluation</id> 
			<url>http://mavensync.zkoss.org/zk/ee-eval</url>
		</repository>
	</repositories>
	<dependencies>
		<dependency>
			<groupId>commons-logging</groupId>
			<artifactId>commons-logging</artifactId>
			<version>${commons-logging.version}</version>
		</dependency>
		<dependency>
			<groupId>commons-fileupload</groupId>
			<artifactId>commons-fileupload</artifactId>
			<version>${commons-fileupload.version}</version>
		</dependency>
		<dependency>
			<groupId>commons-io</groupId>
			<artifactId>commons-io</artifactId>
			<version>${commons-io.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zk</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>zul</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zhtml</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkex</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>zkmax</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.common</groupId>
			<artifactId>zcommon</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.common</groupId>
			<artifactId>zweb</artifactId>
			<version>${zk.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zkforge.el</groupId>
			<artifactId>zcommons-el</artifactId>
			<version>${zkel.version}</version>
		</dependency>
		<dependency>
			<groupId>commons-lang</groupId>
			<artifactId>commons-lang</artifactId>
			<version>${commons-lang.version}</version>
		</dependency>
		<dependency>
			<groupId>org.beanshell</groupId>
			<artifactId>bsh</artifactId>
			<version>${bsh.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.codehaus.groovy</groupId>
			<artifactId>groovy-all</artifactId>
			<version>${jgroovy.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.jruby</groupId>
			<artifactId>jruby</artifactId>
			<version>${jruby.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.python</groupId>
			<artifactId>jython</artifactId>
			<version>${jython.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>rhino</groupId>
			<artifactId>js</artifactId>
			<version>${js.version}</version>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>net.sf.jasperreports</groupId>
			<artifactId>jasperreports</artifactId>
			<version>${jasperreports.version}</version>
		</dependency>
		<dependency>
			<groupId>jfree</groupId>
			<artifactId>jfreechart</artifactId>
			<version>${jfreechart.version}</version>
		</dependency>
		<dependency>
			<groupId>com.jhlabs</groupId>
			<artifactId>filters</artifactId>
			<version>${filters.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zkforge</groupId>
			<artifactId>ckez</artifactId>
			<version>${ckez.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zkforge</groupId>
			<artifactId>gmapsz</artifactId>
			<version>${gmapsz.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zkforge</groupId>
			<artifactId>timelinez</artifactId>
			<version>${timelinez.version}</version>
		</dependency>
		<dependency>
			<groupId>org.zkoss.zkforge</groupId>
			<artifactId>timeplotz</artifactId>
			<version>${timeplotz.version}</version>
		</dependency>
	</dependencies>
</project>

How to Choose the Right ZK Maven Repository for a ZK Package

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:

Add to your Maven projects

Choose the edition you want and add to you Super POM

1. CE (Freely avaialable under LGPL)

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

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

PE-eval
 <repositories>
    <repository>
      <id>ZK PE Evaluation</id>
      <url>http://mavensync.zkoss.org/zk/pe-eval</url>
    </repository>
  </repositories>
EE-eval
 <repositories>
    <repository>
      <id>ZK EE Evaluation</id>
      <url>http://mavensync.zkoss.org/zk/ee-eval</url>
    </repository>
  </repositories>

3. PE / EE (premium users only)

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

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>

Summary of JAR files

There're 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
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
zml.jar V
(only ZK 3)
V V ZK XML components for generating XML output

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

Version History

Last Update: 2010/12/14

Version Date Content
     




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