ZK Java File Generator

From Documentation
DocumentationSmall Talks2007AprilZK Java File Generator
ZK Java File Generator

Andrew SanClemente, Senior Software Architect, DigiHome (Massachusetts, USA).
April 30, 2007


The purpose of this application is to take a ZK .zul file and then generate the Java class file that extends the ZK window class for that .zul. This is only useful if you are utilizing the "use" clause inside of the .zul.

For example, if you have Hello.zul, inside of the .zul file the window declaration would look like the following :

<window id="hello" use="com.yourcompany.example.Hello">

What that means is that the Hello.zul file is expecting a java file called Hello.java that is part of the com.yourcompany.example package. This .zul file will then interact with that java file during the life of the page.

The generator will generate the following given a .zul input file :

1. The Java class file

  • Header comments
  • Import statements for the most common ZK components
  • The java class declaration that extends the ZK Window java class.

2. Member variable declarations for all listbox's, buttons, and textbox's.

3. The onCreate method that is called when the ZK Window is first displayed

4. Initialization of all component variables using the Window::getFellow method

  • This sets up a reference between the java member variable and the component on the screen it represents.

5. Method stubs for all button and listbox callback methods defined in the .zul file.

6. Initialization method stubs for all listbox's (since many require pre-loading with items at the time of onCreate).

Notes :

Currently the generator only cares about buttons, listbox's, and textbox's. This can be easily modified to include other components. Actually, all aspects of the generator can be easily modified to suit your specific needs. It's a very simply program and there is plenty of room to add even more generation to handle many common tasks.

Known Issues :

I recommend generating the output file to a different file than your intended target, what I mean by that is specify the output file to be something like Hello.java.gen. Then cut and paste the contents into your Hello.java file. The reason for this is I have encountered a problem when trying to use the generated file directly, the ZK compiler generates errors which I believe are caused by some hidden characters in the generated file that ZK doesn't like. Cutting and pasting seems to eliminate this problem, I haven't spent the time to debug this since cutting and pasting the contents of the file eliminates the issue. If somebody does figure it out please let us know.

Format of .zul file

Make sure that all of your buttons, listboxes, and textboxes have id's declared.

NOTE : If you do not want a component to have anything generated in the java file, do not declare an id for that component and it will be ignored.

Please download java source code here.

These id's should follow the java naming convention of first character lowercase and first character of contained words upper case. Examples: "nameTextBox" or "phoneNumberListBox". The reason for this is the id is used in the declaration of the member variable in the java file. The same goes for your callback definitions, Example :

<window id="hello" use="com.yourcompany.example.Hello">
	<button id="hellowWorldButton" onClick="hellow.hellowWorldButtonOnClickHandler()"/>

In this example the member variable name would be declared as follows in the Hello.java file :

	private Button hellowWorldButton = null;

The method created would look like the following :

	public void hellowWorldButtonOnClickHandler()

Instructions on use

Included is the ZKWindowFileGeneratorMain class which has the main method. This class takes in 5 command line arguments :

1. The input directory of the .zul file to use

IMPORTANT - the path must have an ending slash : /zul/example/

2. The name of the input file (the .zul file)

3. The output directory of where to place the generated java file

IMPORTANT - the path must have an ending slash : /java/example/

4. The name of the generated java file ( The part that precedes the .java.gen extension needs to match the name in the use clause in the .zul file - "Hello" in this case.)

5. The package that the generated java file belongs in.

Here are example command line arguments :

Input Dir     Input File Output Dir    Output File      Package
/zul/example/  Hello.zul  /java/example /Hello.java.gen  com.yourcompany.example

In the above example, a java file called Hello.java.gen in the package com.yourcompany.example would be generated and output to the /java/example/ directory using the file Hello.zul file in the /zul/example/ directory as input. Simply cut and paste the contents to your Hello.java file (see known issues for the reason behind this).

Use in Eclipse

One way to utilize this application from inside Eclipse is to simply create a new Java Application with ZKWindowFileGeneratorMain as the application. Go to the arguments tab and enter in the command line arguments for your specific case, apply the changes and then simply execute. To generate to or from different files, just change the command line arguments for the application and re-execute.

Please download the example code here.

Editor's note: After this smalltalk is published, another ZK contributor, Mostafa Morabit, has made some improvement on the original source code. Here is what he said:


 I made some improvements to your Code Generator. The processLine
 method is completely rewritten (is called now processDocument), it
 uses now JDOM to parse the ZUL file (zuml code is in fact XML).
 This solves the following bugs:
 - Scanning the whole line for “id” can fail in case you use a
 method name with “id” as substring. Example <button label="Add"
 onClick="addGrid.setVisible(true)" />

 - in method processLine you assume that every component begins and
 ends at one line, but in reality some components can occupy more
 than one line, see the following example:

 <radiogroup id="clientType" onCheck="hello.onSelectClientType(self,
    <radio id="business" value="1" label="Business" />      
    <radio id="residential" value="0" label="Residential" />

 Another benefit of using JDOM is that it checks the zul file for
 valid XML.

 I Also added intbox, checkbox and radiogroup components.
 Attached is the new version.

 I hope you appreciate my changes ;)


 Mostafa Morabit

You can download Morabit's code here.


Andrew SanClemente a Senior Software Architect for a startup company called DigiHome involved in the Home Automation space. He is involved in overall design of the system as well as the actual implementation. They are utilizing ZK, Java, JBoss, MySQL, EJB 3, and the Java Persistence API in their application.

Copyright © Andrew SanClemente. This article is licensed under GNU Free Documentation License.