Wiki source code of XAR Script Service
Last modified by Eleni Cojocariu on 2026/08/21 19:17
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The ##xar## Script Service exposes the [[XAR API>>documentation.xs.dev.xar.WebHome]] to wiki pages as ##$services.xar##. It never throws: a call that fails returns ##null## and stores its exception, which ##getLastError()## then returns. | ||
| 2 | |||
| 3 | |=Method|=Returns|=Description | ||
| 4 | |##getXarPackage(file)##|##XarPackage##|The archive read from a ##java.io.File##. | ||
| 5 | |##getXarPackage(stream, close)##|##XarPackage##|The archive read from an ##InputStream##, which is the form a script uses because an [[attachment>>doc:documentation.xs.user.base.page.view.attachments-tab.WebHome]] provides one. ##close## says whether that stream is closed once the archive has been read. | ||
| 6 | |##getLastError()##|##Exception##|The exception thrown by the previous call, or ##null## when it succeeded. | ||
| 7 | |##isXARExportAvailable()##|##boolean##|Whether the instance can [[export in XAR format>>doc:documentation.xs.admin.exports.export-content-xar-format.WebHome]] at all. | ||
| 8 | |||
| 9 | == Package == | ||
| 10 | |||
| 11 | The ##XarPackage## returned by ##getXarPackage## holds the [[package information>>doc:documentation.xs.admin.exports.export-content-xar-format.format-specifications.WebHome||anchor="HPackageInformation"]] of the descriptor and one entry per Page file. | ||
| 12 | |||
| 13 | |=Property|=Returns|=Description | ||
| 14 | |##entries##|##Collection<XarEntry>##|One entry per Page file found in the archive. | ||
| 15 | |##packageFiles##|##Collection<XarEntry>##|The entries the descriptor lists, which is the same set unless the archive and its descriptor disagree. | ||
| 16 | |##packageName##|##String##|The ##name## element of the descriptor. | ||
| 17 | |##packageDescription##|##String##|Its ##description## element. | ||
| 18 | |##packageLicense##|##String##|Its ##licence## element. | ||
| 19 | |##packageAuthor##|##String##|Its ##author## element. | ||
| 20 | |##packageVersion##|##String##|Its ##version## element. | ||
| 21 | |##packageBackupPack##|##boolean##|Whether the archive is marked as a backup package. | ||
| 22 | |##packagePreserveVersion##|##boolean##|Whether the Page files are meant to carry their history. | ||
| 23 | |##packageExtensionId##|##String##|The Extension the archive holds, ##null## when it holds none. | ||
| 24 | |##getEntry(reference)##|##XarEntry##|The entry of one Page, by its ##LocalDocumentReference##. | ||
| 25 | |||
| 26 | == Entry == | ||
| 27 | |||
| 28 | 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##. | ||
| 29 | |||
| 30 | |=Property|=Returns|=Description | ||
| 31 | |##documentName##|##String##|The name of the Page. | ||
| 32 | |##locale##|##Locale##|The locale of the Page file, empty for the default one. | ||
| 33 | |##entryName##|##String##|The path of the file inside the archive, as in ##Sandbox/TestPage2.xml##. | ||
| 34 | |##entryType##|##String##|The [[entry type>>doc:documentation.xs.admin.exports.export-content-xar-format.format-specifications.WebHome||anchor="HFiles"]], ##null## when the entry has none. | ||
| 35 | |##spaceName##|##String##|Deprecated, and meaningless for a nested Page: the space of the Page. | ||
| 36 | |##defaultAction##|##int##|Deprecated: the ##defaultAction## attribute of the entry. | ||
| 37 | |||
| 38 | == Examples == | ||
| 39 | |||
| 40 | List the Pages of an archive attached to the current Page: | ||
| 41 | |||
| 42 | {{code language="velocity"}} | ||
| 43 | {{velocity}} | ||
| 44 | #set ($xar = $services.xar.getXarPackage($doc.getAttachment('backup.xar').contentInputStream, true)) | ||
| 45 | #foreach ($entry in $xar.entries) | ||
| 46 | * $services.model.serialize($entry, 'local') ($entry.entryName) | ||
| 47 | #end | ||
| 48 | {{/velocity}} | ||
| 49 | {{/code}} | ||
| 50 | |||
| 51 | Show the package information of that archive, telling a read that failed from a file that is not an archive at all: | ||
| 52 | |||
| 53 | {{code language="velocity"}} | ||
| 54 | {{velocity}} | ||
| 55 | #set ($xar = $services.xar.getXarPackage($doc.getAttachment('backup.xar').contentInputStream, true)) | ||
| 56 | #if (!$xar) | ||
| 57 | Reading the archive failed: $services.xar.lastError.message | ||
| 58 | #elseif ($xar.entries.isEmpty()) | ||
| 59 | The attachment holds no Page, so it is not a XAR archive. | ||
| 60 | #else | ||
| 61 | **$xar.packageName** by $xar.packageAuthor, version $xar.packageVersion, $xar.entries.size() Page(s). | ||
| 62 | #end | ||
| 63 | {{/velocity}} | ||
| 64 | {{/code}} |
