XAR Script Service
Reference
The xar Script Service exposes the XAR API to wiki pages as $services.xar. It never throws: a call that fails returns null and stores its exception, which getLastError() then returns.
| Method | Returns | Description |
|---|---|---|
| getXarPackage(file) | XarPackage | The archive read from a java.io.File. |
| getXarPackage(stream, close) | XarPackage | The archive read from an InputStream, which is the form a script uses because an attachment provides one. close says whether that stream is closed once the archive has been read. |
| getLastError() | Exception | The exception thrown by the previous call, or null when it succeeded. |
| isXARExportAvailable() | boolean | Whether the instance can export in XAR format at all. |
Package
The XarPackage returned by getXarPackage holds the package information of the descriptor and one entry per Page file.
| Property | Returns | Description |
|---|---|---|
| entries | Collection<XarEntry> | One entry per Page file found in the archive. |
| packageFiles | Collection<XarEntry> | The entries the descriptor lists, which is the same set unless the archive and its descriptor disagree. |
| packageName | String | The name element of the descriptor. |
| packageDescription | String | Its description element. |
| packageLicense | String | Its licence element. |
| packageAuthor | String | Its author element. |
| packageVersion | String | Its version element. |
| packageBackupPack | boolean | Whether the archive is marked as a backup package. |
| packagePreserveVersion | boolean | Whether the Page files are meant to carry their history. |
| packageExtensionId | String | The Extension the archive holds, null when it holds none. |
| getEntry(reference) | XarEntry | The entry of one Page, by its LocalDocumentReference. |
Entry
A XarEntry is a LocalDocumentReference, so it can be passed anywhere a Page reference is expected, and $services.model.serialize($entry, 'local') turns it into Sandbox.TestPage2.
| Property | Returns | Description |
|---|---|---|
| documentName | String | The name of the Page. |
| locale | Locale | The locale of the Page file, empty for the default one. |
| entryName | String | The path of the file inside the archive, as in Sandbox/TestPage2.xml. |
| entryType | String | The entry type, null when the entry has none. |
| spaceName | String | Deprecated, and meaningless for a nested Page: the space of the Page. |
| defaultAction | int | Deprecated: the defaultAction attribute of the entry. |
Examples
List the Pages of an archive attached to the current Page:
{{velocity}}
#set ($xar = $services.xar.getXarPackage($doc.getAttachment('backup.xar').contentInputStream, true))
#foreach ($entry in $xar.entries)
* $services.model.serialize($entry, 'local') ($entry.entryName)
#end
{{/velocity}}Show the package information of that archive, telling a read that failed from a file that is not an archive at all:
{{velocity}}
#set ($xar = $services.xar.getXarPackage($doc.getAttachment('backup.xar').contentInputStream, true))
#if (!$xar)
Reading the archive failed: $services.xar.lastError.message
#elseif ($xar.entries.isEmpty())
The attachment holds no Page, so it is not a XAR archive.
#else
**$xar.packageName** by $xar.packageAuthor, version $xar.packageVersion, $xar.entries.size() Page(s).
#end
{{/velocity}}FAQ
Why does reading a file that is not an archive report no error?
Because a file with no ZIP entries is read as an archive holding no Page: the call succeeds and getLastError() stays null, so it is entries that has to be checked.
Does the Script Service check any right?
No, it only reads the archive and never touches the wiki, so the right to run a script in the Page is the only requirement.
