Hide last authors
Thomas Mortagne 1.1 1 Handling of XAR packages as defined in [[specifications>>Extension.XAR Module Specifications]].
2
Thomas Mortagne 2.1 3 {{toc/}}
4
Thomas Mortagne 3.1 5 = Script service =
Thomas Mortagne 1.1 6
7 The XAR extension handler expose a ScriptService component for XAR extension specific features.
8
Thomas Mortagne 3.1 9 == XAR Repair ==
Thomas Mortagne 1.1 10
11 Sometimes you have pages coming from an extension in the database but lost the actual extension index. The most common use case is when upgrading from a pre extension manager version of XWiki.
12
13 To recreate index for those extension the script service provide ##Job repairInstalledExtension(String id, String version, String wiki)## API.
14
15 {{code language="java"}}
16 /**
17 * Make sure the provided XAR extension properly is registered in the installed extensions index.
18 * <p>
19 * Start an asynchronous Job.
20 *
21 * @param id the extension identifier
22 * @param version the extension version
23 * @param wiki the wiki where the extension is installed
24 * @return the {@link Job} object which can be used to monitor the progress of the installation process, or
25 * {@code null} in case of failure
26 */
27 public Job repairInstalledExtension(String id, String version, String wiki)
28 {{/code}}
29
Thomas Mortagne 3.1 30 == Extension Diff ==
Thomas Mortagne 1.1 31
32 [since 7.0]
33
34 It's possible to get a full diff between an extension and all its dependencies and what is actually in the database. For this you can use ##Job diff(String feature, String wiki)## method.
35
36 {{code language="java"}}
37 /**
38 * Computes the differences, in unified format, between the documents of an installed XAR extension and the document
39 * from the wiki.
40 *
41 * @param feature the identifier of a XAR extension (or one of its features)
42 * @param wiki the wiki where the XAR extension is installed
43 * @return the {@link Job} object which can be used to monitor the progress while the differences are being
44 * computed, or {@code null} in case of failure
45 * @since 7.0RC1
46 */
47 public Job diff(String feature, String wiki)
48
49 /**
50 * Get the id of the previously (or currently) computed differences, in unified format, between the documents of an
51 * installed XAR extension and the document from the wiki..
52 *
53 * @param feature the identifier of a XAR extension (or one of its features)
54 * @param namespace the namespace where the XAR extension is installed
55 * @return the id of the {@link Job}
56 * @since 9.3RC1
57 */
58 public List<String> getDiffJobId(String feature, String namespace)
59 {{/code}}
60
Thomas Mortagne 3.1 61 == Conflict handling ==
Thomas Mortagne 1.1 62
63 [since 9.2]
64
65 The script service allow getting all the possible types of conflict to can get when installing/upgrading an extension.
66
67 {{code language="java"}}
68 /**
69 * @return the possible conflicts
70 * @since 9.2RC1
71 */
72 public ConflictQuestion.ConflictType[] getConflictTypes()
73 {{/code}}
74
Thomas Mortagne 6.1 75 It's also possible to set the default answer (as one of the ##org.xwiki.extension.xar.question.GlobalAction## enum entries) for each kind of conflict in the ##InstalRequest## trough ##setProperty(String key, Object value)## method:
76
77 * ##extension.xar.packager.conflict.always.MERGE_SUCCESS##: 3 ways merge succeed
78 * ##extension.xar.packager.conflict.always.MERGE_FAILURE##: 3 ways merge failed
79 * ##extension.xar.packager.conflict.always.CURRENT_EXIST##: Already existing different document in database but not in previous version of upgraded/uninstalled extension
80 * ##extension.xar.packager.conflict.always.CURRENT_DELETED##: Document already deleted in the database
81
Thomas Mortagne 3.1 82 == Document to extension ==
Thomas Mortagne 1.1 83
84 [since 9.3]
85
86 The script service provide a set of API to link document to the installed extension where they originated from.
87
88 It's possible to:
Thomas Mortagne 3.1 89
Thomas Mortagne 1.1 90 * get extensions associated to a specific document reference
91 * it's possible to get a ##com.xpn.xwiki.api.Document## instance of a document coming from a XAR package
92 * reset a document to it's standard (as in what it looks like in the XAR package) version
93
94 {{code language="java"}}
95 /**
96 * @param reference the reference of the document to reset to its standard state (what it looks like in the
97 * extension XAR)
98 * @param extensionId the installed extension from which to get the standard version of the document
99 * @param jobId the id of the job which computed the diff if any
100 * @return true if the reset actually did something, false otherwise (any produced error can be accessed using
101 * {@link #getLastError()})
102 * @since 9.3RC1
103 */
104 public boolean reset(DocumentReference reference, ExtensionId extensionId, List<String> jobId)
105
106 /**
107 * @param reference the reference of the document to reset to its standard state (what it looks like in the
108 * extension XAR)
109 * @param jobId the id of the job which computed the diff if any
110 * @return true if the reset actually did something, false otherwise (any produced error can be accessed using
111 * {@link #getLastError()})
112 * @since 9.3RC1
113 */
114 public boolean reset(DocumentReference reference, List<String> jobId)
115
116 /**
117 * @param reference the reference of the document
118 * @return the installed XAR extensions in which this document can be found
119 * @since 9.3RC1
120 */
121 public Collection<InstalledExtension> getInstalledExtensions(DocumentReference reference)
122
123 /**
124 * @param reference the reference of the document
125 * @return a Document instance of passed document when extracted from the standard extension matching this
126 * reference. Null if none could be found.
127 * @throws XarExtensionExtension when failing to get the document
128 * @since 9.3RC1
129 */
130 public Document getInstalledExtensionDocument(DocumentReference reference) throws XarExtensionExtension
131 {{/code}}
Thomas Mortagne 3.1 132
Thomas Mortagne 4.1 133 = Extension pages protection =
134
135 Since 10.4 extension pages are protected against edition and deletion. A warning is shown and you need to force edit or force delete for those protected pages. However it's possible for extension author to indicate pages which don't need protection (pages meant to be customized, configuration, etc.), see [[http://dev.xwiki.org/xwiki/bin/view/Community/XARPlugin#HDocumentstypes]] and [[http://extensions.xwiki.org/xwiki/bin/view/Extension/XAR+Module+Specifications#Hpackage.xml]] for details.
136
137 Since 10.5 several protection systems are provided and can be selected in ##xwiki.properties## file using the property ##extension.xar.protection##:
138
Thomas Mortagne 5.1 139 * ##none##: no protection at all
140 * ##warning## {{info}}default{{/info}}: everyone get a warning when trying to edit a protected document
141 * ##deny## = EDIT/DELETE right is denied for everyone except for admins who just get a warning
142 * ##forcedDeny## = EDIT/DELETE right is denied for everyone, admins can't force edit/delete
143 * ##denySimple## = EDIT/DELETE right is denied for simple users except for simple admins who just get a warning
144 * ##forcedDenySimple## = EDIT/DELETE right is denied for all simple users, simple admins can't force edit/delete
Thomas Mortagne 4.1 145
Thomas Mortagne 8.1 146 = Standard types
147
148 * ##default##: used to force the default. Edit and delete are not allowed and a 3-way merge is applied to the document during upgrades.
149 * ##configuration##: a document containing configuration. Edit is allowed and the document is never upgraded.
150 * ##demo##: a document which purpose is to provide demo data. Edit and delete are allowed and the document is upgraded only if it's not been customized.
151 * ##customizable##: a document meant to be modified but not deleted. Edit is allowed and the document is upgraded only if it's not been customized.
152
153 Also the following document references have a different default type:
154 * ##XWiki.XWikiPreference##: ##configuration##
155 * ##Main.WebHome##: ##demo##
156
157 = Provide custom entry types =
158
159 XWiki comes with standard XAR entry types but it's possible to extend this list with your own by implementing the component role ##org.xwiki.xar.XarEntryType##.
160
161 Each XarEntryType component can indicate:
162 * if edit is allowed for this type of document
163 * if delete is allwoed for this type of document
164 * the generic list of possible behavior to apply during an upgrade
165
166 Appart from an arbitrary entry type name (like "configuration" or "demo") a XarEntryType can be associated to a document reference in which case documents with this reference will be assigned this type unless a type was explicitly associated to it in the XAR extension:
167
168 {{code language="java"}}
169 @Component(hints = { MyXarEntryType.HINT, XarEntryTypeResolver.DOCUMENT_PREFIX + "MySpace.MyPage" })
170 @Singleton
171 public class MyXarEntryType extends AbstractXarEntryType
172 {
173 /**
174 * The name of the type.
175 */
176 public static final String HINT = "mytype";
177
178 /**
179 * Default constructor.
180 */
181 public MyXarEntryType()
182 {
183 super(HINT);
184
185 // This kind of document should not be modified
186 setEditAllowed(false);
187 // Deleting this kind of document is fine
188 setDeleteAllowed(true);
189
190 // Don't upgrade the configuration even if the default configuration changed
191 setUpgradeType(UpgradeType.SKIP_ALLWAYS);
192 }
193 }
194 {{/code}}
195
Thomas Mortagne 3.1 196 = Customize upgrade behavior =
197
Thomas Mortagne 4.1 198 10.3 introduced XAR entry types to customize install/upgrade behavior but XAR Extension also provide an extension point for more complex use cases: ##org.xwiki.extension.xar.XWikiDocumentMerger##.
Thomas Mortagne 3.1 199
Thomas Mortagne 4.1 200 You can implement this role with one of the following hint:
201
Thomas Mortagne 3.1 202 * the XAR entry type name ("home", "configuration", etc) to customize the behavior of this type of XAR entry
203 * or the reference with ##document:## prefix (for example ##document:XWiki.XWikiPreferences##) to customize the behavior of this specific document
204
205 The method ##merge## will will called every time a document need to be installed/upgraded the the 3 versions of the document (previous standard version, current version in the database, new standard version) and the XWikiDocumentMergerConfiguration which provide information about the type, conflict resolution, etc.

Get Connected