Version Upgrade"

From Documentation
m
 
(38 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
−
=Feature comparison=
+
=Versioning=
−
ZK Framework is offered in 3 editions, CE, PE and EE. To see what features are included in each edition, visit the Feature Page.
+
ZK products follow [https://semver.org/ semantic versioning], where the three digits refer to MAJOR.MINOR.PATCH respectively. In the case where a hotfix is required, a fourth digit is introduced.   
 +
Except for major (first digit) upgrades, compatibility is generally maintained, or a fall-back mechanism is available.
  
−
=Upgrade the Library=
+
=Upgrade References=  
−
To upgrade from CE to ZK PE or EE, download the corresponding PE/EE binary files from the Download Page, or specify the evaluation repository and include required PE/EE dependencies if you use maven. Maven instructions here.
+
An introductory smalltalk is published for every MAJOR and MINOR release. For example [[Small_Talks/2020/September/New_Features_of_ZK_9.5.0 | New Features of ZK 9.5]]. The smalltalk highlights the most important changes as well as provides upgrade tips for upgrading to that specific version. View [https://www.zkoss.org/wiki/Category:New_Features all New Features articles].
  
−
In addition to the core ZK features, PE/EE users are given access to use certain add-ons and tools according to the package they are on. For example a EE user can use ZATS Mimic, ZK Spring, ThemePack themes and ZK Calendar - they are not packaged in the core ZK. To use these add-ons, you will have to either download the corresponding jar files from their download pages, or, include the dependency in your maven POM file.  
+
A detailed release note containing a list of fixed issues is available for every new release, including hotfixes. For example, [https://www.zkoss.org/product/zk/releasenote/9.0.0 ZK 9.0.0 release notes]. The [https://www.zkoss.org/product/zk/releasenote/ full release history] can be found here.
  
−
Reference the Feature Page to see what features are covered in PE/EE and reference  the content (jar) of binary distributions to see what comes in the core package.
+
An “upgrade notes” section will be included at the end of a release note when needed. The “upgrade notes” section points out API changes or changes that developers will most likely need to take actions accordingly.
  
−
=Use PE/EE specific components and features=
+
You can follow the same naming conventions as the examples provided above to search for the upgrade references you are looking for.
−
After upgrading to PE/EE, you have more components, features and Java classes to use.  
 
  
−
==Features enabled by default==
+
=Important/breaking changes=
−
After upgrading to PE/EE, some of the features are enabled by default. For example, the client render on demand feature will be enabled by default to improve the client-side performance.
+
{|  class="wikitable"
−
Also, with EE, the tablet UI will be enabled by default, when a tablet/mobile device connects to your application the tablet-supported components will switch themselves to the tablet theme.  
+
! width="70" | ZK Version
−
You can manually disable them in zk.xml if you are not ready.
+
!  | Description
 +
! width="150" | Reference
 +
|-
 +
|ZK 5.0||1. A major architectural change was made in ZK 5, affecting theming, UI creation, and client-side rendering. Upgrading from ZK 2.x or ZK 3.x to ZK 5 requires more effort. <br/>
 +
2. Event thread is now disabled by default. You can enable it in zk.xml if you need to use it.
 +
||[[Small_Talks/2010/January/New_Features_of_ZK_5.0 | Release Smalltalk]]
 +
<br/>
 +
[[Small_Talks/2010/April/Upgrading_to_ZK_5 | Upgrading to ZK 5]]
 +
|-
 +
|ZK 6.0||1. Requires JDK 5 or higher<br/>
 +
||[[Small_Talks/2012/February/New_Features_of_ZK_6 | Release Smalltalk]]
 +
|-
 +
|ZK 6.5||1. Introduced Mobile/Tablet support, EE edition will have a different style and behavior on a mobile device. You can turn it off in zk.xml if that's not desired.<br/>
 +
||[[Small_Talks/2012/September/New_Features_of_ZK_6.5 | Release Smalltalk]]
 +
|-
 +
|ZK 7.0||1. Re-implement the theme with new client technologies including CSS3 and LESS, and the DOM structure of components changes a lot. To upgrade a custom theme for an older version, you will need to redo the style customization based on the new theme. Please refer to [[ZK_Style_Customization_Guide/Upgrade_Customized_Style_From_other_ZK_Version/Upgrade_From_ZK_6.5| Upgrade From ZK 6.5]]. <br/>
 +
2. Drop IE6 & IE7 support.<br/>
 +
3. Deprecate several legacy packages and methods relating to session and event-thread.<br/>
 +
||[[ZK_Style_Customization_Guide/Upgrade_Customized_Style_From_other_ZK_Version | Custom Style Upgrade Guide]]
 +
<br/>
 +
[https://www.zkoss.org/product/zk/releasenote/7.0.0 Release Notes]
 +
|-
 +
|ZK 8.0||1. A new form binding based on proxy is introduced. If you have been using MVVM<br/>
 +
org.zkoss.bind.SimpleForm,<br/> org.zkoss.bind.impl.FormImpl, and<br/> org.zkoss.bind.impl.FormExt<br/>
 +
you have to migrate it to the new proxy binding, or, upgrade to ZK 9.5 which supports the legacy simple form binding.
 +
||[https://blog.zkoss.org/2015/02/03/zk8-new-form-binding-approach/ ZK 8 new form binding]
 +
<br/>
 +
[https://www.zkoss.org/product/zk/releasenote/8.0.0 Release Notes]
 +
|-
 +
|ZK 8.5||1. A new and default theme Iceblue is introduced. The new theme has larger margin and padding from the previous themes. If you are not ready to use the new default theme, you can switch back to the previous themes, or, use ZK 8.6’s compact theme.<br/>
 +
2. Drop IE8 support.
 +
||[[Small_Talks/2017/October/New_Features_of_ZK_8.5.0 | Release Smalltalk]]
 +
<br/>
 +
[https://www.zkoss.org/product/zk/releasenote/8.5.0 Release Notes]
  
−
==Change of default behavior==
+
|-
−
Some of the default behavior changes after you upgraded ZK edition. For example in the case of server push, with CE, it uses client polling. Once you upgrade to PE, the default push becomes comet push, and with EE it uses servlet 3 comet. Read more here.
+
|ZK 9.0||1. ZK 9 requires JDK 8 or later versions.<br/>
  
−
==Require configuration==
+
2. ZK Flex uses CSS 3 Flex instead. You can disable css flex and fall back to the previous implementation if needed.<br/>
−
Some PE/EE features are now available for you to use, but you will have to enable them by yourself. For example if you have a big grid or listbox, you can turn on render on demand to boost its performance.  
 
  
−
Please reference corresponding documentation for the relevant configurations or contact info@zkoss.org if you have any questions.
+
3. Packaging change: ZK Data binding 1 is moved to "zkplus-legacy"; ZK DSP Library is moved to a new module "zweb-dsp".<br/>
 +
||[[Small_Talks/2019/December/New_Features_of_ZK_9.0.0 | Release Smalltalk]]
 +
<br/>
 +
[https://www.zkoss.org/product/zk/releasenote/9.0.0 Release Notes]
  
 +
|-
 +
|ZK 9.1||1. The underlying jQuery version has been upgraded from jQuery 1.12 to jQuery 3.5. If you have custom javascript code that relies on jQuery, you may need to update accordingly.||[https://www.zkoss.org/product/zk/releasenote/9.1.0 Release Notes]
 +
|-
 +
|ZK 9.5||1. Optional libraries(slf4j-jdk14 and closure-compiler-unshaded) are no longer provided by default. You can plugin your preferred libraries if needed.||[[Small_Talks/2020/September/New_Features_of_ZK_9.5.0 | Release Smalltalk]]
 +
|-
 +
|ZK 9.6||1. The default desktop ID generator was replaced by a more secured one. If your tests depend on the previous generator, you can set it in system-config. <br/>2. Deprecated the method of isEditionValid() and encodeWithZK() of org.zkoss.zk.fn.ZkFns and core.dsp.tld.<br/>3. Since ZK 9.6, a JakartaEE-compatible package is released along with the current JavaEE-compatible package. For Jakarta EE 9 support, please use 9.6.0-jakarta version instead.<br/>4. Since 9.6.0, the transitive dependency of jasperreports was removed in zkex. To use the jasperreport component, please add it manually.<br/>
 +
||[[Small_Talks/2021/August/New_Features_of_ZK_9.6.0 | Release Smalltalk]]
 +
|-
 +
|ZK 10.0||1. ZK 10 requires JDK 11 or later versions. <br/> 2. Deprecate old themes: Breeze, Sapphire, Silvertail, and Atlantic <br/>3. ZK 10 works with modern browsers; IE11 and lower IE versions are no longer supported.<br/>4. Enable InaccessibleWidgetBlockService by default in the EE version. Note that it will block Echo Event if the component is disabled or invisible. You can configure it using the library-property org.zkoss.zkmax.au.IWBS.disable.<br/>5. ZK's corresponding features now require Java EE 7 API level, including Servlet 3.1, Bean Validation 1.1, EL 3.0, and JSP 2.3.<br/>6. Remove all deprecated Java APIs and the legacy module "zkplus-legacy". Reference the release smalltalk and the linter tool for upgrade guidance.<br/>7. ZK frontend is now typescript, if you have JS-based custom client-side, you may need to double-check.<br/>8. Some add-on components are updated to support ZK 10. Please refer to Release Smalltalk.
 +
||[[Small_Talks/2024/February/New_Features_of_ZK_10.0.0 | Release Smalltalk]]
 +
|}
  
 +
[https://tracker.zkoss.org/issues/?jql=labels%20%3D%20security Check all security fixes in the tracker]
  
 +
=Upgrade Process=
 +
Upgrading from ZK 5 (or later) to the latest version should be manageable. The steps are:
 +
 +
Specify the version you wish to upgrade to in your maven POM file, or, download corresponding binary files manually and put them into your project. It is important to make sure all ZK jar files are in the same version.
 +
 +
Then, fix any compilation errors and configure the required fallback settings by referencing the [[#Upgrade_References | Upgrade References]].
 +
 +
= Checklist=
 +
To estimate the upgrading effort, we suggest a checklist:
 +
 +
# Check Custom Components
 +
#: check if there is any [[ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon]] that might declare custom components. Since you might need to review it after the upgrade.
 +
# Check configuration description (zk.xml)
 +
#: Check each property in zk.xml upon [[ZK_Configuration_Reference/zk.xml| ZK Configuration Reference]] to see if there is any change in the new version.
 +
# Check Custom Appearance (CSS)
 +
#: If you customize a component's appearance with CSS, you might need to review it for the new version.
 +
# Check Programs Using ZK JavaScript API
 +
#: If you customize a component with JavaScript, you might need to review it for the new version.
 +
# Check Bug Patches
 +
#: Check [https://tracker.zkoss.org/ Bug Tracker] or [https://www.zkoss.org/product/zk/releasenote/ release note] for the existing bug patch. If that bug is fixed in the new version, you can remove the patch.
 +
# Check for Java Compiler Error
  
 
{{ ZKDevelopersReferencePageFooter}}
 
{{ ZKDevelopersReferencePageFooter}}

Latest revision as of 02:33, 9 April 2024


DocumentationZK Developer's ReferenceUpgrade TipsVersion Upgrade
Version Upgrade


Versioning

ZK products follow semantic versioning, where the three digits refer to MAJOR.MINOR.PATCH respectively. In the case where a hotfix is required, a fourth digit is introduced. Except for major (first digit) upgrades, compatibility is generally maintained, or a fall-back mechanism is available.

Upgrade References

An introductory smalltalk is published for every MAJOR and MINOR release. For example New Features of ZK 9.5. The smalltalk highlights the most important changes as well as provides upgrade tips for upgrading to that specific version. View all New Features articles.

A detailed release note containing a list of fixed issues is available for every new release, including hotfixes. For example, ZK 9.0.0 release notes. The full release history can be found here.

An “upgrade notes” section will be included at the end of a release note when needed. The “upgrade notes” section points out API changes or changes that developers will most likely need to take actions accordingly.

You can follow the same naming conventions as the examples provided above to search for the upgrade references you are looking for.

Important/breaking changes

ZK Version Description Reference
ZK 5.0 1. A major architectural change was made in ZK 5, affecting theming, UI creation, and client-side rendering. Upgrading from ZK 2.x or ZK 3.x to ZK 5 requires more effort.

2. Event thread is now disabled by default. You can enable it in zk.xml if you need to use it.

Release Smalltalk


Upgrading to ZK 5

ZK 6.0 1. Requires JDK 5 or higher
 Release Smalltalk
ZK 6.5 1. Introduced Mobile/Tablet support, EE edition will have a different style and behavior on a mobile device. You can turn it off in zk.xml if that's not desired.
 Release Smalltalk
ZK 7.0 1. Re-implement the theme with new client technologies including CSS3 and LESS, and the DOM structure of components changes a lot. To upgrade a custom theme for an older version, you will need to redo the style customization based on the new theme. Please refer to Upgrade From ZK 6.5.

2. Drop IE6 & IE7 support.
3. Deprecate several legacy packages and methods relating to session and event-thread.

 Custom Style Upgrade Guide


Release Notes

ZK 8.0 1. A new form binding based on proxy is introduced. If you have been using MVVM

org.zkoss.bind.SimpleForm,
org.zkoss.bind.impl.FormImpl, and
org.zkoss.bind.impl.FormExt
you have to migrate it to the new proxy binding, or, upgrade to ZK 9.5 which supports the legacy simple form binding.

ZK 8 new form binding


Release Notes

ZK 8.5 1. A new and default theme Iceblue is introduced. The new theme has larger margin and padding from the previous themes. If you are not ready to use the new default theme, you can switch back to the previous themes, or, use ZK 8.6’s compact theme.

2. Drop IE8 support.

Release Smalltalk


Release Notes

ZK 9.0 1. ZK 9 requires JDK 8 or later versions.

2. ZK Flex uses CSS 3 Flex instead. You can disable css flex and fall back to the previous implementation if needed.

3. Packaging change: ZK Data binding 1 is moved to "zkplus-legacy"; ZK DSP Library is moved to a new module "zweb-dsp".

 Release Smalltalk


Release Notes

ZK 9.1 1. The underlying jQuery version has been upgraded from jQuery 1.12 to jQuery 3.5. If you have custom javascript code that relies on jQuery, you may need to update accordingly. Release Notes
ZK 9.5 1. Optional libraries(slf4j-jdk14 and closure-compiler-unshaded) are no longer provided by default. You can plugin your preferred libraries if needed. Release Smalltalk
ZK 9.6 1. The default desktop ID generator was replaced by a more secured one. If your tests depend on the previous generator, you can set it in system-config.
2. Deprecated the method of isEditionValid() and encodeWithZK() of org.zkoss.zk.fn.ZkFns and core.dsp.tld.
3. Since ZK 9.6, a JakartaEE-compatible package is released along with the current JavaEE-compatible package. For Jakarta EE 9 support, please use 9.6.0-jakarta version instead.
4. Since 9.6.0, the transitive dependency of jasperreports was removed in zkex. To use the jasperreport component, please add it manually.
 Release Smalltalk
ZK 10.0 1. ZK 10 requires JDK 11 or later versions.
2. Deprecate old themes: Breeze, Sapphire, Silvertail, and Atlantic
3. ZK 10 works with modern browsers; IE11 and lower IE versions are no longer supported.
4. Enable InaccessibleWidgetBlockService by default in the EE version. Note that it will block Echo Event if the component is disabled or invisible. You can configure it using the library-property org.zkoss.zkmax.au.IWBS.disable.
5. ZK's corresponding features now require Java EE 7 API level, including Servlet 3.1, Bean Validation 1.1, EL 3.0, and JSP 2.3.
6. Remove all deprecated Java APIs and the legacy module "zkplus-legacy". Reference the release smalltalk and the linter tool for upgrade guidance.
7. ZK frontend is now typescript, if you have JS-based custom client-side, you may need to double-check.
8. Some add-on components are updated to support ZK 10. Please refer to Release Smalltalk. 		Release Smalltalk

Check all security fixes in the tracker

Upgrade Process

Upgrading from ZK 5 (or later) to the latest version should be manageable. The steps are:

Specify the version you wish to upgrade to in your maven POM file, or, download corresponding binary files manually and put them into your project. It is important to make sure all ZK jar files are in the same version.

Then, fix any compilation errors and configure the required fallback settings by referencing the Upgrade References.

Checklist

To estimate the upgrading effort, we suggest a checklist:

  1. Check Custom Components
    check if there is any ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon that might declare custom components. Since you might need to review it after the upgrade.
  2. Check configuration description (zk.xml)
    Check each property in zk.xml upon ZK Configuration Reference to see if there is any change in the new version.
  3. Check Custom Appearance (CSS)
    If you customize a component's appearance with CSS, you might need to review it for the new version.
  4. Check Programs Using ZK JavaScript API
    If you customize a component with JavaScript, you might need to review it for the new version.
  5. Check Bug Patches
    Check Bug Tracker or release note for the existing bug patch. If that bug is fixed in the new version, you can remove the patch.
  6. Check for Java Compiler Error



Last Update : 2024/04/09

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


Retrieved from "https://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/Upgrade_Tips/Version_Upgrade&oldid=57064"