Skip to Content

Version 5.1 by Marius Dumitru Florea on 2011/03/29
Show last authors
1 {{velocity}}
2 $xwiki.ssx.use("ReleaseNotesXWikiEnterprise30M3")
3 {{/velocity}}
4
5 {{box cssClass="floatinginfobox" title="**Contents**"}}
6 {{toc/}}
7 {{/box}}
8
9 = New and Noteworthy (since XWiki Enterprise 2.7) =
10
11 {{todo}}todo{{/todo}}
12
13 == Miscellaneous ==
14
15 {{todo}}todo{{/todo}}
16
17 == Translations ==
18
19 * The following translations have been updated: {{todo}}todo{{/todo}}
20
21 = Known issues =
22
23 * [[Bugs we know about>>http://jira.xwiki.org/jira/secure/IssueNavigator.jspa?reset=true&&type=1&pid=10010&resolution=-1&sorter/field=updated&sorter/order=DESC]]
24
25 = Test Report =
26
27 You can check the [[manual test report>>TestReports.ManualTestReportXE30]] to learn about what was tested and the results on various browsers.
28
29 = Backward Compatibility and Migration Notes =
30
31 == General Notes ==
32
33 {{warning}}
34 If you're running in a multiwiki setup you'll also need to define the property //xwiki.store.migration.databases=all// to your //xwiki.cfg// file or explicitly name all databases to be migrated as in //xwiki.store.migration.databases=db1,db2,...//.
35 {{/warning}}
36
37 You may also want to [[import the default wiki XAR>>Main.Download]] in order to benefit from the improvements listed above.
38
39 {{warning}}
40 Always make sure you compare your //xwiki.cfg// file with the newest version since some configuration parameters were added. Note 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.
41 {{/warning}}
42
43 == Migration Notes ==
44
45 === The Velocity engine was updated to version 1.7 ===
46
47 {{warning}}
48 We upgraded Velocity to version 1.7 which brings several changes that are not backwards compatible.
49 {{/warning}}
50
51 We had to fix the following problems on the velocity code bundled with XWiki Enteprise:
52
53 * Escape quotes in interpolated strings (both ' and ") by doubling them ('' and "") (See [[VELOCITY-555>>https://issues.apache.org/jira/browse/VELOCITY-555]])
54 * [[XABLOG-117>>http://jira.xwiki.org/jira/browse/XABLOG-117]]: Blog application broken under Velocity 1.7
55 * [[XAADMINISTRATION-200>>http://jira.xwiki.org/jira/browse/XAADMINISTRATION-200]]: Configurable sections are broken ("configuration cannot be displayed because it was last edited by Admin who doesn't have permission to edit this page")
56 * [[XE-806>>http://jira.xwiki.org/jira/browse/XE-806]]: Upgrade activity macro to work with velocity 1.7
57
58 ==== Macro evaluation strategy ====
59
60 The main change is that Velocity 1.7 changed the way macro evaluations work. While before it was more flexible with many possible outcomes depending on what parameters were passed, and how they were used inside the macro, the current version simplified a lot the internal logic of variable assignments inside macros, which resulted in a critical regression for us. The same change was introduced between 1.6.0 and 1.6.1, but was reverted in 1.6.2 when we notified them of the regression, with the decision to go further with the change in 1.7.
61
62 To better understand the kind of code that doesn't work, take this example:
63
64 {{code language="none}}
65 #macro(callBySharing $x)
66 #set($x = 'a')
67 #end
68 #set($y = 'y')
69 #callBySharing($y)
70
71 $y -> 'y' in 1.7
72 $y -> 'a' in 1.6.2, 1.6.0 and before)
73 {{/code}}
74
75 But:
76
77 {{code language="none"}}
78 #set($x = 'x')
79 #callBySharing($x)
80
81 $x -> 'a' in all versions
82 {{/code}}
83
84 This means that only macros that are supposed to assign and return a value in one of its formal parameters will stop working, and only when the formal and actual parameters have different names. Macros with signatures like:
85
86 {{code language="none"}}
87 #macro(computeSomething $fromValue1 $fromValue2 $putResultHere)
88 {{/code}}
89
90 The only macro in the global ##macros.vm## that was broken by this change was ###setVariableFromRequest##, which is already fixed in the released version.
91
92 Now there's also a generic ###setVariable ("variableName" $value)## macro which can be used to emulate the call by sharing behavior in custom macros. How to use it:
93
94 Suppose you had a macro like this:
95
96
97 {{code language="none"}}
98 #macro(isBlogGlobal $blogDoc $isGlobal)
99 #set($isGlobal = false)
100 #getBlogProperty($blogDoc 'blogType' '' $discard)
101 #if($discard == 'global')
102 #set($isGlobal = true)
103 #end
104 #end
105 {{/code}}
106
107 Here ##$isGlobal## is the output variable which now doesn't always work. The updated version of the macro can be written as:
108
109 {{code language="none"}}
110 #macro(isBlogGlobal $blogDoc $isGlobal)
111 #set ($result = false)
112 #getBlogProperty($blogDoc 'blogType' '' $discard)
113 #if($discard == 'global')
114 #set($result = true)
115 #end
116 #set ($isGlobal = $util.null)
117 #setVariable ("$isGlobal" $result)
118 #end
119 {{/code}}
120
121 Pay attention to the last two lines in the macro.
122
123 In Velocity, when rendering ##$variable##, where ##$variable## is ##undefined## or ##null##, will cause the variable name to be printed instead. As it happens, when inside a macro, what gets printed is the name of the actual parameter (the one passed in the macro call), and not the formal one (the one declared in the macro definition). So, whenever ##$isGlobal## is rendered as a string, the name of the actual parameter is obtained.
124
125 ###set ($isGlobal = $util.null)## will make sure that no matter what the previous value of the variable was, ##$isGlobal## will be ##null## from this point forward, and ##"$isGlobal"## will output the name of the actual parameter.
126
127 When calling ###setVariable ("$isGlobal" $result)##, the first parameter will contain the name of the actual parameter used when calling ###isBlogGlobal##.
128
129 Inside the ###setVariable## macro, the wanted variable is assigned using ###evaluate##.
130
131 ==== Quotes and apostrophes inside strings ====
132
133 The second change is the escape syntax used inside strings for quotes and apostrophes. While before this used to work:
134
135 {{code language="none"}}
136 {{velocity}}
137 #set ($a = "He said \"maybe\"")
138 $a => He said \"maybe\"
139 {{/velocity}}
140 {{/code}}
141
142 now this snippet would throw an exception. Trying to escape an apostrophe inside an apostrophe-delimited string would have failed even before.
143
144 In Velocity 1.7 it is possible to place both single and double quotes inside a string, by doubling that character. For example:
145
146 {{code language="none"}}
147 {{velocity}}
148 #set ($a = "He said ""maybe""")
149 $a => He said "maybe"
150
151 #set ($b = 'that''s funny')
152 $b => that's funny
153 {{/velocity}}
154 {{/code}}
155
156 === Update dashboard macro calls ===
157
158 Because of the implementation of [[XWIKI-5938>>http://jira.xwiki.org/jira/browse/XWIKI-5938]], when upgrading from 2.x to 3.0, if the dashboard macro was used in its form from 2.5 (with the macro calls in the source of the page), it needs to be manually converted to the objects form.
159
160 {{todo}}Anca, please give more details about the update steps.{{/todo}}
161
162 === Update web.xml ===
163
164 Due to the package rename done for [[XWIKI-6158>>http://jira.xwiki.org/jira/browse/XWIKI-6158]] when upgrading from 2.x to 3.0 you must edit your ##web.xml## file and replace all occurrences of ##com.xpn.xwiki.wysiwyg## with ##org.xwiki.wysiwyg##.
165
166 == API Breakages ==
167
168 The following xwiki-core APIs were modified since XWiki Enterprise 2.7 (API breakages in modules that were moved to Rendering or Commons top level projects are not included):
169
170 {{code language="none"}}
171 ERROR: 8001: org.xwiki.officeimporter.OfficeImporter: Class org.xwiki.officeimporter.OfficeImporter removed
172 ERROR: 8001: org.xwiki.officeimporter.OfficeImporterFilter: Class org.xwiki.officeimporter.OfficeImporterFilter removed
173 ERROR: 7002: org.xwiki.officeimporter.OfficeImporterVelocityBridge: Method 'public java.lang.String getLastErrorMessage()' has been removed
174 ERROR: 7002: org.xwiki.officeimporter.OfficeImporterVelocityBridge: Method 'public boolean importDocument(byte[], java.lang.String, java.lang.String, java.util.Map)' has been removed
175 ERROR: 7002: org.xwiki.officeimporter.builder.PresentationBuilder: Method 'public org.xwiki.officeimporter.document.XDOMOfficeDocument build(java.io.InputStream, java.lang.String)' has been removed
176 ERROR: 7002: org.xwiki.officeimporter.builder.PresentationBuilder: Method 'public org.xwiki.officeimporter.document.XDOMOfficeDocument build(byte[])' has been removed
177 ERROR: 7002: org.xwiki.officeimporter.builder.XDOMOfficeDocumentBuilder: Method 'public org.xwiki.officeimporter.document.XDOMOfficeDocument build(byte[], org.xwiki.bridge.DocumentName, boolean)' has been removed
178 ERROR: 7002: org.xwiki.officeimporter.builder.XHTMLOfficeDocumentBuilder: Method 'public org.xwiki.officeimporter.document.XHTMLOfficeDocument build(byte[], org.xwiki.bridge.DocumentName, boolean)' has been removed
179 ERROR: 7012: org.xwiki.officeimporter.openoffice.OpenOfficeConverter: Method 'public boolean isMediaTypeSupported(java.lang.String)' has been added to an interface
180 ERROR: 8001: org.xwiki.officeimporter.openoffice.OpenOfficeDocumentConverter: Class org.xwiki.officeimporter.openoffice.OpenOfficeDocumentConverter removed
181 ERROR: 7002: org.xwiki.officeimporter.openoffice.OpenOfficeManager: Method 'public org.artofsolving.jodconverter.OfficeDocumentConverter getDocumentConverter()' has been removed
182 ERROR: 7002: org.xwiki.officeimporter.splitter.XDOMOfficeDocumentSplitter: Method 'public java.util.Map split(org.xwiki.officeimporter.document.XDOMOfficeDocument, int[], java.lang.String, org.xwiki.bridge.DocumentName)' has been removed
183 ERROR: 7012: org.xwiki.bridge.DocumentModelBridge: Method 'public org.xwiki.rendering.syntax.Syntax getSyntax()' has been added to an interface
184 ERROR: 7012: org.xwiki.bridge.DocumentModelBridge: Method 'public org.xwiki.rendering.block.XDOM getXDOM()' has been added to an interface
185 ERROR: 7002: org.xwiki.container.Request: Method 'public org.xwiki.url.XWikiURL getURL()' has been removed
186 ERROR: 7002: com.xpn.xwiki.api.XWiki: Method 'public java.lang.Object getExoPortalService(java.lang.String)' has been removed
187 ERROR: 7002: com.xpn.xwiki.api.XWiki: Method 'public java.lang.Object getExoService(java.lang.String)' has been removed
188 ERROR: 7002: com.xpn.xwiki.api.XWiki: Method 'public java.lang.Object getPortalService(java.lang.String)' has been removed
189 ERROR: 7002: com.xpn.xwiki.api.XWiki: Method 'public java.lang.Object getService(java.lang.String)' has been removed
190 ERROR: 7002: com.xpn.xwiki.api.XWikiCompatibilityAspect: Method 'public java.lang.Object ajc$interMethod$com_xpn_xwiki_api_XWikiCompatibilityAspect$com_xpn_xwiki_api_XWiki$getPortalService(com.xpn.xwiki.api.XWiki, java.lang.String)' has been removed
191 ERROR: 7002: com.xpn.xwiki.api.XWikiCompatibilityAspect: Method 'public java.lang.Object ajc$interMethod$com_xpn_xwiki_api_XWikiCompatibilityAspect$com_xpn_xwiki_api_XWiki$getService(com.xpn.xwiki.api.XWiki, java.lang.String)' has been removed
192 ERROR: 7002: com.xpn.xwiki.api.XWikiCompatibilityAspect: Method 'public java.lang.Object ajc$interMethodDispatch1$com_xpn_xwiki_api_XWikiCompatibilityAspect$com_xpn_xwiki_api_XWiki$getPortalService(com.xpn.xwiki.api.XWiki, java.lang.String)' has been removed
193 ERROR: 7002: com.xpn.xwiki.api.XWikiCompatibilityAspect: Method 'public java.lang.Object ajc$interMethodDispatch1$com_xpn_xwiki_api_XWikiCompatibilityAspect$com_xpn_xwiki_api_XWiki$getService(com.xpn.xwiki.api.XWiki, java.lang.String)' has been removed
194 ERROR: 7002: com.xpn.xwiki.pdf.api.PdfExport: Method 'public byte[] convertToStrictXHtml(byte[], com.xpn.xwiki.XWikiContext)' has been removed
195 ERROR: 7002: com.xpn.xwiki.pdf.api.PdfExport: Method 'public java.lang.String convertToStrictXHtml(java.lang.String)' has been removed
196 ERROR: 7002: com.xpn.xwiki.pdf.api.PdfExport: Method 'public byte[] convertXHtmlToXMLFO(byte[], com.xpn.xwiki.XWikiContext)' has been removed
197 ERROR: 7002: com.xpn.xwiki.pdf.api.PdfExport: Method 'public java.lang.String convertXHtmlToXMLFO(java.lang.String, com.xpn.xwiki.XWikiContext)' has been removed
198 ERROR: 7005: com.xpn.xwiki.pdf.api.PdfExport: Parameter 3 of 'public void export(com.xpn.xwiki.doc.XWikiDocument, java.io.OutputStream, int, com.xpn.xwiki.XWikiContext)' has changed its type to com.xpn.xwiki.pdf.api.PdfExport$ExportType
199 ERROR: 7005: com.xpn.xwiki.pdf.api.PdfExport: Parameter 3 of 'public void exportHtml(java.lang.String, java.io.OutputStream, int, com.xpn.xwiki.XWikiContext)' has changed its type to com.xpn.xwiki.pdf.api.PdfExport$ExportType
200 ERROR: 7002: com.xpn.xwiki.pdf.api.PdfExport: Method 'public void exportXHtml(byte[], java.io.OutputStream, int, com.xpn.xwiki.XWikiContext)' has been removed
201 {{/code}}
202
203 The following XWiki GWT APIs were modified since XWiki Enterprise 2.7:
204
205 {{code language="none"}}
206 TODO
207 {{/code}}

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected