ZK 6.5.0 Installation Guide

5/28/2018 ZK 6.5.0 Installation Guide

1/115

PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information.

PDF generated at: Thu, 13 Sep 2012 11:30:10 CST

ZK Installation GuideFor ZK 6.5.0

5/28/2018 ZK 6.5.0 Installation Guide

2/115

Contents

Articles

ZK Installation Guide 1

Before You Start 1

New to Java 1

New to Java Servlet 2

Quick Start 3

Create and Run Your First ZK Application with Eclipse and ZK Studio 3

Create and Run Your First ZK Application with Eclipse and Maven 8

Create and Run Your First ZK Application with NetBeans and REM 17

Create and Run Your First ZK Application Manually 21

ZK Background 23

Sample of web.xml for Servlet 3.0 23

Sample of web.xml for Servlet 2.4 24

Sample of web.xml for Servlet 2.3 26

The Content of ZK Binary Distribution 27

Setting up Servers 29

Tomcat 30

JBoss 31

JBoss Cluster 32

WebSphere 33

WebSphere Portal 37

Oracle Server 40

WebLogic 41

WebLogic Portal 42

WebLogic Cluster 47

Google App Engine 48 Heroku 52

Red Hat OpenShift Express 57

Liferay 60

Pluto 84

Jetty 87

Resin 87

Setting up OSGi 88

EclipseRT Web Starter Kits 88

Setting up OS 93

5/28/2018 ZK 6.5.0 Installation Guide

3/115

Linux 93

IOS 94

Setting up IDE 95

Eclipse with ZK Studio 95

Eclipse without ZK Studio 96

Maven 98

Setting up Maven on Eclipse 99

Resolving ZK Framework Artifacts via Maven 101

XML Editor 108

References

Article Sources and Contributors 109

Image Sources, Licenses and Contributors 111

5/28/2018 ZK 6.5.0 Installation Guide

4/115

ZK Installation Guide 1

ZK Installation Guide

Documentation:Books/ZK_Installation_Guide http:/ / books. zkoss. org/ wiki/

ZK_Installation_Guide

Before You Start

Before developing a Web application in Java, you have to install Java Development Kit (JDK) and a Servlet

container. Here we will guide you through the installation of JDK and the content of ZK binary distribution.

New to Java

You don't need to know Java to use ZK, since all rich user interfaces can be implemented in a HTML-like markup

language called ZUML. However, to complete a Web application, you or your teammates need to write some Java

code to glue UI and services together. It requires some Java knowledge.

If you haven't installed the following applications on your computer, please download and install them first.

Java SE Development Kit (JDK)

JDK is a software development for writing application in Java.

Note : we suggest you install this first even some web server already contains one

Web Server

A Web servlet is used to host the Web application you developed

ZK FrameworkZK is an Ajax framework simplifying the development of Web applications

Java Tutorials

Here are some good Java tutorials.

Java URLs

Language Basic[1]

[1]

Class and Object[2]

[2]

[3][3]

[4][4]

5/28/2018 ZK 6.5.0 Installation Guide

5/115

New to Java 2

Install Java SE Development Kit

ZK supports JDK[5]

5, 6 and later[6]

. You could visit the Java website to download and install the version you want.

JDK 6

Download: http://www.oracle.com/technetwork/java/javase/downloads/jdk6-jsp-136632.html

Installation Instructions: http:/

/

www.

oracle.

com/

technetwork/

java/

javase/

index-137561.

htmlJDK 5

Download: http://www.oracle.com/technetwork/java/javase/downloads/index-jdk5-jsp-142662.html

Installation Instructions: http://java.sun.com/j2se/1.5.0/install.html

[1] http://java.sun. com/docs/books/tutorial/java/nutsandbolts/index. html

[2] http://java.sun. com/docs/books/tutorial/java/concepts/index.html

[3] http://java.sun. com/docs/books/tutorial/java/javaOO/index. html

[4] http://java.sun. com/docs/books/tutorial/java/IandI/index.html

[5] Java SE Development Kit

[6] For Java 1.4, please use ZK 5 instead.

Version History

Version Date Content

New to Java Servlet

You don't need to know Java Servlet to use ZK, since ZK encapsulates the HTTP requests to higher-level concepts,

such as ZUL pages and executions. However, it is helpful if you have some Java Servlet concepts[1]

.

Java Servlet Tuturials

A Web container[2]

is a server to serve HTTP requests. A software developer who wants to add dynamical content

usually implements a so-called Java Servlet[3]

.

A Java Servlet[3]

is a Java class responsible for processing HTTP requests and then generating the corresponding

HTTP response (usually in the format of HTML), based on the requirement of your applications.

A Web container is also known as a Servlet container. Tomcat[4]

is one of the most famous Web containers.

Rich Java[1]

offers a good tutorial about Java Servlet.

5/28/2018 ZK 6.5.0 Installation Guide

6/115

New to Java Servlet 3

Version History

Version Date Content

References[1] http://richjava.wordpress.com/

[2] http://en.wikipedia.org/wiki/Web_container

[3] http://www.google.com. tw/search?q=define:Java+Servlet

[4] http://tomcat.apache.org/

Quick Start

This chapter describes how to quickly start your first ZK application.

Create and Run Your First ZK Application with

Eclipse and ZK Studio

ZK Studio[1]

is an Eclipse plugin to simplify the development of ZK applications with Eclipse.

If you prefer to install it manually or use with other IDE, please refer to Create and Run Your First ZK Application

Manually.

Prepare Eclipse

Install Eclipse

1. Visit Eclipse download page[2]

and download Eclipse IDE for Java EE Developers[3]

2. Uncompress it to a proper directory

3. Then, eclipse is ready to start for use.

For example, you could double-click eclipse.exe to start Eclipse under Windows.

Prerequisites

You can follow ZK Studio Installation Guide [4] to install ZK Studio. There are prerequisites you have to set up

before installing ZK Studio:

Java SE Development Kit (JDK)

Java SE Development Kit version 5 or 6 is required in order to run Eclipse, you can download either of them from

the links below:

JDK 6

http://java.sun.com/javase/downloads/index.jsp[5]

JDK 5

http://java.sun.com/javase/downloads/index_jdk5.jsp [6]

5/28/2018 ZK 6.5.0 Installation Guide

7/115

Create and Run Your First ZK Application with Eclipse and ZK Studio 4

For detailed information on JDK installation, please see http://java. sun.com/javase/ 6/ webnotes/ install/ index.

html[7]

, or http://java.sun.com/j2se/1.5.0/install.html[8]

Eclipse IDE for Java EE Developers

ZK Studio is an Eclipse Plug-in so you must install Eclipse in advance. The following Eclipse IDE for Java EE

Developers packages are recommended:

Eclipse v3.6 (Helios)

http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr1[9]

Eclipse v3.5 (Galileo)

http://www.eclipse.org/downloads/packages/release/galileo/sr2[10]

Please also see WTP Tutorials Building and Running a Web Application[11]

for details.

Application Servers

Before developing web applications in Java with the ZK Ajax Framework, you need to install an application server.

Apache Tomcat is one of the most popular Web containers. Tomcat versions 6 and 7 are compatible with ZK Studioand can be downloaded from the link http://tomcat.apache.org/

[4].

Download the zip file of Tomcat distribution and extract it into a proper location (with no illegal characters or space

in the pathname). Tomcat requires configuration before it works with Eclipse, please see ZK Studio Essentials for

details.

Installing ZK Studio

Please follow the installation guide for your Eclipse version:

Eclipse v3.6 (Helios)

Installation Guide for Eclipse v3.6 (Helios) Eclipse 3.5 (Galileo)

Installation Guide for Eclipse 3.5 (Galileo)

Eclipse 3.4 (Ganymede)

Installation Guide for Eclipse 3.4 (Ganymede)

Eclipse 3.3 (Europa)

Installation Guide for Eclipse 3.3 (Europa)

Defining a Server Runtime

Before deploying and testing your application, you have to install a Web server (such as Tomcat) and specify the

server in eclipse. For more information on how to install a server, please also see ZK Installation Guide/Setting up

Servers/Tomcat.

To specify the server in eclipse, please do as follows.

1. From menu goto Windows > Preferences...

2. Select Server > Runtime Environments, then click Add

3. Select Apache > Apache Tomcat v6.0 and then click Next

4. Browse to and select the root directory of the Web server installed in your computer

For example, the root directory of Apache Tomcat might be C:\Program Files\Apache Software

Foundation\Tomcat 6.0

For how to install Tomcat, please refer to this section

5/28/2018 ZK 6.5.0 Installation Guide

8/115

Create and Run Your First ZK Application with Eclipse and ZK Studio 5

5. Click Finish

Create a "Hello World" application from scratch with ZK Sutdio

Create a new "ZK Project"

With the release of ZK Studio you no longer have to create a new Dynamic Web Project and configure the settings

for ZK! You can create a new ZK Project, choose your ZK Package and sit back while ZK Studio does the rest for

you.

The following swf demonstrates how to create a new ZK project using Eclipse 3.4 and ZK Studio: Zk_studio_094_new_zk_project.swf

For detailed steps, please refer to Create a New ZK Project

Create a new ZUL file

1. Right click on the WebContent folder in the Project Explorer view or the Package Explorer view andselect New > ZUL.

2. Type test.zul in the File name textbox and click Finish.

5/28/2018 ZK 6.5.0 Installation Guide

9/115

Create and Run Your First ZK Application with Eclipse and ZK Studio 6

3. The newly created ZUL File will be opened in the ZUL Editor.

5/28/2018 ZK 6.5.0 Installation Guide

10/115

Create and Run Your First ZK Application with Eclipse and ZK Studio 7

Run the application

1. Right click on the MyApp project in explorer and in the Menu dialog select Run As > Run on Server

2. Select Apache > Tomcat v6.0 Server in the server type dialog and then click Finish

3. View the result in your browser.

Version History

Version Date Content

References

[1] http://www.zkoss.org/product/zkstudio

[2] http://www.eclipse.org/downloads/

[3] http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR2/

eclipse-jee-ganymede-SR2-win32.zip

[4] http://books. zkoss.org/wiki/ZK_Studio_Essentials/Installation

[5] http://java.sun. com/javase/downloads/index.jsp[6] http://java.sun. com/javase/downloads/index_jdk5.jsp

[7] http://java.sun. com/javase/6/webnotes/install/index.html

5/28/2018 ZK 6.5.0 Installation Guide

11/115

Create and Run Your First ZK Application with Eclipse and ZK Studio 8

[8] http://java.sun. com/j2se/1.5.0/install.html

[9] http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr1

[10] http://www.eclipse.org/downloads/packages/release/galileo/sr2

[11] http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.html

Create and Run Your First ZK Application withEclipse and Maven

M2eclipse[1]

is the first and most mature of the projects aimed at integrating Apache Maven[2]

within the Eclipse

IDE.

Prepare Eclipse

Install Eclipse

Please follow the installation guide for your Eclipse:

Install Eclipse

Install M2eclipse

Please follow the installation guide for your M2eclipse:

Install M2eclipse

5/28/2018 ZK 6.5.0 Installation Guide

12/115

Create and Run Your First ZK Application with Eclipse and Maven 9

Add ZK Maven Archetype

[Window] -> [Preferences] -> [Maven] --> [Archetypes], clickAdd Remote Catalog and type in the catalog file

as illustrated:

http://mavensync.zkoss.org/maven2/

Click Verify and then OK to add the catalog.

If the Remote catalog is empty.[3]

[1] http://www.eclipse.org/m2e/

[2] http://maven.apache.org/

[3] If an error message appears stating that the Remote catalog is empty, this is most likely due to a bug in the m2eclipse plugin in v0.12.x,

MNGECLIPSE-2757 (https://issues.sonatype.org/browse/MNGECLIPSE-2757). Until m2eclipse 0.13.x or newer versions are released

and available, there are two possible workarounds:

1. Install the "older version" 0.10.x from the Installing m2eclipse (http://m2eclipse.sonatype.org/installing-m2eclipse.html) website.

Users will first need to uninstall m2eclipse 0.12.x, restart, and then install 0.10.x available from the following site:

http://m2eclipse.sonatype.org/sites/m2e/0.10.2.20100623-1649/

2. Install the newer version from the following site: http://download.eclipse.org/technology/m2e/releases You first will need to

uninstall m2eclipse 0.12.x, restart Eclipse before you can install the newer version from the website above. (Please note: the newer

version of M2eclipse plugin is not compatible with the old Maven Project. Therefore you must enable your maven project with the latest

M2eclipse plugin from the Installing m2eclipse website.)

3. Create the plugin from the archetype using the Maven command line tool mvn, then use import existing maven project to add the

generated project to Eclipse. For more details, please refer to Use the command line version of Maven to create a project.

5/28/2018 ZK 6.5.0 Installation Guide

13/115

Create and Run Your First ZK Application with Eclipse and Maven 10

Create a "Hello World" application with ZK Maven Archetype

Create a Maven Project

[File] -> [New] -> [Other] --> [Maven Project]

Make sure Create a simple project is unticked in the first screen of the New Maven Project wizard and click Next

>.

5/28/2018 ZK 6.5.0 Installation Guide

14/115

Create and Run Your First ZK Application with Eclipse and Maven 11

From the Select an Archetype screen, select ZK Maven Archetype from the catalog dropdown list.

Selectzk-archetype-webapp from the list. (At the time of writing this is at version 6.0).

Next, fill in details for group id, artifact id, version number andpackage name.

5/28/2018 ZK 6.5.0 Installation Guide

15/115

Create and Run Your First ZK Application with Eclipse and Maven 12

If the propertyzk-version-since is missing.[1]

Click Finish and the Eclipse status bar should say ' Creating zk-archetype-webapp ' and ' Updating Maven

Dependencies '. If this is the user's first time dealing with ZK libraries, Maven will download the necessary

dependencies to compile and run this example, and would be stored in .m2/repository in the user's home directory.

5/28/2018 ZK 6.5.0 Installation Guide

16/115

Create and Run Your First ZK Application with Eclipse and Maven 13

[1] Users who are running this wizard for the first time, ZK Archetype would not have been downloaded into m2eclipse yet, and as a result may

not populate thezk-version-since property correctly, leading to an error message like the following:

Unable to create project from archetype [org.zkoss:zk-archetype-webapp:6.0 ->

http://mavensync.zkoss.org/maven2/], Archetype org.zkoss:zk-archetype-webapp:6.0 is not configured property

''zk-version-since'' is missing. The simple workaround for this problem is to just try again after clicking Finish to

end the ZK Maven web project wizard. When re-running the wizard, the zk-version-since property should appear inthe list this time.

Run the application

1. Go to Run As> Maven build...

2. In the goals field, enterjetty:stop jetty:run and tick Skip Tests then click "Apply" then "Run".

3. View the result in your browser.

http://localhost:8080/mywebapp/index.zul (http://localhost:8080/mywebapp/index.zul)

5/28/2018 ZK 6.5.0 Installation Guide

17/115

Create and Run Your First ZK Application with Eclipse and Maven 14

Packaging your porject into a Web Application Archive (WAR)

1. Go to Run As> Maven install

2. The project will then be packed into a war file and a zip file with source code.

Use the command line version of Maven to create a project

Create a Maven project

For instructions on how to set up maven, please refer to Maven (http://maven.apache.org/guides/

getting-started/maven-in-five-minutes.html).

Go to the folder in Eclipse workspace, then run the following command:

Calling archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/'' - the plugin will first

ask 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 and the

base package for the sources.

It will then ask for confirmation of the configuration and perform the creation of the project.

5/28/2018 ZK 6.5.0 Installation Guide

18/115

Create and Run Your First ZK Application with Eclipse and Maven 15

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 andpackage to com.foo'.

$ mvn archetype:generate -DarchetypeCatalog=http://mavensync.zkoss.org/maven2/

[INFO] Scanning for projects...

[INFO] Searching repository for plugin with prefix: 'archetype'.

[INFO] ------------------------------------------------------------------------

[INFO] Building Maven Default Project

[INFO] task-segment: [archetype:generate] (aggregator-style)

[INFO] ------------------------------------------------------------------------

[INFO] Preparing archetype:generate

[INFO] No goals needed for project - skipping

[INFO] [archetype:generate {execution: default-cli}]

[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: http://mavensync.zkoss.org/maven2/ -> zk-archetype-component (An archetype th

at generates a starter ZK component project)

2: http://mavensync.zkoss.org/maven2/ -> zk-archetype-extension (An archetype th

at generates a starter ZK extension project)

3: http://mavensync.zkoss.org/maven2/ -> zk-archetype-webapp (An archetype that

generates a starter ZK CE webapp project)

4: http://mavensync.zkoss.org/maven2/ -> zk-ee-eval-archetype-webapp (An archety

pe 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] ------------------------------------------------------------------------

5/28/2018 ZK 6.5.0 Installation Guide

19/115

Create and Run Your First ZK Application with Eclipse and Maven 16

Import a Maven project into Eclipse

[File] -> [Import] -> [Maven] --> [Existing Maven Projects]

After this, the user should now get a new project in the Package explorer.

5/28/2018 ZK 6.5.0 Installation Guide

20/115

Create and Run Your First ZK Application with Eclipse and Maven 17

Version History

Version Date Content

Create and Run Your First ZK Application withNetBeans and REM

REM[1]

is a NetBeans module for ZK application development contributed by Mr. Sotohiro Terashima.

Install NetBeans REM

Install NetBeans

1. Download the latest NetBeans IDE from here [2]

2. Follow the installation wizard

Install REM plugin

1. Download the latest REM plugin from here[3]

2. Start NetBeans

3. On NetBeans' main menu bar, select Tools > Plugins.

4. Click on the "Downloaded" tab, followed by "Add Plugins" to open the file explore

5. Navigate to where REM is downloaded and select the REM plugin

5/28/2018 ZK 6.5.0 Installation Guide

21/115

Create and Run Your First ZK Application with NetBeans and REM 18

6. Click "Install" and follow the NetBeans plugin manager prompts

Create a New ZK Project

1. On NetBeans main menu bar, select "New Project"2. On the New Project wizard under "Categories", select "Java Web"

5/28/2018 ZK 6.5.0 Installation Guide

22/115

Create and Run Your First ZK Application with NetBeans and REM 19

3. Confirm and create a new ZK project.

4. Select the ZK project folder, and right click "Run" to deploy the project on Glassfish

5/28/2018 ZK 6.5.0 Installation Guide

23/115

Create and Run Your First ZK Application with NetBeans and REM 20

Deploy the ZK Demo Project

1. On NetBeans main menu bar, select "New Project"

2. On the New Project wizard under "Categories", expand the "Samples" folder and select "Java Web"

3. Select "ZK505 Demo Project" under "Projects"

4. Select the ZK demo project and right click to select "Run" to deploy the ZK demo

5/28/2018 ZK 6.5.0 Installation Guide

24/115

Create and Run Your First ZK Application with NetBeans and REM 21

Version History

Version Date Content

References[1] http://rem1.sourceforge.net/

[2] http://www.netbeans.org/downloads/index. html

[3] http://sourceforge.net/projects/rem1/files/

Create and Run Your First ZK Application

Manually

Prepare the server

Install Tomcat

First, you have to prepare a Web server. You can use any Web servers that support Java Servlet (2.3 or later). Here

we introduce the installation of Tomcat[1]

. For other servers and more information, please refer to Setting up

Servers.

1. Visit Tomcat Official Site[4]

2. Select the correct binary distribution for your environment and download

For Windows, you might download and execute 32-bit/64-bit Windows Service Installer[2]

, and then follow

the instructions

For any download/installation problems, please refer to http://tomcat.apache.org/tomcat-6.0-doc/index.

html

Download ZK Libraries

ZK libraries can be downloaded from ZK Download[3]

and then save it to a proper location.

Create your first application

Here shows you how to create a web application manually without IDE or other tools.

Create Web application

ZK Web Applications use a standard directory structure defined in the Servlet specification.

When developing ZK web applications, you must follow this structure so that the application can be deployed in any

J2EE compliant web servers.

All you need to do is create a web application directory with related files. Now i create one for example named myZK

5/28/2018 ZK 6.5.0 Installation Guide

25/115

Create and Run Your First ZK Application Manually 22

Install Library Distribution

1. Unzip zk-bin-x.x.x.zip (thex.x.x is the latest version)

2. Copy JAR files under following list to myZK/WEB-INF/lib

{YOUR_ZK_UNZIP_FOLDER}/dist/lib

{YOUR_ZK_UNZIP_FOLDER}/dist/lib/ext

{YOUR_ZK_UNZIP_FOLDER}/dist/lib/zkforge

Create Deployment Descriptor(Web.xml)

web.xml is called the web application deployment descriptor. This is an XML file that defines servlets, servlet

mappings, listeners, filters, welcome files etc.

The deployment descriptor is a heart of any J2EE web applications, so every web applicationmust have a web.xml

deployment descriptor directly under WEB-INF folder.

For the content of web.xml, please refer to Sample of web.xml for Servlet 3.0, Sample of web.xml for Servlet 2.4

or Sample of web.xml for Servlet 2.3, depending on your Web server support.

Create First ZUL file

Here is a simple zul file named hello.zul.

Hello World!

Pack your project

1. Compress the myZK directory(e.g. myZK.zip)

2. Rename myZK.zip to myZK.war3. Done!!

Confirm your ZK Web Archive (WAR) file

myZK.war

hello.zul

- WEB-INF

web.xml

- lib

*.jar

5/28/2018 ZK 6.5.0 Installation Guide

26/115

Create and Run Your First ZK Application Manually 23

Version History

Version Date Content

References[1] http://tomcat.apache.org

[2] http://apache.stu.edu.tw//tomcat/tomcat-6/v6.0.29/bin/apache-tomcat-6.0.29.exe

[3] http://www.zkoss.org/download/zk.dsp

ZK Background

This chapter describes the information of ZK installation, such as the sample of web.xml and the content of the

binary distribution.

Sample of web.xml for Servlet 3.0

ZK 6 supports Servlet 3.0 Pluggability, so you don't have to configure WEB-INF/web.xml at all.

MyApp

On the other hand, if metadata-complete=true was specified in WEB-INF/web.xml (i.e., the support of pluggability

is disabled), you have to configure ZK servlets and listeners manually as described in the Sample of web.xml for

Servlet 2.4.

Version History

Version Date Content

6.0.0 December 2011 The support of Servlet 3.0 Pluggability was introduced.

5/28/2018 ZK 6.5.0 Installation Guide

27/115

Sample of web.xml for Servlet 2.4 24

Sample of web.xml for Servlet 2.4

After the ZK libraries have been deployed to a Web application, we have to configure web.xml to install the required

Servlets, listener and mapping: DHtmlLayoutServlet[1]

, DHtmlUpdateServlet[2]

, and HttpSessionListener[3]

.

Here is the sample web.xml for servers that support Servlet 2.4 and later.

Notice that if you are using Servlet 3, you generally don't need to set up web.xml unless you'd like to configure

it different.

Notice that the ZK demo distribution has several web.xml files under the MyApp/WebContent/WEB-INF

directory: web.servlet-3.xml (for servers supporting only Servlet 3), web.servlet-2.4.xml (for servers

supporting Servlet 2.4 or later), and web.servlet-2.3.xml (for servers supporting only Servlet 2.3). You could

copy one of them instead of creating from scratch.

MyApp

ZK listener for session cleanup

org.zkoss.zk.ui.http.HttpSessionListener

ZK loader for ZUML pages

zkLoader

org.zkoss.zk.ui.http.DHtmlLayoutServlet

update-uri

/zkau

1

zkLoader

*.zul

zkLoader

*.zhtml

5/28/2018 ZK 6.5.0 Installation Guide

28/115

Sample of web.xml for Servlet 2.4 25

zkLoader

/zk/*

-->

The asynchronous update engine for ZK

auEngine

org.zkoss.zk.au.http.DHtmlUpdateServlet

auEngine

/zkau/*

index.zul index.zhtml

index.html

index.htm

Version History

Version Date Content

References

[1] http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/http/DHtmlLayoutServlet.html#

[2] http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/au/http/DHtmlUpdateServlet.html#

[3] http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/http/HttpSessionListener.html#

5/28/2018 ZK 6.5.0 Installation Guide

29/115

Sample of web.xml for Servlet 2.3 26

Sample of web.xml for Servlet 2.3

Here is the sample web.xml for servers that support Servlet 2.3 only.

Notice that the ZK demo distribution has two web.xml files under the MyApp/WebContent/WEB-INF

directory: web.xml (for servers supporting Servlet 2.4 or later), and web.servlet-2.3.xml (for servers

supporting only Servlet 2.3). You could copy one of them instead of creating from scratch.

MyApp

org.zkoss.zk.ui.http.HttpSessionListener23

zkLoader

org.zkoss.zk.ui.http.DHtmlLayoutServlet

update-uri

/zkau

1

auEngine

org.zkoss.zk.au.http.DHtmlUpdateServlet

zkLoader

*.zul

zkLoader

*.zhtml

5/28/2018 ZK 6.5.0 Installation Guide

30/115

Sample of web.xml for Servlet 2.3 27

-->

auEngine

/zkau/*

index.zul

index.zhtml

index.html

index.htm

Version History

Version Date Content

The Content of ZK Binary Distribution

Directory Structure

The content of the ZK binary distribution is as follows.

/doc

This directory holds the documents including release notes and license.

/dist

/dist/lib

This directory holds the ZK libraries

Filename Description License Shipped

zcommon.jar ZK's common library that ZK depends on (org.zkoss.*) LGPL All

zweb.jar ZK's Web library that ZK depends on (org.zkoss.web.* LGPL All

zk.jar ZK core functions, such as ZK Loader and Update Engine. (org.zkoss.zk.*) LGPL All

zul.jar ZUL components (org.zkoss.zul.*) LGPL All

zhtml.jar ZK HTML (ZHTML) components (org.zkoss.zhtml.*) LGPL All

zkbind.jar ZK Bind, including data binding and MVVM. LGPL All

zkplus.jar ZK extra utilities integrated easily with other frameworks. (org.zkoss.zkplus.*) LGPL All

zel.jar ZK's implementation of EL 2.2. It is based on Apache Tomcat 7's EL 2.2 implementation. Apache All

zkex.jar ZK professional ZUL components and utilities (org.zkoss.zkex.*) Commercial ZK PE and EE only

5/28/2018 ZK 6.5.0 Installation Guide

31/115

The Content of ZK Binary Distribution 28

zml.jar ZK XML components for generating XML output (org.zkoss.zml.*) Commercial ZK PE and EE only

zkmax.jar ZK enterprise components and utilities (org.zkoss.*) Commercial ZK EE only

/dist/lib/zkforge

This directory holds the additional components and libraries. It is optional depending on whether you needthem.

There are three kinds of binary distributions: CE, PE and EE. If not stated explicitly, it is shipped in all

distributions.

Filename Description License Version Shipped

sapphire.jar Required if you want to use the sapphire theme. LGPL 6.0.0 All

silvertail.jar Required if you want to use the silvertail theme. LGPL 6.0.0 All

ckez.jar Required if you want to use ZK CKeditor component. LGPL 3.6.0.1 All

timelinez.jar Required if you want to use ZK Timeline component. GPL 2.3.1_50 ZK PE and EE only

timeplotz.jar Required if you want to use ZK Timeplot component. GPL 1.1_50 ZK EE only

gmapsz.jar Required if you want to use ZK Google Maps component. GPL 2.0.52 ZK EE only

zuljsp.jar Required if you want to use ZK JSP Tags. GPL 2.0 ZK EE only

/dist/lib/ext

This directory holds the external libraries required to run ZK. Since these libraries are common, you might have

already installed them in your Servlet container. These jar files are optional. You can choose whether to copy

depending on your requirements.

Filename Description License Version Shipped

commons-fileupload.jar

commons-io.jar

Required if you want

to upload files with

them.

Apache Commons Fileupload 1.2.2

Commons IO 2.1

All

jcommon.jar

jfreechar.jar

Required if you want

to use ZUL's chart

component.

LGPL JFreeChart 1.0.14

JCommon 1.0.17

ZK PE and

EE only

jasperreports.jar

itext.jar

jxl.jar

poi.jar commons-collections.jar

commons-logging.jar

commons-digester.jar

Required if you want

to use the jasperreport

component.

LGPL

(jasperreports)

Jasper Reports 4.5.1 (itext: 2.1.7, commons-collections:

3.2.1, commons-logging: 1.1.1, commons-digester: 2.1,

jxl: 2.6.12, poi: 3.7)

Note: poi.jar is required if you want to use Apache POI togenerate Microsoft Excel format. And, jxl.jar is required

only if you want to use JExcelApi to generate the

Microsoft Excel format.

ZK PE and

EE only

bsh.jar Required if you want

scripting in Java

interpreter

(BeanShell).

LGPL BeanShell 2.0b4 All

Filters.jar Required if you want

to use the captcha

component.

Apache JH Labs Java Image Filters ZK PE and

EE only

The interpreters for Groovy (groovy.jar), Ruby (jruby.jar), Python (jython.jar), JavaScript (js.jar), MVEL

(mvel.jar) and OGNL (ognl.jar) are not shipped with the binary distribution since ZK 6. You could get them from

5/28/2018 ZK 6.5.0 Installation Guide

32/115

The Content of ZK Binary Distribution 29

their websites, or from ZK's Git repository (https://github.com/zkoss/zk/tree/master/dist/lib/ext).

/dist/src

This directory holds the source codes in JAR format. These JAR files are used for debugging in IDE, such as Eclipse

and NetBeans. You cannot build the binary libraries from these. Rather, download and uncompress

zk-src-6.0.0.tar.gz.

/dist/xsd

This directory holds the XSD files that might be useful to develop ZK applications.

/dist/WEB-INF

This directory holds the sample configuration file (web.xml and portlet.xml) and the TLD files. These TLD files are

part of JAR files so they are loaded automatically. We put them here mainly for your reference only.

Version History

Version Date Content

Setting up Servers

If you are new to Web servers, you could start with ZK Installation Guide/Setting up Servers/Tomcat.

5/28/2018 ZK 6.5.0 Installation Guide

33/115

Tomcat 30

Tomcat

Install Tomcat

1. Visit Tomcat Official Site[4]

2. Select the correct binary distribution for your environment and download

For Windows, you might download and execute 32-bit/64-bit Windows Service Installer[2]

, and then follow

the instructions

Any download/install problem, please refer to http://tomcat.apache.org/tomcat-6.0-doc/index.html

Deploy

Deploy ZK demo application(optional)

The simplest way to test drive ZK existed application is to download and install the ZK demo application.

This step is optional. You could skip it if you prefer to start creating your own application directly.

1. Download the lastest zkdemo at http://sourceforge.net/projects/zk1/files/ZK/(e.g. zk-sandbox-6.0.0.zip)

2. Unzip zk-sandbox-6.0.0.zip

3. Copy zkdemo.war under the zk-sandbox-6.0.0 directory to $TOMCAT_HOME/webapps.

4. Start/ReStart the tomcat services (In some cases, you may need to restart your container if it is running.)

5. Visit http://localhost:8080/zkdemo, and then play around with the demo application

Deploy war file to Tomcat is very easy but there're something you need to know

Tomcat will unzip the war file to filename\ directory automatically

You canNOT modify the content of filename\ directory unless you remove the war file, or your modification

will not work.

For more information about Tomcat's deployer, please refer to http://tomcat.apache.org/tomcat-6.0-doc/

deployer-howto.html

Deploy your application with IDE

When developing an application, we usually use IDE to deploy it. For more information, please refer to the

document of your IDE.

If you are new to Java IDE, you might take a look at Setting up Eclipse with ZK Studio.

Version History

Version Date Content

5/28/2018 ZK 6.5.0 Installation Guide

34/115

JBoss 31

JBoss

JBoss 4.0 and above

1. Download Jboss from http://www.jboss.com/downloads/index and install it,if you haven't installed it.

2. Test the Jboss using link http://localhost:port, if it's OK stop the server.

3. Unzip zk-demo-XXX.zip or zk-demo-XXX.tar.gz

4. Copy dist/lib/*.jar and dist/lib/*/*.jar to the $JBOSS_HOME/server/default/lib

5. Copy zkdemo.war to $JBOSS_HOME/server/default/deploy

6. Start the server.

7. Browse to http://localhost/zkdemo/userguide or http://localhost:8080/zkdemo/userguide depending on you

configuration for JBoss.

by Juan Jose Buendia Mardones (Chile)

JBoss 3.2.2 + tomcat 4.1

1. Follow the instruction to install ZK Ajax on tomcat 4.1.

2. Download the following files and copy them to the lib directory under default.

bsh-bsf-2.0b4.jar

bsh-core-2.0b4.jar

bsh-2.0b2.jar

3. Change the web.xml so that it will fit servlet 2.3 specifications.

4. We are still working on some problems and I will update this record when I'll have the full solution.

When I tried the solution given by Mars Chen some of the components built upon the Jboss platform didn't function

anymore. When doing my solution however one of the ZK components (the upload file) didn't work. But for now I

did a workaround to use tomcat 5.5 in the background.

by Yaniv Ran (USA)

2.1 There I got another simple solution: using ZK distribution's bsh.jar into JBoss lib directory to replace

bsh-core-version.jar.

Please refer BeanShell official site. == http:// www. beanshell. org/ download. html == The bsh-version.jar

containas all files in bsh-core-version.jar.

by Mars Chen (Taiwan)

Version History

Version Date Content

5/28/2018 ZK 6.5.0 Installation Guide

35/115

JBoss Cluster 32

JBoss Cluster

Before You Start

You have to configure the following setting for Web and JBoss.

web.xml

According to JBoss' tutorial, it is required to add the following settings in WEB-INF/web.xml if you are doing

clustering in JBoss.

jboss-web.xml

Create jboss-web.xml file under under XXX/WEB-INF folder(XXX is like ZKsandbox in the war file) if

fileupload component is used in your app.

For example,

warFileName

5/28/2018 ZK 6.5.0 Installation Guide

36/115

JBoss Cluster 33

Setting up JBoss 5.1.0 Clusters with Apache Load Balance

After you have done the settings above, please follow JBoss' official document to set up a JBoss Clustered Server

here[1]

.

References

[1] http://docs.jboss.org/jbossclustering/cluster_guide/5.1/html-single/index. html

WebSphere

IBM WebSphere

1. IBM offers a websphere application server community edition. Please go to http://www-128.ibm.com/

developerworks/downloads/ws/wasce/?S_TACT=105AGX10&S_CMP=WASCE to download it.

2. Follow the instruction to download, you might need to register for an account if you don't already have one.

3. Under downloads, choose Server and 32bit IBM SDK 1.4.2 SR4-1, procees to download.

4. Start the installer and accepts all defaults.

5. Once installation is completed, go to All Programs->IBM Websphere->Application

Server->Profiles->Default->Start the Server, this will start the server.

6. Browse http://localhost:9060/ibm/console/secure/logon.do to deploy application

7. After deployed, applications can be access via http://localhost:9080/myapp

8. For additional documentation and tutorials, go to http://publib.boulder.ibm.com/wasce/Front_en.html

ZK supports Servlet 2.3, 2.4 and later. The only difference is the content of WEB-INF/web.xml is a little

bit different. Please refer to Sample of web.xml and Sample of web.xml for Servlet 2.3.

IBM WebSphere 7

Import war file

1. Applications -> Application Types -> WebSphere enterprise applications -> Click install button

2. Select war file to import

5/28/2018 ZK 6.5.0 Installation Guide

37/115

WebSphere 34

3. Select Fast P

Find web application port

1. Servers -> Server Types -> WebSphere application servers -> Click "server1"

2. Communcations -> Click on "Ports"

5/28/2018 ZK 6.5.0 Installation Guide

38/115

WebSphere 35

3.

5/28/2018 ZK 6.5.0 Installation Guide

39/115

WebSphere 36

View Web application

Version History

Version Date Content

5/28/2018 ZK 6.5.0 Installation Guide

40/115

WebSphere Portal 37

WebSphere Portal

Setting up Websphere Portal

Download Websphere Portal from IBM[1]

Follow the installation guide here[2]

to install

Browse http://localhost:10039/wps/portal and set up admin account and password

Create ZK portlet project

since 6.0.1

Create a ZK project by ZK Studio

Add the following portlet.xml file under /WEB-INF

zk zk

org.zkoss.zk.ui.http.DHtmlLayoutPortlet

zk_page

/index.zul

0

text/html

zk

zk

zk

administrator

guest

5/28/2018 ZK 6.5.0 Installation Guide

41/115

WebSphere Portal 38

power-user

user

Export the project as a war file

Deploy ZK portlet in WebSphere Portal

Browse http://localhost:10039/wps/portal and login with admin account

ClickAdministration tab at the top of the page

Select Web Module then click the install button.

Click Choose File button to select the war file then press theNext button.

Check the war information and choose Start application, then click theFinish button.

Go back toHome page

Add a new tab page by clickingAction ->EditPage

ClickNew Page then enter "Page name" and "Friendly URL Name"

5/28/2018 ZK 6.5.0 Installation Guide

42/115

WebSphere Portal 39

Add the deployed portlet to the created new page by clickingAction ->EditPage.

Click Customize ->All -> in the search box, enter the portlet name defined in portlet.xml

Drag and drop the portlet into the created new page and click Save & Exit button.

ZK project is now deployed in a Websphere Portal

5/28/2018 ZK 6.5.0 Installation Guide

43/115

WebSphere Portal 40

Version History

Version Date Content

References[1] http://www14.software.ibm. com/webapp/download/byproduct.jsp?pgel=ibmhzn1&cm_re=masthead-_-supdl-_-dl-trials

[2] http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Installing_wp7

Oracle Server

Oracle OC4J and Oracle OPMN Release 3

OC4J 10.1.3 (release 3) is the first production version of Oracle Containers to support J2EE 1.4 specification

(Servlet 2.4).

1. Download OC4J 10.1.3 or later from http://www.oracle.com and install it.

2. You must setup OC4J to run with the -userThreads parameter at the command line (oc4j.cmd, on OPMN this is

done inside the opmn.xml )

3. Unzip zk-1.2.0-2006-04-07.zip or later version

4. Copy dist/lib/*.jar and dist/lib/ext/*.jar to the $OC4J_HOME/j2ee/home/applib

5. Start OC4J server and enter a new oc4jadmin's password if prompted or restart the server if it is already up

6. Open "Enterprise Manager" application - just browse to http://localhost:8888/em/

7. Login as oc4jadmin and go to Applications --> Deploy page

8. Deploy zkdemo.war (follow the on-screen instructions)

9. Browse to http://localhost:8888/zkdemo/userguide

Substitute "/zkdemo" with the context uri you entered in EM during deployment

Start OC4J Server:

bin/oc4j -start

10.1.2 and earlier

Prior versions 10.1.2.0.2, 10.1.2.0.1 supports only J2EE 1.3 (with Servlet 2.3), WEB-INF/web.xml shall be replaced

with Sample of web.xml for Servlet 2.3.

Notice that ZK supports Servlet 2.3 but the web.xml configuration file is a bit different. Also notice that ZK 6 and

later no longer support Java 1.4.

Version History

Version Date Content

5/28/2018 ZK 6.5.0 Installation Guide

44/115

WebLogic 41

WebLogic

1. Download Weblogic 9.1 from [1]

2. Start the Weblogic installer and accept all defaults.

3. Once the default installation is complete, create a weblogic domain by clicking Start->Programs->BEA

products->Tools->Configuration Wizard.

4. Select "Create New Weblogic Domain" and click Next.

5. Accept the defaults on "Select Domain Source" and click Next.

6. Enter a password in "Configure Administrator Username and Password" and click Next.

7. Accept all defaults on "Configure Server Start Mode and JDK" and click Next.

8. Selct No on Configure Environment Setting and Services" and click Next.

9. Accept all defaults on "Create Weblogic Domain and click Create.

10. Once the domain is created, check the check box labeled "Start Admin Server" and click Done.

11. The server will start up.

12. The HTTP port is default to 7001 unless you change it.

The easiest way to deploy your application is to copy your war/ear (it could be in an exploded format) to the

autodeploy directory under the weblogic installaton directory. If you followed the instruction above that

directory is located at C:\bea\user_projects\domains\base_domain\autodeploy. When you place your war/ear

file in that directory, weblogic will detect it and do a hot deployment.

If you want to copy ZK libraries to the domain, put them under c:/bea/user_projects/domains/base_domain/lib

Libraries that have to be copied include bsh.jar, commons-fileupload.jar, commons-el.jar, pxcommon.jar, pxweb.jar,

zk.jar, zul.jar, and zhtml.jar.

Version HistoryVersion Date Content

References

[1] http://commerce.bea.com/showproduct.jsp?family=WLS&major=9.1&minor=0

5/28/2018 ZK 6.5.0 Installation Guide

45/115

WebLogic Portal 42

WebLogic Portal

Introduction

Weblogic Portal provides several types of portlets, if you want to convert an existing zul page into a portlet, you can

consider using a JSP portlet.

Add JSP/HTML Portlet

1. Right click onportlet folder > [New] > [Portlet]

2. Give a file name then clickNext.

5/28/2018 ZK 6.5.0 Installation Guide

46/115

WebLogic Portal 43

3. Select JSP/HTML Portlet then clickNext.

4. CheckMinmizable andMaximizable and you can define title andzul page location then click Create.

5/28/2018 ZK 6.5.0 Installation Guide

47/115

WebLogic Portal 44

Add Zul page to your webapp

Create myZulPage.zul in the WebContent/portlet/myzulpage folder.

5/28/2018 ZK 6.5.0 Installation Guide

48/115

WebLogic Portal 45

Add portlet to portal page

1. Drag myZulPage.portlet to "Page 1" in the index.portal.

2. Done.

5/28/2018 ZK 6.5.0 Installation Guide

49/115

WebLogic Portal 46

Run the weblogic server

Run the server and access your application in the following link, http://localhost:7001/myPortalWebProject/

index.portal[1]

.

Version History

Version Date Content

References

[1] http://localhost:7001/myPortalWebProject/index.portal

5/28/2018 ZK 6.5.0 Installation Guide

50/115

WebLogic Cluster 47

WebLogic Cluster

Before You Start

You have to configure the following setting for ZK and Weblogic.

zk.xml

Turn on Serializable UI Factory for ZK, please refer to this documentation.

org.zkoss.zk.ui.http.SerializableUiFactory

5/28/2018 ZK 6.5.0 Installation Guide

51/115

WebLogic Cluster 48

Setting up Weblogic Clusters

After those things done above, please follow the official document to set up a Weblogic Cluster Server here[2]

.

Version History

Version Date Content

5.0.8 June 2011 Add ClusterSessionPatch listener to zk.xml for enforce Weblogic to write session.

References

[1] http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webapp/weblogic_xml.html#wp1071982

[2] http://download.oracle.com/docs/cd/E12840_01/wls/docs103/cluster/setup. html

Google App Engine

Get Your App Engine Account Ready

First, you have to sign up an App Engine[1]

account and download the App Engine SDK. Refer to the official

website[1]

for details.

To use Google App Engine for Java, you have to take one additional step: sign up here[2]

.

In addition, since GAE is a clustered platform, your application must be ready for clustering, such as

implementing serializable. For more information, please refer to ZK Developer's Reference:

Clustering/Programming Tips.

Configure Your App Engine Project

Here we assume you created a App Engine project. If not, please refer here[3]

.

There are three files that you have to configure: web.xml, zk.xml and appengine-web.xml . They all reside

in the WEB-INF directory.

The web.xml File

The content is similar to other ZK application except the AU engine has to be mapped to /zkau, too (in additions to

/zkau/*. Otherwise, AU requests won't be sent to the AU engine. Here is is an example.

ZK listener for session cleanup

org.zkoss.zk.ui.http.HttpSessionListener

zkLoader

org.zkoss.zk.ui.http.DHtmlLayoutServlet

update-uri

5/28/2018 ZK 6.5.0 Installation Guide

52/115

Google App Engine 49

/zkau

1

auEngine

org.zkoss.zk.au.http.DHtmlUpdateServlet

zkLoader

*.zul

auEngine

/zkau/*

auEngine

/zkau

index.zul

index.zhtml

index.html

The zk.xml File

Google App Engine is a cloud service, so you have to enable the clustering: disable event threads and use

serializable UI factory. In addition, Google App Engine doesn't allow users to create a working thread, so we have to

disable the resend mechanism.

Here is an example.

org.zkoss.zk.ui.http.SerializableUiFactory

org.zkoss.util.logging.hierarchy.disabled

true

5/28/2018 ZK 6.5.0 Installation Guide

53/115

Google App Engine 50

-1

With ZK 6 or later, you don't have to specify the library property called org.zkoss.util.logging.hierarchy.disabled.

Rather, just not to configure the logging at all (i.e., do not use any feature specified in ZK Developer's

Reference/Supporting Utilities/Logger). Then, java.util.logging.LogManager won't be used (which is prohibited by

GAE).

The appengine-web.xml File

App Engine requires one addition configuration file named appengine-web.xml. It resides in the WEB-INF

directory.

true

More Information

Due to the way App Engine serializes sessions, you have to use ZK 3.6.2 or later. In additions, there are some other

limitations.

You cannot define functions in zscript, since BeanShell's method can not be serialized correctly[4]

.

You cannot use captcha due to the limit support of AWT[5]

[1] http://code.google.com/appengine/

[2] http://appengine.google.com/promo/java_runtime[3] http://code.google.com/appengine/docs/java/gettingstarted/

[4] It runs correctly locally but not if uploaded. It could be done by specifying as a library property to disable the serializing of zscript methods

for the whole application.

[5] You will see a warning, ... Component captcha ignored., in the application log.

Memory Limitation and Solutions

GAE limits the session memory to 1 mega bytes. If a user visits several pages (with different URLs) in the same

browser session, there would be several desktops created and stored in the session, and it might run out the 1 mega

bytes. To avoid this, you can implement DesktopInit (http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/

util/ DesktopInit. html#) to remove other desktops in the desktop cache and specify it in WEB-INF/zk.xml as a

listener. For example,

5/28/2018 ZK 6.5.0 Installation Guide

54/115

Google App Engine 51

publicclassMyDesktopInitimplementsDesktopInit {

publicvoidinit(Desktop desktop,Object req)throwsException {

HttpServletRequest request =(HttpServletRequest)req;

//Remove old Desktop

String oldDesktopId =(String)

request.getSession().getAttribute("currentDesktopId");

WebAppCtrl ctrl =

(WebAppCtrl)Executions.getCurrent().getDesktop().getWebApp();

DesktopCache dc =ctrl.getDesktopCache(desktop.getSession());

dc.removeDesktop(dc.getDesktop(oldDesktopId));

//Add new Desktop

request.getSession().setAttribute("currentDesktopId",

desktop.getId());

}

}

Sample

Download (http://sourceforge.net/projects/ zk1/files/ZK for Google App Engine/) a sample application named

zk-gae.

You can visit it at http://zk-gae.appspot.com/hello.zul (http://zk-gae.appspot.com/hello.zul).

In additions, you could visit Bitbucket (https://bitbucket.org/antiso/zktest/src/143186a3ae8b/src/main/). It is a

sample project developed by Vladimir Sosnin, and the working demo is here (http:// tags42. appspot. com/

borderlayout/borderlayout.zul).

Version History

Version Date Content

5.0.8 June 2011 Add ClusterSessionPatch listener to zk.xml for enforce GAE to write session.

5.0.9 September

2011

In 5.0.7/5.0.8, we introduced a feature allowing developers to log the serialization. Unfortunately, it broke one of GAE

restriction: java.util.logging.LogManager is not accessible. It is fixed in 5.0.9 but specifying a library property called

org.zkoss.util.logging.hierarchy.disabled in WEB-INF/zk.xml.

5/28/2018 ZK 6.5.0 Installation Guide

55/115

Heroku 52

Heroku

Get Your Heroku Ready

Refer to Getting Started with Heroku[1]

for getting Heroku ready. You should have Ruby, Git, and Heroku Gem

installed and have applied for a Heroku account.

Deploy ZK Project to Heroku

Heroku only allow Maven Projects. Follow this guide[2]

to create a ZK-Maven Project. After you have created a

ZK-Maven project, you can decide to run with either Jetty or Tomcat.

ZK Maven Project With Jetty Server Embedded

1. Modify pom.xml to add embedded Jetty web container for running on Heroku.

org.apache.maven.plugins

maven-dependency-plugin

2.3

package

copy

org.mortbay.jetty

jetty-runner

7.5.4.v20111024

jetty-runner.jar

3. Create a file named Procfile in Project root to tell Heroku how to execute the application

web: java $JAVA_OPTS-jar target/dependency/jetty-runner.jar --port

$PORTtarget/*.war

5/28/2018 ZK 6.5.0 Installation Guide

56/115

Heroku 53

ZK Maven Project With Tomcat Server Embedded

1. Create Main.java in src/main/java with package launch to start embedded Tomcat server.

packagelaunch;

importjava.io.File;

importorg.apache.catalina.startup.Tomcat ;

publicclassMain{

publicstaticvoidmain(String[]args)throwsException {

String webappDirLocation ="src/main/webapp/";

Tomcat tomcat =newTomcat();

// The port that we should run on can be set into an

environment variable

// Look for that variable and default to 8080 if it isn't

there.

String webPort =System.getenv("PORT");

if(webPort ==null||webPort.isEmpty()){

webPort ="8080";

}

tomcat.setPort(Integer.valueOf(webPort).intValue());

tomcat.addWebapp("/",newFile(webappDirLocation).getAbsolutePath());

System.out.println("configuring app with basedir: "+new

File("./"+webappDirLocation).getAbsolutePath());

tomcat.start();

tomcat.getServer().await();

}

}

3. Modify pom.xml.

a) Removewar line to makeMain.class work

b) Add embedded Tomcat web container for running on Heroku.

...

org.apache.tomcat.embed

tomcat-embed-core

7.0.22

org.apache.tomcat.embed

5/28/2018 ZK 6.5.0 Installation Guide

57/115

Heroku 54

tomcat-embed-logging-juli

7.0.22

org.apache.tomcat.embed

tomcat-embed-jasper

7.0.22

org.codehaus.mojo

appassembler-maven-plugin

1.1.1

target

launch.Main

webapp

package

assemble

5/28/2018 ZK 6.5.0 Installation Guide

58/115

Heroku 55

...

7. Create a file named Procfile in Project root to tell Heroku how to execute the application

web: sh target/bin/webapp

Deploy to Heroku

Once the server is ready, we can deploy to Heroku.

1. Initialize git repository.

cd projectName

git init

3. Create a .gitignore file to ignore all the files under target folder as these files are unnecessary to be managed and

included by git repository.

target

5. Commit project source code to git repository.

git add .

git commit -m "CommitMessageNote"

7. Create Heroku app on Cedar stack and Heroku will create an app with a randomAppName that can be changed

later:

heroku create --stack cedar

9. Deploy the code

git push heroku master

11. Rename theAppName (Optional)

heroku rename newname

13. Visit the application

heroku open

5/28/2018 ZK 6.5.0 Installation Guide

59/115

Heroku 56

Update Source Code changes to Heroku

If you wish to make changes to the app deployed on Heroku, follow the steps below:

1. Commit project source code to git repository.

git add .

git commit -m "CommitMessageNote"

3. Deploy the code

git push heroku master

5. Visit the changes

heroku open

Sample

Download[3]

the sample maven project named heroku_zksandbox.zip.

Sandbox sample is deployed on Heroku at http://zksandbox.herokuapp.com/[4]

.

References

[1] http://devcenter.heroku.com/articles/quickstart

[2] http://books. zkoss.org/wiki/ZK_Installation_Guide/Setting_up_IDE/Maven/Create_and_Run_ZK_Application_with_Maven_Archetype

[3] http://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%20Sandbox%20for%20Heroku/

[4] http://zksandbox. herokuapp.com/

5/28/2018 ZK 6.5.0 Installation Guide

60/115

Red Hat OpenShift Express 57

Red Hat OpenShift Express

Get Your OpenShift Ready

Apply a new OpenShift account if you don't have a Red Hat Network (RHN) account.

If you prefer to use Eclipse, you can install Eclipse plugin to create OpenShift domain and application without

following the prerequisites and steps listed below. Here is the video[1]

that demonstrates how you can use Eclipse

plugin to do so. If you are doing so, you do not need to follow the next a few steps.

Refer to OpenShift User Guide[2]

for required client tools.

1. Prerequisites for Red Hat Enterprise Linux or Fedora:

RHEL 6 and up or Fedora 14 and up.

Express repo file openshift.repo[3]

View video walkthrough[4]

2. Prerequisites for Other Linuxes:

Root access

Ruby 1.8 or higher installed or available to be installed

Install the required packages: git, ruby, rubygems, and the ruby 1.8 development package.

3. Prerequisites for Mac:

git

4. Prerequisites for Windows:

Cygwin[5]

with the following optional components:

openssh

ruby

make gcc

git

RubyGems[6]

Create an OpenShift domain name

Run rhc-create-domain command to create an unique domain name for your application.

$ rhc-create-domain -n DomainName -l rhlogin -p password

-nDomainName specifies the domain that you want to create. This must contain a maximum of 16alphanumeric characters.

-lrhlogin your OpenShift Express or RHN account.

-ppassword your OpenShift Express or RHN password.

5/28/2018 ZK 6.5.0 Installation Guide

61/115

Red Hat OpenShift Express 58

Create a Maven Application

Run rhc-create-app command and OpenShift will create a maven project with default page automatically.

$ rhc-create-app -a AppName -t Type -l rhlogin -p password

-aAppName The name of the application to create (maximum of 32 alphanumeric characters).

-t Type The framework type to create. OpenShift Express currently supports the following application types:

php-5.3 for PHP applications

wsgi-3.2 for Web Server Gateway Interface applications

rack-1.1 for Ruby Webserver Interface applications

perl-5.10 for Perl applications

jbossas-7.0 for JBoss AS applications (used for ZK project)

raw-0.1 a raw cartridge type used to create applications of no specific type

-lrhlogin your OpenShift Express or RHN account.

-ppassword your OpenShift Express or RHN password.

Once it is done the application is on the cloud, you can visit http:/

/

AppName-DomainName.

rhcloud.

com/

to seethe default OpenShift page.

Import into Eclipse IDE (Optional)

If you wish to use Eclipse,

Run the following command to support Eclipse.

$ mvn eclipse:eclipse

Refer to here to import into Eclipse.

Deploy changes to OpenShift

Once you have created an OpenShift application in your local machine following the steps above, the application is

at the same time deployed to the cloud. To update and make changes to your application, you have to make changes

in the git directory specified during the application creation process.

There are two options to deploy the changes:

Option 1: Upload contents in a Maven src structure

This option is simple and recommended. Just push the source code with "git push" command.

$ cd AppName

$ git add .

$ git commit -a -m "Commit Message"

$ git push origin master

Then OpenShift will build your project on cloud. Once it's done you can visit http:// AppName-DomainName.

rhcloud.com/to see your application.

5/28/2018 ZK 6.5.0 Installation Guide

62/115

Red Hat OpenShift Express 59

Option 2: Upload prebuilt contents

If you do not wish OpenShift to build your project automatically, you have to remove pom.xml file and all the

source code.

$ cd AppName

$ git rm -r src/ pom.xml

Then, copy the pre-built war file into deployments folder and rename it to ROOT.war[7]

$ cp target/prebuilt.war deployments/ROOT.war

$ git add .

$ git commit -a -m "Commit Message"

$ git push origin master

Once it's done you can visit http://appName-domainName.rhcloud.com/to see the result

[1] https://www.redhat.com/openshift/community/blogs/deploying-java-apps-to-the-cloud-with-the-openshift-eclipse-plug-in

[2] http://docs.redhat.com/docs/en-US/OpenShift_Express/1.0/html/User_Guide/index.html

[3] https://openshift.redhat.com/app/repo/openshift.repo

[4] http://www.youtube.com/watch?v=KLtbuvyJFFE

[5] http://www.cygwin.com/

[6] http://rubyforge.org/projects/rubygems

[7] By default the warName is ROOT within the pom.xml file. This will render the webapp contents at http://app_name-namespace.rhcloud.

com.

If you change the warName in pom.xml to "app_name" or if the warName in deployments folder is "app_name.war", then your base URL

would become http://app_name-namespace.rhcloud.com/app_name.

Sample

Download (http:/

/

sourceforge.net/

projects/

zkforge/

files/

Small Talks/

ZK Sandbox for OpenShift/

?) thesample maven project named openshift_zksandbox.zip.

Sandbox sample is deployed on OpenShift at http://zksandbox-zksupport.rhcloud.com/.

5/28/2018 ZK 6.5.0 Installation Guide

63/115

Liferay 60

Liferay

Setting up Liferay

There are several ways in which an application can be set up within Liferay, the first one being to simply go to

Liferay[1]

and download the pre-bundled liferay tomcat bundle (other app server bundles are also available but

experiences indicate that other ones might be trickier to begin with as the configuration is usually more lengthy),

however, this option is not ideal if the user already have an existing tomcat server.

If the user already has a tomcat server on hand and does not particularly feel like deploying another one, the second

option would be to download "liferay war". Typically, Liferay's installation removes the ROOT folder from the

server, to avoid this situation, please stick to the following steps closely.

Download the non-bundled liferay war (Liferay Portal Professional 4.2.1 WAR) from Liferay[1]

Download the additional file called Liferay Portal 4.2.1 Dependencies, and unzip it to shared/lib

In order to keep the ROOT folder, extract the contents of the war into a folder, call it 'myportal' for instance.

Under the WEB-INF folder, create a 'classes' folder, in this folder create a file called 'portal-ext.properties', and in

this file place the following (note that users may of course change the portal.ctx and/or the lucene and jackrabbit

directory depending on later configurations):

portal.release=professional

portal.ctx=/myportal

auto.deploy.dest.dir=../webapps

portal.instances=1

lucene.dir=C:/home/liferay/lucene

jcr.jackrabbit.repository.root=C:/home/liferay/jackrabbit

omniadmin.users=

Go back to the WEB-INF folder and edit the web.xml - change the root_path to have a param value of '/myportal',

so that the top of the web.xml will look as follows:

5/28/2018 ZK 6.5.0 Installation Guide

64/115

Liferay 61

.

.

.

Now go into the META-INF folder and add a file called 'context.xml' and add the following (configure this

according to own specifics, just make sure that the context path attribute is '/myportal', if the user does not use

mysql database and wants liferay to use hSQLdb, strip out the first Resource element):

Now for the real trick, liferay 4.2 has a small bug when changing the context to something other than the ROOT.

In the folder html/portal, find a file called load_render_portlet.jsp, open the file up and go to line 55-56 and it

should look like the following:

functionloadPortlet() {

varpath ="/c/portal/render_portlet";

however it should look as follows:

5/28/2018 ZK 6.5.0 Installation Guide

65/115

Liferay 62

functionloadPortlet() {

varpath ="/myportal/c/portal/render_portlet" ;

If the user wishes to use mySQL, modify the context.xml to the user's own configurations, the user will also need

to download the liferay-mysql script file and run it against the user's database.

Now, in the ROOT folder (i.e. C:\ for windows, / for UNIX/LINUX), create a 'home' folder (if it doesn't already

exist) and in that folder, create a 'liferay' folder. Make sure tomcat has permission to modify the folder.

Now, re zip the folder and rename the zip file to myportal.war, drop it into tomcat's webapps deploy directory and

(hopefully) a working liferay portal will appear.

Deploying a ZK portlet

Here, this guide assumes that users are familiar with and have created a ZK war.

First, in order to tell liferay about the portlet, create a class that looks like this:

/**

* Copyright (c) 2000-2006 Liferay, LLC. All rights reserved.

*

* Permission is hereby granted, free of charge, to any person

obtaining a copy

* of this software and associated documentation files (the

"Software"), to deal

* in the Software without restriction, including without limitation

the rights

* to use, copy, modify, merge, publish, distribute, sublicense, and/or

sell

* copies of the Software, and to permit persons to whom the Software

is

* furnished to do so, subject to the following conditions:

*

* The above copyright notice and this permission notice shall be

included in

* all copies or substantial portions of the Software.

*

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR

* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

MERCHANTABILITY,

* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT

SHALL THE

* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR

OTHER

* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,

ARISING FROM,

* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER

DEALINGS IN THE

* SOFTWARE.

*/

5/28/2018 ZK 6.5.0 Installation Guide

66/115

Liferay 63

packageza.co.mypackage.portlet;

importjava.io.IOException;

importjavax.portlet.ActionRequest;

importjavax.portlet.ActionResponse;

importjavax.portlet.GenericPortlet;

importjavax.portlet.PortletException;

importjavax.portlet.PortletRequestDispatcher ;

importjavax.portlet.RenderRequest;

importjavax.portlet.RenderResponse;

importorg.apache.commons.logging.Log;

importorg.apache.commons.logging.LogFactory ;

/**

* @author Brian Wing Shun Chan

* @modified Glenn Keith

*/

publicclassJSPPortletextendsGenericPortlet {

publicvoidinit()throwsPortletException {

editJSP =getInitParameter("edit-jsp");

helpJSP =getInitParameter("help-jsp");

viewJSP =getInitParameter("view-jsp"); }

publicvoiddoDispatch(RenderRequest req,RenderResponse res)

throwsIOException,PortletException {

String jspPage =req.getParameter("jspPage");

if(jspPage !=null){

include(jspPage,req,res);

}

else{

super.doDispatch(req,res);

}

}

publicvoiddoEdit(RenderRequest req,RenderResponse res)

throwsIOException,PortletException {

if(req.getPreferences()==null){

super.doEdit(req,res);

}

5/28/2018 ZK 6.5.0 Installation Guide

67/115

Liferay 64

else{

include(editJSP,req,res);

}

}

publicvoiddoHelp(RenderRequest req,RenderResponse res)

throwsIOException,PortletException {

include(helpJSP,req,res);

}

publicvoiddoView(RenderRequest req,RenderResponse res)

throwsIOException,PortletException {

include(viewJSP,req,res);

}

protectedvoidinclude(String path,RenderRequest req,

RenderResponse res)

throwsIOException,PortletException {

PortletRequestDispatcher prd =

getPortletContext().getRequestDispatcher(path);

if(prd ==null){

_log.error(path +" is not a valid include"); }

else{

prd.include(req,res);

}

}

protectedString editJSP;

protectedString helpJSP;

protectedString viewJSP;

privatestaticLog _log =LogFactory.getLog(JSPPortlet.class);

}

Next, create a 'liferay-display.xml' file that looks like the following in WEB-INF:

5/28/2018 ZK 6.5.0 Installation Guide

68/115

Liferay 65

Now, also in the WEB-INF, create a file called 'liferay-portlet.xml' that looks like the following:

5/28/2018 ZK 6.5.0 Installation Guide

69/115

Liferay 66

/view.zul

0

text/html

Sample JSP Portlet

Sample JSP Portlet

Sample JSP Portlet

guest

power-user

user

Note that the /view.zul reference in this file is the 'index' file of the portlet, and all these files have been

referenced as 'portletone', please change this as the name of the war file.

Finally, at the top of the web.xml file after add the following (followed by the typical ZK stuff):

.

.

.

sample-jsp-portlet

company_id

liferay.com

com.liferay.portal.kernel.servlet.PortletContextListener

5/28/2018 ZK 6.5.0 Installati