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

This release is mainly focused on the Flamingo skin and it being now used by default, but also features improvements for applications such as AWM and Blog and various performance improvements. Developers can benefit from new APIs such as the new Mail Sender API and the new Blame API but also from improved APIs such as the wiki module API and JS widgets.

New and Noteworthy (since XWiki 6.1)

Full list of issues fixed and Dashboard for 6.2.

Flamingo

• Flamingo is the new default skin in XWiki!
• The applications panel (also known as the "Applications Bar") has been set by default on the left panel.
• The default icon theme is now Font Awesome.
• A new application has been made to manage color themes on Flamingo. It does not only permit to change colors anymore, but also the typography, etc... That is why it is called Flamingo Theme Application.
  
• By default, a new theme is enabled: FlamingoDefaultTheme, made with the new application described above.
• Colibri Skin can use the themes from Flamingo thanks to a mapping between Flamingo Theme Application and Color Theme Application. The results may not be perfect though.
• Improved Login form

  

• The page headers from Colibri ColorThemes can be displayed for Flamingo skin by setting the $displayPageHeader to true in layoutExtraVars.vm. By default this variable is set to false

    

• You can control whether or not you want to display the create and the "more actions" menus with 2 new variables: $displayCreateMenu and $displayMoreActionsMenu. You can manually set them in the layoutExtraVars.vm file.
  • The textarea now use a monospace font.
  • The user profile looks better on smartphones:

      

  You can see the results of all this changes in the following screenshot:
  

Icon Theme Application

A new application is now bundled in XWiki: Icon Theme Application. Its purpose is to let the user chose which icon set she would like to have in her wiki.

This application is compatible with icon stored as images but also with font icons such as FontAwesome!

Font Awesome

Font Awesome is our first alternative to silk as an Icon Theme. It is now bundled in XWiki, but the Icon Theme mapping is still at a beta state.

Initialization screen improvements

If XWiki initialization failed you get a detailed log and it stop refreshing the page.

Application Bar

• The icons are now bigger.
• The icons displayed in the application bar use the new Icon Theme Application, in order to let the user choose the icon set she wants to see:
  
  
• On devices with small screen, when panels are displayed under the page content (currently, it is the case for Flamingo only), the appbar is now displayed differently to use all the available width:
  
  

Blog Application

The blog panels are now displayed on the right column by default, to fit Flamingo:

New structure for apps created with App Within Minutes

When you create a new application using AWM, your application will be structured into 2 spaces (one for data and the other for code). For more details, see AWM's documentation.

Miscellaneous

• The RTF export is now only supported when an Office Server is connected to XWiki (we used to default to using FOP when no Office Server is connected but the quality of the export was too low to consider this a viable solution).
• When using the Standalone distribution, the format has changed when passing parameters. The shell used has also been changed from sh to bash The new format is:

  start_xwiki.sh:

  # ----------------------------------------------------------------------------------------------------------------
  # Optional ENV vars
  # -----------------
  #   XWIKI_OPTS - parameters passed to the Java VM when running XWiki e.g. to increase the memory allocated to the
  #       JVM to 1GB, use set XWIKI_OPTS=-Xmx1024m
  #   JETTY_PORT - the port on which to start Jetty.
  #   JETTY_STOP_PORT - the port on which Jetty listens for a Stop command.
  #
  # Optional Parameters
  # -------------------
  #   -p, --port: The Jetty HTTP port to use. Overrides any value from JETTY_PORT. Defaults to 8080.
  #   -sp, --stopport: The Jetty stop port to use. Overrides any value from JETTY_STOP_PORT. Defaults to 8079.
  #   -ld, --lockdir: The directory where the executing process id is stored to verify that that only one instance is
  #       started. Defaults to /var/tmp.
  #   -k, --kill: If set then kills any already executing XWiki instance before starting a new one.
  #
  # Example
  # -------
  #   start_xwiki.sh -p 8080 -sp 8079 -k
  # ----------------------------------------------------------------------------------------------------------------

  start_xwiki_debug.sh:

  # ----------------------------------------------------------------------------------------------------------------
  # Optional ENV vars
  # -----------------
  #   XWIKI_OPTS - parameters passed to the Java VM when running XWiki e.g. to increase the memory allocated to the
  #       JVM to 1GB, use set XWIKI_OPTS=-Xmx1024m
  #   JETTY_PORT - the port on which to start Jetty.
  #   JETTY_STOP_PORT - the port on which Jetty listens for a Stop command.
  #
  # Optional Parameters
  # -------------------
  #   -p, --port: The Jetty HTTP port to use. Overrides any value from JETTY_PORT. Defaults to 8080.
  #   -sp, --stopport: The Jetty stop port to use. Overrides any value from JETTY_STOP_PORT. Defaults to 8079.
  #   -ld, --lockdir: The directory where the executing process id is stored to verify that that only one instance is
  #       started. Defaults to /var/tmp.
  #   -k, --kill: If set then kills any already executing XWiki instance before starting a new one.
  #   -yp, --yourkitpath: The path where Yourkit can find the agent. If not passed then YourKit won't be enabled.
  #       For example: "/Applications/YourKit Java Profiler 7.0.11.app/bin/mac"
  #       or "/home/User/yjp-11.0.8/bin/linux-x86-64/"
  #
  # Example
  # -------
  #   start_xwiki_debug.sh -yp "/Applications/YourKit Java Profiler 7.0.11.app/bin/mac"
  # ----------------------------------------------------------------------------------------------------------------

  stop_xwiki.sh:

  # ----------------------------------------------------------------------------------------------------------------
  # Optional ENV vars
  # -----------------
  #   XWIKI_OPTS - parameters passed to the Java VM when running XWiki e.g. to increase the memory allocated to the
  #       JVM to 1GB, use set XWIKI_OPTS=-Xmx1024m
  #   JETTY_STOP_PORT - the port on which Jetty listens for a Stop command.
  #
  # Optional Parameters
  # -------------------
  #   -p, --port: The Jetty HTTP port that was used to start XWiki. Defaults to 8080.
  #   -sp, --stopport: The Jetty stop port to use. Overrides any value from JETTY_STOP_PORT. Defaults to 8079.
  #   -ld, --lockdir: The directory where the executing process id is stored to verify that that only one instance is
  #       started. Defaults to /var/tmp.
  #
  # Example
  # -------
  #   stop_xwiki.sh -sp 8079
  # ----------------------------------------------------------------------------------------------------------------
• When using the standalone package, the logs can also be found in files under data/logs/.
• The jetty configuration is now split in several files, making it easier to configure the needed parts.
• There's a sample configuration file for enabling HTTPS for the standalone Jetty server.
• The port on which Jetty listens for request can be configured using the JETTY_PORT environment variables; JETTY_STOP_PORT can be used to configure the port where stop commands are expected.
• Jetty's messages are now more informative: internal information isn't displayed, while notifications for the users are printed both at startup and shutdown.
• Single line fields in documents are not merged at character level anymore. This might increase a bit the number of potential conflicts but at the same time improve the suggestion in most cases in case of real conflict since most of the time this kind of field cannot really be merged.
• The XWiki Snapshots maven extensions repository is now used by default (when no other repositories are configured) on snapshot/development builds of XWiki Enterprise in order to make the testing of snapshot builds easier and faster.
• ModalPopup and LightBox resource components are now responsive. For small resolutions their width will occupy the whole screen.

    

• Deleted document translations can now be restored, even if the main document or a different translation has already been restored (as long as no conflict exists). See XWIKI-9567 and the documentation.
• The Font Awesome Icon Theme has been improved with 50 new icons.
• In Flamingo, the form of the login page has been changed to navigate easily using the keyboard.
• Annotations initialization speedup
• Wiki macros initialization speedup

See the full list of JIRA issues fixed in this release.

For Developers

Wiki module improvements

• Added an API to directly get the wiki identifiers:
  • From Velocity:
    #set($wikiIds = $services.wiki.allIds)
  • From Java:
    Collection<String> wikiIds = wikiDescriptorManager.getAllIds();

The XWiki.widgets.ConfirmationBox widget can display a Cancel button

By passing the showCancelButton : true option in the interactionParameters argument to the constructor, a Cancel button will be displayed next to the Yes and No ones. The label of the button can be specified with the cancelButtonText interaction option, and an optional callback to execute with the onCancel behavior option.

The XWiki.widgets.ModalPopup#createButton method now accepts an extraClass parameter

The fifth parameter can be used to add additional classes, besides the standard button, to the created buttons.

WikiStream module renamed to Filter module

The heart of WikiStream being far more generic than wikis, most of it have been moved to commons in the already existing Filter module.

Most of WikiStream module moved to commons filter module (everything that wasn't really depending on any platform project) and it also been renamed to Filter on platform side to follow commons naming. The structure of the API did not changed a bit except for the naming. In short every "WikiStream" in your code should be changed to Filter or FilterStream. None of the existing streams identifiers changed except for the generic XML streams which is is now filter+xml (instead of wiki+xml). 

Mail Sender API

• The new Mail Sender API is now bundled by default in XWiki Enterprise. 
• It's now possible to access the Mail Sending API configuration from scripts by calling $services.mailsender.configuration.
• The send() API now sends messages synchronously and a new sendAsynchronously() API has been added
• Using the following will now automatically add a template body part too:
  #set ($message = $services.mailsender.createMessage('template', $templateReference, $mailParameters) 
• In addition the "template" Mime Message Factory supports passing "to", "from", "cc" and "bcc" addresses in the parameters list, for example:
  #set ($mailParameters = {'from' : 'localhost@xwiki.org', 'to' : 'john@doe.com', 'language' : $xcontext.language, 'velocityVariables' : { 'var1' : 'value1' }})
  #set ($message = $services.mailsender.createMessage('template', $templateReference, $mailParameters) 

Building XWiki is now possible using Maven 3.1 and 3.2

The packager Maven plugin was using temporary APIs used only in Maven 3.0, which made it impossible to build modules depending on that plugin with other versions of Maven than 3.0.x. This has now been fixed, and the build works with any 3.x Maven version.

Blame generic API and Script Service

Provides the implementation of the blame/annotate/praise algorithm.

Like the diff module API, this API is not tied to any type so you have to first transform the datas you want to blame into lists and you will be able to link them with any kind of revision metadata. Blame will link each elements of the initial list with the revision metadata of the original revision it came from. You will have to call blame in loop with each revised list, starting from the most recent one, until all element are annotated.

See Blame Module for more information.

Upgrades

The following dependencies have been upgraded:

• Bootstrap 3.2.0
• HTML5Shiv 3.7.2
• Jetty 8.1.15
• JFreechart 1.0.19
• Joda-Time 2.4
• xalan 2.7.2
• Groovy 2.3.6
• Velocity Tools 2.0
• Jython 2.7-b3
• httpclient 4.3.5
• Guava 18.0
• Apache FOP 1.1
• Maven 3.2.3
• JGroups 3.4.5
• HTMLCleaner 2.9
• Font Awesome 4.2.0

Miscellaneous

• The auto value has been added to the align option of the Auto Suggest Widget.
• A new parameter targetQueryString has been added to the UI Extension points org.xwiki.platform.panels.Applications and org.xwiki.platform.panels.Applications.more.
• New com.xpn.xwiki.api.Collection#getValue(String name). That means you can write directly $myobject.getValue('fieldname') instead of $myobject.getProperty('fieldname').value. Who knows, maybe we will get a bit less missuses of  com.xpn.xwiki.api.Object#get(String name).
• New org.xwiki.text.StringUtils which extends org.apache.commons.lang3.StringUtils with new useful methods. See http://extensions.xwiki.org/xwiki/bin/view/Extension/Text+Module#HFeatures.
• The user of an Activity Stream event is now always stored as an absolute serialized reference. See XWIKI-9066 for more details.
• A new user and group references related reference resolver have been provided:
  @Inject
  @Named("user/current")
  private DocumentReferenceResolver<String> currentUserDocumentResolver;
  
  @Inject
  @Named("user/current")
  private EntityReferenceResolver<String> currentUserEntityResolver;
  
  @Inject
  @Named("user")
  private EntityReferenceResolver<String> defaultUserEntityResolver;
• Each XWiki class property can now control how it's merged. Just need to overwrite com.xpn.xwiki.objects.classes.PropertyClass#mergeProperty method.
• The target syntax is now part of the Rendering Context when the Rendering is used to render some Blocks (otherwise it's null. For example when parsing content).
• Added new org.xwiki.rendering.renderer.printer.WriterWikiPrinter to output all calls to org.xwiki.rendering.renderer.printer.WikiPrinter into a org.xwiki.rendering.renderer.printer.Writer
• Added the new component org.xwiki.skinx.internal.LinkSkinExtension (with the hint "linkx") that wraps the $xwiki.linkx plugin
• New $cookietool available for working with cookies in Velocity. See XCOMMONS-627
• New $doc.isTranslation() method is available in the web API. See XWIKI-10805
• xwiki-platform-font-awesome has been moved in the xwiki-platform-icon module and renamed xwiki-platform-icon-fontawesome.
• Icon Theme can now use JavaScript Extensions.
• The Icon class of the Icon Theme does not store the name of the icon anymore, since it is already stored in a map in the IconSet class (better memory usage).
• It is now possible to compile a LESS file or to compute a color theme from an other skin.
• xwiki-platform-less-css has been renamed xwiki-platform-lesscss in order to be consistent with our naming conventions.
• new API to flush rendering cache. See Performances.

Translations

The following translations have been updated: 

• Danish
• German
• French
• Latvian
• Polish
• Russian
• Swedish
• Simplified Chinese

Tested Browsers & Databases

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

	Browser	Test Result
	Google Chrome 37	Smoke testing
	Mozilla Firefox 32	Jira Tickets Marked as Fixed in the Release Notes, Full testing
	Internet Explorer 8	Not Tested
	Internet Explorer 9	Not Tested

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

	Database	Test Result
	HyperSQL 2.3.2	Jira Tickets Marked as Fixed in the Release Notes, Full testing
	MySQL 5.6.17	Not Tested
	Oracle 11.2	Not Tested
	PostgreSQL 9.3.4	Not Tested

Performances tests compared to 5.4.5

6.2 is generally slower than 5.4.5 except macro rendering which gets a big improvement and it uses a bit less memory. The big slow down on initialization is when compiling Flamingo less files. There's still work to do, however a lot of the losses accumulated during 6.0 and 6.1 have been regained (see some partial results on Jetty HSQLDB single wiki).

Summary

Speed

Heap Memory

More details on performance comparison on single wiki between 6.2 and 5.4.5.

Known issues

• Bugs we know about

Backward Compatibility and Migration Notes

General Notes

When upgrading make sure you compare your xwiki.cfg, xwiki.properties and web.xml files with the newest version since some configuration parameters may have been modified or added. Note that you should add xwiki.store.migration=1 so that XWiki will attempt to automatically migrate your current database to the new schema. Make sure you backup your Database before doing anything.

API Breakages

The following APIs were modified since XWiki 6.1:

• Young APIs:
  org.xwiki.rendering.transformation.RenderingContext: Method 'public org.xwiki.rendering.syntax.Syntax getTargetSyntax()' has been added to an interface

  • Added an API for a very common use case so that we optimize it

  org.xwiki.wiki.descriptor.WikiDescriptorManager: Method 'public java.util.Collection getAllIds()' has been added to an interface

  org.xwiki.mail.MailSender: Method 'public void send(javax.mail.internet.MimeMessage, javax.mail.Session, org.xwiki.mail.MailResultListener)' has been removed
  org.xwiki.mail.MailSender: Method 'public void sendAsynchronously(javax.mail.internet.MimeMessage, javax.mail.Session, org.xwiki.mail.MailResultListener)' has been added to an interface
  org.xwiki.mail.MailResultListener: Parameter 2 of 'public void onError(javax.mail.internet.MimeMessage, java.lang.Throwable)' has changed its type to java.lang.Exception
  org.xwiki.mail.script.MimeMessageWrapper: Parameter 1 of 'public MimeMessageWrapper(javax.mail.internet.MimeMessage, javax.mail.Session, org.xwiki.mail.MailSender, org.xwiki.context.Execution, org.xwiki.component.manager.ComponentManager)' has changed its type to org.xwiki.mail.internal.ExtendedMimeMessage
  org.xwiki.mail.script.MimeMessageWrapper: Return type of method 'public javax.mail.internet.MimeMessage getMessage()' has been changed to org.xwiki.mail.internal.ExtendedMimeMessage

• The extended class got moved to a new package with the upgrade to velocity-tools 2.0 and the old location got deprecated.
  org.xwiki.velocity.XWikiWebappResourceLoader: Removed org.apache.velocity.tools.view.servlet.WebappLoader from the list of superclasses

• Not really APIs to begin with.
  com.xpn.xwiki.doc.XWikiDocument: Removed field compactEntityReferenceSerializer
  com.xpn.xwiki.doc.XWikiDocument: Removed field compactWikiEntityReferenceSerializer
  com.xpn.xwiki.doc.XWikiDocument: Removed field currentDocumentReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field currentMixedDocumentReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field currentReferenceDocumentReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field currentReferenceObjectReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field defaultEntityReferenceSerializer
  com.xpn.xwiki.doc.XWikiDocument: Removed field explicitDocumentReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field explicitReferenceDocumentReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field localEntityReferenceSerializer
  com.xpn.xwiki.doc.XWikiDocument: Removed field localUidStringEntityReferenceSerializer
  com.xpn.xwiki.doc.XWikiDocument: Removed field relativeEntityReferenceResolver
  com.xpn.xwiki.doc.XWikiDocument: Removed field syntaxFactory
  com.xpn.xwiki.doc.XWikiDocument: Removed field uidStringEntityReferenceSerializer
  com.xpn.xwiki.doc.XWikiDocument: Removed field xClassEntityReferenceResolver

• The annotation API already needs a larger refactoring, this small fix stay in line with the existing API and does not deserve the creation of a new (temporary) API.
  org.xwiki.annotation.io.IOTargetService: Method 'public org.xwiki.rendering.block.XDOM getXDOM(java.lang.String)' has been added to an interface
  org.xwiki.annotation.io.IOTargetService: Method 'public org.xwiki.rendering.block.XDOM getXDOM(java.lang.String, java.lang.String)' has been added to an interface