XML-RPC Java Examples (XWiki.org)

= Requirements =

The following libraries should be added to your application classpath:

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.

|=Library|=Source

|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

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

String user="Admin";

String pass="admin";

//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");

}

}

}

= 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.

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

String user="Admin";

String pass="admin";

try{

//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");

}

}

}

= 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.

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

String user="Admin";

String pass="admin";

//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());

}

rpc.logout();

}

catch(XmlRpcException e){

126

System.out.println("invalid username/password was specified or communication problem");

}

}

}

= 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

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

rpc.addSpace(space);

rpc.logout();

} catch (XmlRpcException e) {

170

System.out.println("invalid username/password was specified or communication problem");

}

}

}

= 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.

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");

}

}

}

= 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

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

234

235

In our example below, we would use

|=Parameter|=Value

|Space|demo code

|title|New Page

|Content|New Page Created

241

{{info}}This is XMLRPC Test{{/info}}

242

243

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

rpc.storePage(page);

} catch (XmlRpcException e) {

286

System.out.println("invalid username/password was specified or communication problem or ");

287

System.out.println(e);

} finally {

rpc.logout();

}

}

}

= 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

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.

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);

} finally {

rpc.logout();

}

}

}

= 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

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.

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);

} finally {

rpc.logout();

}

}

}

= Page: Remove A Page =

439

440

Removal of Pages is straight forward. You are required to know the fully qualified name of the Page i.e. SpaceName.PageName (in our example, this would be "demo code.New Page"). We test the safe deletion of the Page using a boolean variable. The rpc.removePage() method returns true if the Page was successfully removed from the wiki.

441

442

443

You would need to have the deletion rights assigned to the user credentials you are passing to the rpc.login() method

444

445

446

rpc.removePage() method does not completely delete a Page in ordinary circumstances. If you have a recycle bin option enabled (by default, it is enabled for XWiki), then the "removed/deleted Page" is stored in the recycle bin from where it will cleaned out as per the settings for recycle bin in the xwiki.cfg file of your XWiki instance.

import java.net.MalformedURLException;

453

import org.apache.xmlrpc.XmlRpcException;

454

import org.xwiki.xmlrpc.XWikiXmlRpcClient;

455

456

457

public class DeletePage {

458

public static void main(String[] args) throws MalformedURLException, XmlRpcException {

459

460

//URL of the xwiki instance

461

String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

462

463

//Replace user & pass with desired xwiki username & password

464

String user = "Admin";

465

String pass = "admin";

466

467

468

XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);

469

try {

470

471

//Perform Login & Authentication

472

rpc.login(user, pass);

473

474

//Delete Page called "New Page" from Space called "demo code"

475

//Test deletion using a Boolean variable

476

Boolean b=rpc.removePage("demo code.New Page");

477

478

//Should print "true" if deletion of page was successful

479

System.out.println(b);

480

481

482

} catch (XmlRpcException e) {

483

System.out.println("invalid username/password was specified or communication problem or ");

484

System.out.println(e);

} finally {

rpc.logout();

}

}

}

= Attachment: List Attachments For Page =

495

496

So far, we worked with the Spaces (which are like directories/folders), Pages (which are the actual documents inside directories/folders). Both, Spaces & Pages can reside on their own & still be meaningful. However, there are other entities such as Attachments/Comments which are meaningful only when attached to Pages.

497

The first entity that we explore are Attachments. A very common operation in a Wiki is to attach files to an existing Page. However, let's start with an example where we assume that there are a number of attachments already associated with a Page. Our job here is to find out what are those attachments.

498

499

500

Please be aware that there are two class files for "Attachment" in two different packages and both look like they are exactly the same thing. One of them is the org.codehaus.swizzle.confluence.Attachment & the other is the com.xpn.xwiki.api.Attachment. We use the former one which is org.codehaus.swizzle.confluence.Attachment. The other one is part of the XWiki Core & used for Attachment related actions in the XWiki itself.

import org.codehaus.swizzle.confluence.Attachment;

506

import java.net.MalformedURLException;

507

import java.util.List;

508

import org.apache.xmlrpc.XmlRpcException;

509

import org.xwiki.xmlrpc.XWikiXmlRpcClient;

510

511

public class AttachmentList {

512

public static void main(String[] args) throws MalformedURLException, XmlRpcException {

513

//Replace the url with your xwiki server address

514

String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

515

516

//Replace user & pass with desired xwiki username & password

517

String user = "Admin";

518

String pass = "admin";

519

520

//Perform Login & Authentication using above url address

521

XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);

522

523

try {

524

rpc.login(user, pass);

525

526

//Get the list of all attachments for the Page named "Main.Host Page"

527

List<Attachment> att = rpc.getAttachments("Main.Host Page");

528

529

//Iterate through all the attachments in the list obtained

530

for (Attachment attachment : att) {

531

532

//Name of the file attached to the "Main.Host Page"

533

System.out.println(attachment.getFileName());

534

//Size of the file (in Bytes)

535

System.out.println(attachment.getFileSize());

536

//Absolute URL of the attachment for direct access

537

System.out.println(attachment.getUrl());

}

} catch (XmlRpcException e) {

542

System.out.println("invalid username/password was specified or communication problem or ");

543

System.out.println(e);

} finally {

rpc.logout();

}

}

}

= User: Create A New User =

552

553

This is an Administrative function in XWiki & needs Admin privileges for the User with whose credential we connect through the XML-RPC. Creating a new User involves the following steps:

554

555

1. Create a Page with the desired "UserName" as the Page Name

556

1. Create this Page in the "XWiki" space

557

1. Set the properties of the newly created User

558

559

Please read the comments in the example below to understand the detailed steps:

import java.net.MalformedURLException;

564

import java.security.NoSuchAlgorithmException;

565

import org.apache.xmlrpc.XmlRpcException;

566

import org.codehaus.swizzle.confluence.Page;

567

import org.xwiki.xmlrpc.XWikiXmlRpcClient;

568

import org.xwiki.xmlrpc.model.XWikiObject;

569

570

public class CreateUser {

571

572

public static void main(String[] args) throws MalformedURLException, XmlRpcException, NoSuchAlgorithmException {

573

574

//URL of the xwiki instance

575

String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

576

577

//Replace user & pass with desired xwiki username & password

578

String user = "Admin";

579

String pass = "admin";

580

581

582

XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);

583

try {

584

//Perform Login & Authentication

585

rpc.login(user, pass);

586

587

//Create a Page object & set it's three important attributes viz. Space, Title, Content

588

//In our example, testuser is the Page Name

589

//We set the content of the Page to automatically load XWiki.XWikiUserSheet

590

//This sheet is used to display the User Profile in the default format

591

592

Page page = new Page();

593

page.setSpace("XWiki");

594

page.setTitle("testuser");

595

page.setId("XWiki.testuser");

596

page.setContent("{{include document=\"XWiki.XWikiUserSheet\"/}}");

597

rpc.storePage(page);

598

599

//Set properties for the newly created user "testuser"

600

//List of all properties available in the XWiki.XWikiUsers class in your wiki

601

//Edit XWikiUsers class in class editing mode to access all properties or define new ones

602

603

XWikiObject xobj = new XWikiObject();

604

xobj.setClassName("XWiki.XWikiUsers");

605

xobj.setPageId("XWiki.testuser");

606

xobj.setProperty("first_name", "Test");

607

xobj.setProperty("last_name", "User");

608

xobj.setProperty("password","asdfjk");

609

rpc.storeObject(xobj);

610

611

//Finally, associate the user to the XWikiAllGroup

612

//We simply associate the XWiki.testuser Page to the XWiki.XWikiAllGroup Page

613

//Set the "member" property to the desired XWiki UserName

614

615

XWikiObject xobjgrp = new XWikiObject();

616

xobjgrp.setClassName("XWiki.XWikiGroups");

617

xobjgrp.setPageId("XWiki.XWikiAllGroup");

618

xobjgrp.setProperty("member","XWiki.testuser");

619

rpc.storeObject(xobjgrp);

620

621

} catch (XmlRpcException e) {

622

System.out.println(e);

} finally {

rpc.logout();

}

}

}

= User: Add User To Groups =

632

633

Adding User to Groups is a very simple task. This requires us to add the desired user to the properties of the Group in question. The example below details all the steps needed to complete this task:

import java.net.MalformedURLException;

638

import java.security.NoSuchAlgorithmException;

639

import org.apache.xmlrpc.XmlRpcException;

640

import org.codehaus.swizzle.confluence.Page;

641