ZK 6: Upgrade Notes"
m (→Overview) |
|||
| Line 7: | Line 7: | ||
=Overview= | =Overview= | ||
In additions to new features, ZK 6 also cleans up some API that are confusing, redundant or over complicated. The effort to upgrade depends on what features your application uses. Many of them shall run without modification. It is suggested to re-compile the applications and replace the code that use the deprecated API. | In additions to new features, ZK 6 also cleans up some API that are confusing, redundant or over complicated. The effort to upgrade depends on what features your application uses. Many of them shall run without modification. It is suggested to re-compile the applications and replace the code that use the deprecated API. | ||
| + | |||
| + | Also remember to remove <code>breeze.jar</code> since [[#Breeze is the default theme|breeze has become the standard theme]] and, without removing the old <code>breeze.jar</code>, it might cause some conflicts. | ||
=Upgrade addons = | =Upgrade addons = | ||
Revision as of 02:03, 14 February 2012
ZK Team, Potix Corporation
November 15, 2011
ZK 6
Overview
In additions to new features, ZK 6 also cleans up some API that are confusing, redundant or over complicated. The effort to upgrade depends on what features your application uses. Many of them shall run without modification. It is suggested to re-compile the applications and replace the code that use the deprecated API.
Also remember to remove breeze.jar since breeze has become the standard theme and, without removing the old breeze.jar, it might cause some conflicts.
Upgrade addons
Here is a list of addons that you have to upgrade:
- ZK JSP 2.0 or later. Download here.
- ZK Calendar 2.1.1 or later. Download here.
In additions, zcommons-el.jar is replaced with zel.jar supporting EL 2.2. If you prefer EL 1.1 (i.e., backward compatible with ZK 5), please remove zel.jar and copy zcommons-el.jar to your project instead[1].
- ↑ ZK Bind (our new generation of data binding) utilizes EL 2.2 to support two-way binding, so don't use zcommons-el.jar if you want to use the new data binding.
API that are changed
org.zkoss.zk.zul.api.* are removed
The component's API interfaces (org.zkoss.zk.ui.api.*, org.zkoss.zul.api.*...) are removed[1]. Please replace them with the concrete classes. For example, use org.zkoss.zul.Window instead of org.zkoss.zul.api.Window.
You could use the search-and-replace or refactor feature in your IDE to replace the package name. Here is an example that uses Eclipse to replace the package name.
- ↑ The reason to remove them is they cause more confusion than the abstraction benefit. In additions, they are costly and error-prone to maintain.
org.zkoss.zk.ui.util.Initiator is simplified
For easy extension and better consistency[1], the org.zkoss.zk.ui.util.Initiator class now has only one method called doInit. The doAfterComposer, doCatch and doFinally methods are moved to org.zkoss.zk.ui.util.InitiatorExt. In other words, if you'd like to override any of these methods, your initiator has to implement both org.zkoss.zk.ui.util.Initiator and org.zkoss.zk.ui.util.InitiatorExt.
org.zkoss.xel.FunctionMapper is simplified
For easy extension[1], the getClassNames and resolveClass methods of the org.zkoss.xel.FunctionMapper class are removed. On the other hand, org.zkoss.xel.FunctionMapperExt was introduced to have these methods. In other words, you'd like to implement any of these methods, you have to implement both FunctionMapper and FunctionMapperExt.
- ↑ The getClassNames and resolveClass methods are useful only for special evaluators, such as MVEL and OGNL
i3-label.properties is renamed to zk-label.properties
To avoid confusion, the default properties file for the internationalization labels is renamed to zk-label.properties[1].
- ↑ For backward compatibility,
i3-label.propertieswill be loaded ifzk-label.propertiesis not found.
API returns Iterable instead Iterator
To use with Java 5's for statement, the return type of the following APIs are changed to java.lang.Iterable:
- org.zkoss.zk.ui.Exectuion: getHeaders and getHeaderNames
- org.zkoss.zk.ui.WebApp: getInitParameterNames
- org.zkoss.zk.ui.RichletConfig: getInitParameterNames
Window, Messagebox and Fileupload won't throw InterruptedException
Window, Messagebox and Fileupload won't throw java.lang.InterruptedException anymore, since it won't happen if the event processing thread is disabled (default). If the event processing thread is enabled, InterruptedException will be wrapped with UiException.
addEventListener allows the same listener registered multiple times
Component's addEventListener now allows the same listener being registered multiple times, and the listener will be called multiple times.
If you prefer to ignore the second registration of the same listener (i.e., backward compatible with ZK 5 and earlier), you could specify a library property called org.zkoss.zk.ui.EventListener.duplicateIgnored to true in WEB-INF/zk.xml.
UiFactory's newComponent is changed
The newComponent method of the org.zkoss.zk.ui.sys.UiFactory is changed. In additions, two new methods newComposer and newServerPush were introduced to allow developers have more control of the instantiations.
GenericForwardComposer and GenericAutowireComposer won't wire variables defined in zscript and variable resolvers
For sake of better performance, org.zkoss.zk.ui.util.GenericForwardComposer and org.zkoss.zk.ui.util.GenericAutowireComposer won't wire variables defined in zscript and variable resolvers. If you prefer to write them as ZK 5 and earlier does, you could specify the library properties called org.zkoss.zk.ui.composer.autowire.zscript and org.zkoss.zk.ui.composer.autowire.xel to true.
Component's newChildren and newExtraCtrl are removed
The newChildren and newExtraCtrl methods of AbstractComponent are removed since they are redundant. Please override the getChildren and getExtraCtrl instead.
Component's setVariable is removed
Component's setVariable method is removed[1]. Please use Component.setAttribute(name, value, SPACE_SCOPE) instead. In other words, you could store the variables in the attributes of the space owner (Component.getSpaceOwner()).
- ↑ It was deprecated in ZK 5, since we don't maintain a separate namespace for each ID space.
The selection and open contract between Tree and TreeModel become TreeSelectableModel and TreeOpenableModel
For better performance, org.zkoss.zul.ext.TreeOpenableModel are introduced to replace
For backward compatibility, AbstractTreeModel also implements Selectable and Openable. Application is free to access it, though ZK doesn't count on them. However, since their contract is based the data objects, TreeModel.getPath(E) will be called to get the tree path. Thus, make sure your implementation is good if you invoke them a lot.
org.zkoss.zul.SimpleTreeModel and org.zkoss.zul.SimpleTreeNode are removed
The org.zkoss.zul.SimpleTreeModel and org.zkoss.zul.SimpleTreeNode classes are removed[1], and replaced with org.zkoss.zul.DefaultTreeModel and org.zkoss.zul.DefaultTreeNode.
- ↑ It was deprecated in ZK 5.0.6.
ListX, TreeArray and CheckableTreeArray are removed
The org.zkoss.util.ListX, org.zkoss.util.TreeArray and org.zkoss.util.CheckableTreeArray are removed. Please use java.util.LinkedList or java.util.ArrayList instead.
API that are deprecated
ListModelExt, TreeModelExt and GroupsModelExt are deprecated
The org.zkoss.zul.ListModelExt and org.zkoss.zul.TreeModelExt interface are deprecated, and replaced with Sortable. Also, org.zkoss.zul.GroupsModelExt is deprecated and replaced with GroupsSortableModel.
org.zkoss.zk.ui.event.Express is deprecated
The org.zkoss.zk.ui.event.Express interface is deprecated. Please use the addEventListener(int, String, EventListener) method instead, and assign the priority as 1000.
HTMLs, StyleSheet and JavaScript are moved
The HTMLs, StyleSheet and JavaScript classes are moved to the package called org.zkoss.html.
Notice the previous classes are still available but deprecated (not found in JavaDoc).
Theme and UI
Breeze is the default theme
The breeze theme has become the default styling, without the need to include breeze.jar. Please make sure you remove breeze.jar from your project. On the other hand, the sapphire and silvertail themes are packaged and delivered as they were in ZK 5. Of course, you have to upgrade to the version shipped with ZK 6's binary distribution.
Tablechildren and Columnchidlren support any child
Tablechildren and Columnchildren support any kind of child components, not limited to Panel. Thus, if you don't need the feature of Panel, you could remove it from your UI to make the layout structure simpler.
Groupbox's zclass is renamed to z-groupbox
To be consistent, the zclass of Groupbox's default mold is renamed to z-groupbox(it was called z-fieldset in ZK 5). The zclass of the 3d mold is renamed to z-groupbox-3d (it was called z-groupbox).
The vflex and hflex of Panelchildren are deprecated
The hflex/vflex properties of Panelchildren are determined by its parent Panel's hflex/vflex properties. The setHflex and setVflex methods of Panelchildren will throw UnsupportedOperationException. In other words, you shall control Panel rather than Panelchildren.
The hflex and width of Treerow, Rows... is deprecated
As the sizing of Grid/Listbox/Tree are controlled by Grid/Listbox/Tree and the header components (such as Treecol, Listheader and Column). By others, the hflex and width properties of them are irrelevant. Their setHflex and setWidth methods are deprecated. These components include: Treeitem, Treerow, Treecell, Treechildren, Treecols, Treefoot, Rows, Columns, Row, Cell, Foot, Listitem, Listcell, Listhead, Listfoot.
Messagebox's template is changed
Messagebox's template (i.e., ~./zul/html/messagebox.zul) is changed to support the new features such as reordering and custom labels. If you ever customized it, please refer to the source code for the details.
iZUML uses #{...} to represent an expression
The format of the expression used in iZUML (client-side ZUML) has become #{...}, such that it is easier to embed in a ZUML page where ${...} is used. In additions, iZUML is supported by ZK CE since ZK 6.
Optional but suggested
Use ZK Bind instead of old data binding
ZK Bind (org.zkoss.bind.*) is our new generation of data binding. It is more powerful and controllable, though the first version of data binding (org.zkoss.zkplus.databind.*) is still maintained. For more information, please refer to Envisage ZK 6: The Next Generation Data Binding System.
Notice that ZK Bind supports both data binding and MVVM. Data binding, as you are already familiar with, minimizes the effort to access database, while MVVM introduces additional abstract layer isolating the view dependence from the controller.
Use SelectorComposer instead of GenericForwardComposer
The org.zkoss.zk.ui.select.GenericAnnotatedComposer class provides more control how to wire the members. It is generally recommended. Of course, some might find org.zkoss.zk.ui.util.GenericForwardComposer's wire-by-convention is more convenient to use, and it is still supported.
Comments
| Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License. |