• AsyncContext component
• Async Script Service
• Context entries
  • Standard context entries
  • Custom context entries
• Caching
  • Resource which are automatically "used"
  • Force refresh

Since 10.10 XWiki provide various tools to make easier to execute part of the UI asynchronously.

Support for asynchronous execution is integrated in:

• Pages (for the execution of the content)
• Panels
• UI extensions
• Wiki macros
• Templates

There are also two public entry points to manipulate contextual information related to the asynchronous rendering:

AsyncContext component

• is/setEnabled: indicate if asynchronous rendering is allowed in the current context (for example it's disabled when doing HTML export)
• use* methods: indicate what kind of elements is used in the current context so that it's registered with the cached rendering to know when to invalidate it (for example XWiki#getDocument register the loaded document so that the cached content which needed to load that document is automatically invalidate when the document is modified in any way)

Async Script Service

The async script service expose the AsyncContext API and also add the following:

• flushCache: remove from the cache all the result of asynchronous rendering

Context entries

Standard context entries

• user: the reference of the current user ($xcontext.userReference), fallback on the author when not set
• author: the reference of the author of the currently executed script (XWikiContext#getAuthorReference), superadmin if not set
• doc.reference: the reference of the current document ($doc.documentReference), the wiki home page if not set. XWiki 12.9+ the context document is also automatically associated with the cached result and invalidated when the document is modified. XWiki 12.10+ the wiki of the document is used to set the context wiki and it's not saved.
• wiki: the identifier of the current wiki ($xcontext.database)
• secureDocument: XWiki 10.11.11+, 11.0+ the reference of the current secure document (which contains the current author)
• request.url: the URL received by XWiki
• request.parameters: the parameters received by XWiki ($request.parameterMap)
• request.base: the first part of the URL (<protocol>:<host:<port>) received by XWiki. Also imply request.contextpath.
• request.contextpath: XWiki 10.11.11+, 11.0+ the part following the base URL (usually xwiki unless the configuration has been changed)
• request.wiki: the wiki corresponding to the URL received by XWiki (could be different from the current wiki when the async execution is triggered).
• request.*: XWiki 12.10+ all the above request related data
• locale: the current locale
• action: XWiki 12.10+ the current action
• icon.theme: the current icon theme
• rendering.defaultsyntax: XWiki 11.8+ the value of org.xwiki.rendering.transformation.RenderingContext#getTargetSyntax
• rendering.targetsyntax: XWiki 11.8+ the value of org.xwiki.rendering.transformation.RenderingContext#getDefaultSyntax
• rendering.restricted: XWiki 13.10.11+, 14.4.8+, 14.10.3+, 15.0-rc-1+ the value of org.xwiki.rendering.transformation.RenderingContext#isRestricted

Custom context entries

Any extension can provide its own context elements. For this you will need to provide a component implementing the role org.xwiki.context.concurrent.ContextStore and have any unique role hint:

• getSupportedEntries: the names of the context entries supported by the ContextStore
• save: save only the passed context entries in the passed map
• restore: inject in the current context data found in the passed map

You can provide display names for these properties in the form of translations of the form rendering.async.context.entry.<key>.

For example:

Caching

When you enable cache the result of the execution will be stored in a memory cache and automatically invalidated when an event related to one of the associated resources (document, components, etc.) is received.

XWiki is doing its best to automatically associate many things but sometimes it's not easy to do it automatically (for example when you use database requests) and you will need to be a bit more explicit. For this you can use the various "use" API described in previous sections.

Resource which are automatically "used"

You won't need to call #use API for the following elements:

• anything that end up calling XWiki#getDocument will automatically cause the document reference to be associated
• any lookup for a component or a component list will automatically be associated
• since 11.8 any security right check is associated
• since 12.9 the context document when provided in the async context configuration

Force refresh

since 11.8 It's possible to force skipping the cache by sending the HTTP header Cache-Control with value "no-cache". Fortunately this is something the browser does when you force refresh (SHIFT+F5 or CTRL+SHIFT+R usually) so using forcing refresh in your browser will not only affect the browser cache but also the async rendering server side cache.