This is the release notes for XWiki Commons, XWiki Rendering and XWiki Platform. They share the same release notes as they are released together and have the same version.

The main focus of this version was developer tools such as introducing support for exposing WebSocket endpoints as XWiki components, making easier to handle skin extensions in asynchronous HTML content, a more accurate strategy to select between several similar Java methods in Velocity scripts and support for ConfigurableClass in all administration pages. It also comes with various bug fixes and improvements.

New and Noteworthy (since XWiki 13.6)

Full list of issues fixed and Dashboard for 13.7.

For Users

No changes!

For Admins

• Smaller serialized job status: Job status are now zipped (new jobs will end up with a file named status.xml.zip instead of status.xml). The content of the actual XML used to serialize the progress was also optimized a little (removed various metadata which did not really needed to be serialized) when possible. This should help reduce quite a lot the disk space used by some jobs statuses.

For Developers

WebSocket Integration

 
Starting with this version you can write WebSocket end-points as XWiki Components using the standard Java API for WebSocket (JSR 356). For deploying the end-points we rely on the servlet container, which means the servlet container needs to support WebSockets (i.e. it needs to provide an implementation of the JSR 356 specs). At the moment, this includes all the servlet containers we support. See the documentation for more information.

Automatic injection of required skin extensions

 
Lazy loading UI elements has become much easier with the automatic injection (on the client side) of the required skin extensions.

Method selection improvement in Velocity

 
When standard Velocity cannot match a method call, XWiki try to find a close approximation that could be called provided the arguments are converted. The only criteria to select a suitable method used to be to count the number of arguments, but the order in which methods with the same number of arguments were tried was pretty much random. This leaded sometime to either hard to call methods or random results. This has been greatly improved to have more advanced ordering (taking into account already compatible arguments, etc.), see Velocity Module for more details.

Allow to display ConfigurableClass in all administration pages

 
The ConfigurableClass has been refactored to use a new scope property for defining where it should be configured. This property can take 4 different values:

• WIKI (displayed Wiki): the configuration will be displayed in the wiki administration (equivalent to true value in configureGlobally for older versions)
• SPACE (displayed "Current space"): the configuration will be displayed in administration of pages that belongs to the current space (equivalent to false value in configureGlobally for older versions)
• ALL_SPACES (displayed "All spaces"): the configuration will be displayed on administration of pages for any space, but not on the wiki administration. 
• WIKI+ALL_SPACES (displayed "Wiki and all spaces"): the configuration will be displayed in all administration pages, be it the wiki administration or any page administration. 

Note that the old configureGlobally property is still supported in the code handling the ConfigurableClass so no migration is needed for this change.

Miscellaneous

• Document restoration events: It's now possible to be notified when a document is restored from the recycle bin using the events org.xwiki.bridge.event.DocumentRestoringEvent and org.xwiki.bridge.event.DocumentRestoredEvent. See Model Bridge API for more details.

• History delete event: It's now possible to be notified when a range of document history versions is about to be deleted using the event org.xwiki.bridge.event.DocumentVersionRangeDeletingEvent. See Model Bridge API for more details.

• NamespaceURLClassLoader#isClosed(): NamespaceURLClassLoader now exposes an API to know if it has been closed.

• Allow to recompute average ratings from script service: A new API methods has been added in Ratings script service to allow computing back the average ratings when needed.

  The signature of the method is the following:

      /**
       * Recompute the average rating of a reference.
       * Note that this method can be resource consuming if the set of data is large.
       *
       * @param reference the reference for which to recompute the average ratings.
       * @return the average rating in an optional or an empty optional in case of error.
       * @since 13.7RC1
       * @since 13.4.3
       * @since 12.10.9
       */
      @Unstable
      @Programming
     Optional<AverageRating> recomputeAverageRating(EntityReference reference)

• Allow to store Like average xobjects: Like implementation is based on Ratings, and until this version the configuration of Ratings we were using was hardcoded.

  We provide in this version 2 new properties that allow to store the average ratings xobjects related to the Like information: those xobjects can notably be used to perform HQL queries with the total number of likes in pages, since this data is stored in them.

  We only provide those properties as an experimental feature: it might be removed later, by providing a cleaner API for this usecase.

  The properties are the following:

  ## Specify if the average rating should be stored or not for likes. Default value is false.
  like.averagerating.isStored=true
  
  ## Specify where the average ratings should be stored. Default value is xobject. Possible values are currently solr or xobject.
  like.averagerating.hint=xobject

Upgrades

The following runtime dependencies have been upgraded (they have a different release cycle than XWiki Commons, XWiki Rendering and XWiki Platform):

• CKEditor Integration 1.55
• Tika 2.0
• Liquibase 4.4.3
• Hibernate 5.5.6
• Byte Buddy 1.11.12
• Checker Qual 3.17.0
• Commons CSV 1.9.0
• jstree 3.3.11
• Logback 1.2.5
• Infinispan 12.1.7
• common-compress 1.21
• SLF4J 1.7.32
• jsoup 1.14.2
• Maven 3.8.2
• MariaDB connector 2.7.4
• Netty 4.1.67.Final
• Commons Pool 2.11.1
• Commons DBCP2 2.9.0
• Error Prone annotations 2.8.1
• JAXB Runtime 2.3.5
• MySQL connector 8.0.26
• Commons IO 2.11.0

Translations

The following translations have been updated:

• French
• Russian

Tested Browsers & Databases

Here is the list of browsers we support and how they have been tested for this release:

	Browser	Tested on:
	Microsoft Edge 92	Not Tested
	Google Chrome 92	Jira Tickets Marked as Fixed in the Release Notes
	Internet Explorer 11	Tests run and results
	Mozilla Firefox 91
	Safari 14	Not Tested

Here is the list of databases we support and how they have been tested for this release:

	Database	Tested on:
	HyperSQL 2.5.2	Not Tested
	MariaDB 10.6	Tests run and results
	MySQL 8
	PostgreSQL 13	Jira Tickets Marked as Fixed in the Release Notes
	Oracle 19c	Not Tested

Here is the list of Servlet Containers we support and how they have been tested for this release:

	Servlet Container	Tested on:
	Tomcat 9.0.52	Jira Tickets Marked as Fixed in the Release Notes Tests run and results
	Jetty 9.4.29 (XWiki Standalone packaging)
	Jetty 9.4.29	Not Tested

Known issues

• Bugs we know about

Backward Compatibility and Migration Notes

General Notes

• When upgrading make sure you compare and merge the following XWiki configuration files since some parameters may have been modified, removed or added:
  • xwiki.cfg
  • xwiki.properties
  • web.xml
  • hibernate.cfg.xml
• Add xwiki.store.migration=1 in xwiki.cfg so that XWiki will attempt to automatically migrate your current database to any new schema. Make sure you backup your Database before doing anything.

API Breakages

The following APIs were modified since XWiki 13.6:

Unknown Criticality

These violationq are missing a criticality and need to be fixed.

• Unstable API: this API was not properly designed and shouldn't have returned that in first place.
  • Violation type:
    java.method.returnTypeChanged
  • Code:
    ## Old:
    method javax.mail.internet.InternetAddress org.xwiki.security.authentication.script.AuthenticationScriptService::requestResetPassword(org.xwiki.user.UserReference) throws org.xwiki.security.authentication.ResetPasswordException
    
    ## New:
    method void org.xwiki.security.authentication.script.AuthenticationScriptService::requestResetPassword(org.xwiki.user.UserReference) throws org.xwiki.security.authentication.ResetPasswordException
• Unstable API: this API was not properly designed and shouldn't have returned that in first place.
  • Violation type:
    java.method.removed
  • Code:
    ## Old:
    method javax.mail.internet.InternetAddress org.xwiki.security.authentication.ResetPasswordRequestResponse::getUserEmail()
• Not a breackage. Moved to legacy.
  • Violation type:
    java.method.removed
  • Code:
    ## Old:
    method java.lang.String com.xpn.xwiki.XWiki::invokeServletAndReturnAsString(java.lang.String, com.xpn.xwiki.XWikiContext)
• Not a breackage. Moved to legacy.
  • Violation type:
    java.method.removed
  • Code:
    ## Old:
    method java.lang.String com.xpn.xwiki.api.XWiki::invokeServletAndReturnAsString(java.lang.String)

Credits

The following people have contributed code and translations to this release (sorted alphabetically):

• Eduard Moraru
• Manuel Leduc
• Marius Dumitru Florea
• Simon Urli
• slauriere
• Teo Caras
• Thomas Mortagne
• urs19work
• Vincent Massol