Wiki source code of XML-RPC Java Examples

Version 2.2 by dilipkumarj on 2010/01/30 16:38

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}{{toc/}}{{/box}}
2
3 = Requirements =
4
5 The following libraries should be added to your application classpath:
6
7 {{info}}
8 Most of the libraries can be easily found in the WEB-INF/lib folder of your XWiki instance. As mentioned at [[platform:Features.XMLRPC]], version numbers of these libraries for the most part are irrelevant. In the examples listed here, XWiki version 2.1.1 is used.
9 {{/info}}
10
11 |=Library|=Source
12 |commons-logging-1.1.1.jar|WEB-INF/lib folder of XWiki 2.1.1
13 |ws-commons-util-1.0.2.jar|WEB-INF/lib folder of XWiki 2.1.1
14 |xmlrpc-common-3.1.jar|WEB-INF/lib folder of XWiki 2.1.1
15 |xmlrpc-client-3.1.jar|WEB-INF/lib folder of XWiki 2.1.1
16 |xwiki-core-2.1.1.jar|WEB-INF/lib folder of XWiki 2.1.1
17 |swizzle-confluence-1.2-20080419-xwiki.jar|WEB-INF/lib folder of XWiki 2.1.1
18 |xwiki-core-xmlrpc-client-2.1.1.jar|For XWiki 2.1.1 the jar is available [[here>>http://maven.xwiki.org/releases/org/xwiki/platform/xwiki-core-xmlrpc-client/2.1.1/xwiki-core-xmlrpc-client-2.1.1jar]]
19 |xwiki-core-xmlrpc-model-2.1.1.jar|WEB-INF/lib folder of XWiki 2.1.1
20
21 = Authentication: Login Example =
22
23 Try Providing an incorrect username & password. The application will throw an exception
24 For correct username & password, the application will compile & run successfully.
25
26 {{code language="java"}}
27 import java.net.MalformedURLException;
28 import org.apache.xmlrpc.XmlRpcException;
29 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
30 public class XmlRpcLogin {
31 public static void main(String[] args) throws MalformedURLException{
32
33 //URL of the xwiki instance
34 String url="http://localhost:8080/xwiki/xmlrpc/confluence";
35
36 //Replace user & pass with desired xwiki username & password
37 String user="Admin";
38 String pass="admin";
39
40 //Perform Login & Authentication using above url address
41 try{
42 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
43 rpc.login(user, pass);
44
45 }
46 catch(XmlRpcException e){
47 System.out.println("invalid username/password was specified or communication problem");
48 }
49 }
50 }
51 {{/code}}
52
53 = Authentication: Logout Example =
54
55 Let's build on the previous example where we "Logged In". We test logout action using a boolean variable since rpc.logout() method returns true on successful logout.
56
57 {{code language="java"}}
58
59 import java.net.MalformedURLException;
60 import org.apache.xmlrpc.XmlRpcException;
61 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
62 public class XmlRpcLogout {
63 public static void main(String[] args) throws MalformedURLException{
64
65 //Variable to test whether user logged out successfully. Default set to false
66 boolean loggedOut=false;
67
68 //URL of the xwiki instance
69 String url="http://localhost:8080/xwiki/xmlrpc/confluence";
70
71 //Replace user & pass with desired xwiki username & password
72 String user="Admin";
73 String pass="admin";
74
75 try{
76 //Perform Login & Authentication using above url address
77 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
78 rpc.login(user, pass);
79
80 //Log out action. Returns true if user successfully logged out
81 loggedOut=rpc.logout();
82 System.out.println(loggedOut);
83 }
84 catch(XmlRpcException e){
85 System.out.println("invalid username/password was specified or communication problem");
86 }
87 }
88 }
89 {{/code}}
90
91
92 = Space: Get A List Of Spaces =
93
94 Now, that we can log in and log out, let's move to finding out what's inside your wiki. How about a list of all the spaces inside the wiki. Compare the above two examples and you will see the new import that we added viz. the SpaceSummary class.
95
96 {{code language="java"}}
97
98 import java.net.MalformedURLException;
99 import java.util.List;
100 import org.apache.xmlrpc.XmlRpcException;
101 import org.codehaus.swizzle.confluence.SpaceSummary;
102 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
103 public class SpaceList {
104
105 public static void main(String[] args) throws MalformedURLException {
106 //URL of the xwiki instance
107 String url="http://localhost:8080/xwiki/xmlrpc/confluence";
108
109 //Replace user & pass with desired xwiki username & password
110 String user="Admin";
111 String pass="admin";
112
113 //Perform Login & Authentication using above url address
114 try{
115 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
116 rpc.login(user, pass);
117
118 List<SpaceSummary> spaceList = rpc.getSpaces();
119 System.out.println("Total Number of Spaces: " +spaceList.size());
120 for(int i=0;i<spaceList.size();i++){
121 System.out.println(spaceList.get(i).getKey());
122 }
123 rpc.logout();
124 }
125 catch(XmlRpcException e){
126 System.out.println("invalid username/password was specified or communication problem");
127 }
128 }
129 }
130 {{/code}}
131
132 = Space: Create A Space =
133
134 So far, we logged in, logged out & also were able to see a list of spaces in the xwiki instance. Let's go ahead and create a new space. And not just that we will also assign the default home page for the space. In this example, we use "XMLRPC" as the space name & "xmlrpc.WebHome" as the home page
135
136 {{code language="java"}}
137 import java.net.MalformedURLException;
138 import org.apache.xmlrpc.XmlRpcException;
139 import org.codehaus.swizzle.confluence.Space;
140 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
141
142 public class CreateSpace {
143
144 public static void main(String[] args) throws MalformedURLException {
145 //URL of the xwiki instance
146 String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
147
148 //Replace user & pass with desired xwiki username & password
149 String user = "Admin";
150 String pass = "admin";
151
152 //Perform Login & Authentication using above url address
153 try {
154 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
155 rpc.login(user, pass);
156
157 //Create a Space object which holds the Key, Homepage, Name & description.
158 //Key is visible name for the space
159 Space space = new Space();
160 space.setKey("XMLRPC");
161 space.setHomepage("xmlrpc.WebHome");
162 space.setName("xmlrpc");
163 space.setDescription("Demo Space Created To Test XMLRPC");
164
165 //One simple method adds the space created to your xwiki instance
166 rpc.addSpace(space);
167
168 rpc.logout();
169 } catch (XmlRpcException e) {
170 System.out.println("invalid username/password was specified or communication problem");
171 }
172 }
173 }
174 {{/code}}
175
176 = Space: Delete A Space =
177
178 Removal of a space is far more easier than creating one. All it requires is the "Key" (the visible name of the space) to be provided to the remove() method.
179
180 {{warning}}Please note that deletion of space removes all pages in the space too. It is recommended to always make sure that the space is empty before deleting it.
181 {{/warning}}
182
183 {{code language="java"}}
184
185 import java.net.MalformedURLException;
186 import org.apache.xmlrpc.XmlRpcException;
187 import org.codehaus.swizzle.confluence.Space;
188 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
189
190 public class DeleteSpace {
191
192 public static void main(String[] args) throws MalformedURLException {
193 //URL of the xwiki instance
194 String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
195
196 //Replace user & pass with desired xwiki username & password
197 String user = "Admin";
198 String pass = "admin";
199
200 //Perform Login & Authentication using above url address
201 try {
202 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
203 rpc.login(user, pass);
204
205 //Delete the space which is reference by "XMLRPC" key
206 rpc.removeSpace("XMLRPC");
207
208 rpc.logout();
209 } catch (XmlRpcException e) {
210 System.out.println("invalid username/password was specified or communication problem");
211 }
212 }
213 }
214 {{/code}}
215
216 = Page: Retrieve/Search A Page =
217
218 A page is probably the most important unit of any wiki around which everything else is built. Spaces/Categories, Attachments, Comments, etc are more or less meaningless without a supporting page in a wiki system.
219 One of the most widely performed action on any wiki has to be searching for pages. Searches may happen through search boxes provided in a wiki or may be through following links from one page to another. On the XMLRPC side too, searching pages has been given a lot of importance and quite a few methods are available for the same.
220 Since, this topic is an important one, all the page retrieval/search examples [[can be found here>>XMLRPCJavaExamples2]]
221
222 = Page: Create A Page =
223
224 Now for the moment of truth. Addition of Pages to a Wiki is as simple as searching for them. Thankfully, the XWiki XMLRPC api has just the tools you need to do your job.
225 At the very least, you would require the following three parameters to create a Page:
226
227 1. Space - The Space where the Page is to be stored
228 1. Title - The title for the Page
229 1. Content - The content to be displayed inside the Page
230
231 {{warning}}
232 Please beware that using a title for an existing Page will overwrite all the contents of that Page. Make sure no Page *with the same title* exists in the same Space before you attempt to use the create Page functionality of XMLRPC.
233 {{/warning}}
234
235 In our example below, we would use
236
237 |=Parameter|=Value
238 |Space|demo code
239 |title|New Page
240 |Content|New Page Created
241 {{info}}This is XMLRPC Test{{/info}}
242
243 {{code language="java"}}
244 import java.net.MalformedURLException;
245 import org.apache.xmlrpc.XmlRpcException;
246 import org.codehaus.swizzle.confluence.Page;
247 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
248
249 public class CreatePage {
250
251 public static void main(String[] args) throws MalformedURLException, XmlRpcException {
252
253 //URL of the xwiki instance
254 String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
255
256 //Replace user & pass with desired xwiki username & password
257 String user = "Admin";
258 String pass = "admin";
259
260
261 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
262 try {
263
264 //Perform Login & Authentication
265 rpc.login(user, pass);
266
267 //Create a Page object & set it's three important attributes viz. Space, Title, Content
268 //Observe how the \\\\ has been used to create a new line in the final wiki Page
269 //Also, XWiki syntax can be passed as it is. Here, we passed the info macro
270 //The info macro would get rendered an info box in the Page
271 Page page = new Page();
272 page.setSpace("demo code");
273 page.setTitle("New Page");
274 page.setContent("New Page Created \\\\ {{info}}This is XMLRPC Test{{/info}}");
275
276 //Also set the parent Page to "demo code.WebHome" so that the "New Page" we created is not
277 //an orphan Page
278 page.setParentId("demo code.WebHome");
279
280
281 //Store the page object into XWiki
282 rpc.storePage(page);
283
284
285 } catch (XmlRpcException e) {
286 System.out.println("invalid username/password was specified or communication problem or ");
287 System.out.println(e);
288 } finally {
289 rpc.logout();
290 }
291 }
292 }
293
294 {{/code}}
295
296
297 = Page: Get Page History =
298
299 Now, that we are adding content to Pages, there are going to be versions of the same document. These versions are called History of the Page. The XWiki API has methods available to access the history of the Page. The class that would help us in this case is the XWikiPageHistorySummary class.
300
301 {{info}}
302 Please note that the methods of XWikiPageHistorySummary class only help you access the various historical revisions of the document & not the content of the document itself. Eg. You would get to know that a particular Page called Main.WebHome has highest version as 4.1 or maybe 10.9. In order to access the content of the 4.1 revision of the document, you would have to use the [[Page retrieval code provided here>>http://platform.xwiki.org/xwiki/bin/view/Features/XMLRPCJavaExamples2#HRetrievePageByMajorMinorVersion]] by passing the appropriate version of the document.
303 {{/info}}
304
305 {{code language="java"}}
306 import java.net.MalformedURLException;
307 import java.util.List;
308 import org.apache.xmlrpc.XmlRpcException;
309 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
310 import org.xwiki.xmlrpc.model.XWikiPageHistorySummary;
311
312
313 public class PageHistory {
314
315 public static void main(String[] args) throws MalformedURLException, XmlRpcException {
316
317 //URL of the xwiki instance
318 String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
319
320 //Replace user & pass with desired xwiki username & password
321 String user = "Admin";
322 String pass = "admin";
323
324
325 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
326 try {
327
328 //Perform Login & Authentication
329 rpc.login(user, pass);
330
331 //Create a XWikiPageHistorySummary object to hold all the revisions/history
332 //of the Main.WebHome Page
333 List<XWikiPageHistorySummary> hist = rpc.getPageHistory("Main.WebHome");
334
335 //Iterate through all the available versions for Main.WebHome
336 for(XWikiPageHistorySummary xphs:hist){
337
338 //Print the fully qualified name of the Page i.e. SpaceName.PageName
339 //In our example this would be Main.WebHome
340 System.out.println(xphs.getBasePageId());
341
342 //Print the historical page ID or name of the Main.WebHome page
343 //This would print something like:
344 //Main.WebHome?minorVersion=1&language=&version=2
345 //It means page=Main.WebHome, version=2, minor version=1 & language=default
346 System.out.println(xphs.getId());
347
348 //Printing the version of Main.WebHome in the majorversion.minorversion format
349 System.out.println("Version: "+xphs.getVersion()+"."+xphs.getMinorVersion());
350
351 //Date when the Page was last modified
352 System.out.println(xphs.getModified());
353
354 //User who last modified the Page
355 System.out.println(xphs.getModifier());
356
357 //Just a seperator between various versions of the document when printing
358 //to console
359 System.out.println("------------------------------");
360 }
361
362 } catch (XmlRpcException e) {
363 System.out.println("invalid username/password was specified or communication problem or ");
364 System.out.println(e);
365 } finally {
366 rpc.logout();
367 }
368 }
369 }
370 {{/code}}
371
372
373 = Page: Update A Page =
374
375 We saw code to search a Page, create a Page and get all it's revisions. Now, we move to updating a Page. In our example, we have used the Page called "Update Page" in the "demo code" Space. The basic intent is to get the content first from XWiki. Then add our updated content or "concatenate" new content with the existing content. Then, update the final content back to XWiki. Only the methods of the Page class & the rpc.getPage() & rpc.storePage() would be used here.
376
377 {{warning}}
378 It is strongly advised that if this is the first time you are using XWiki XMLRPC, go through the examples at the start of this article. Each example tries to build up on the previous one & you would find understanding the API easier.
379 {{/warning}}
380
381 {{code language="java"}}
382
383 import java.net.MalformedURLException;
384 import org.apache.xmlrpc.XmlRpcException;
385 import org.codehaus.swizzle.confluence.Page;
386 import org.xwiki.xmlrpc.XWikiXmlRpcClient;
387
388
389 public class UpdatePage {
390
391 public static void main(String[] args) throws MalformedURLException, XmlRpcException {
392
393 //URL of the xwiki instance
394 String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
395
396 //Replace user & pass with desired xwiki username & password
397 String user = "Admin";
398 String pass = "admin";
399
400
401 XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
402 try {
403
404 //Perform Login & Authentication
405 rpc.login(user, pass);
406
407 //Create a Page object to hold our Document information
408 Page page = new Page();
409 //Fetch the required page. In our example, the page is in Space "demo code"
410 //and the Page is "Update Page"
411 page=rpc.getPage("demo code.Update Page");
412 //Fetch the content of the page & store it in a string for temporary storage
413 //This is the present content of the Page
414 String presentContent=page.getContent();
415 //Create a string that will hold the new content that is to be added to the Page
416 String newContent="\\\\Some new content added";
417 //Set the content of the page as: present content + new content
418 //However, this page is not yet stored to XWiki. It only resides in your application
419 page.setContent(presentContent+newContent);
420 //Finally, store the "updated" Page to XWiki
421 rpc.storePage(page);
422
423 //Just to make sure everything saved all right, fetch the content again for the Page
424 System.out.println(page.getContent());
425
426 } catch (XmlRpcException e) {
427 System.out.println("invalid username/password was specified or communication problem or ");
428 System.out.println(e);
429 } finally {
430 rpc.logout();
431 }
432 }
433 }
434
435 {{/code}}

Get Connected