XPages Portable Command Guide A Compact Resource to XPages Application Development and the XSP Language

Martin Donnelly, software architect and tech lead for IBM’s XPages runtime team, has worked on all four XPages releases.

Maire Kehoe, lead developer on IBM’s XPages team, worked on Lotus Component Designer from 2004 to 2007, and moved to IBM Lotus Domino to help develop the Domino Server’s XPages runtime.

Tony McGuckin, senior software engineer for the XPages core runtime team, also researches and develops next generation application development tools, and consults on XPages with IBM customers.

Dan O’Connor, Team Lead for IBM Lotus Domino Designer, has worked on Domino Designer since release 8.5.0. He previously worked on the XFaces tooling for Lotus Component Designer and on JSF tooling for Rational® Application Developer.

Chapter 1 Working with XSP Properties 1

Locating and Updating xsp.properties 7

The Timeout Properties 9

xsp.application.timeout 10

xsp.session.timeout 10

xsp.session.transient 12

xsp.application.forcefullrefresh 13

The Theme Properties 13

xsp.theme 13

xsp.theme.web 14

xsp.theme.notes 15

The Resources Properties 18

xsp.resources.aggregate 18

The File Upload Properties 21

xsp.upload.maximumsize 21

xsp.upload.directory 21

The JSF Persistence Properties 22

xsp.persistence.discardjs 23

xsp.persistence.mode 24

xsp.persistence.tree.maxviews 29

xsp.persistence.file.maxviews 30

xsp.persistence.viewstate 30

xsp.persistence.file.gzip 32

xsp.persistence.file.async 32

xsp.persistence.file.threshold 33

xsp.persistence.dir.xspstate 34

xsp.persistence.dir.xspupload 35

xsp.persistence.dir.xsppers 35

The Client Side JavaScript Properties 37

xsp.client.script.dojo.version 37

xsp.client.script.dojo.djConfig 42

The HTML Page-Generation Properties 44

xsp.html.doctype 44

xsp.html.meta.contenttype 45

xsp.html.preferredcontenttypexhtml 46

xsp.html.page.encoding 47

xsp.compress.mode 47

xsp.client.validation 48

xsp.redirect 49

The Error-Management Properties 50

xsp.error.page.default 50

xsp.error.page 52

The User Preferences Properties 55

xsp.user.timezone 55

xsp.user.timezone.roundtrip 56

The AJAX Properties 57

xsp.ajax.renderwholetree 57

The Script Cache Size Properties 60

ibm.jscript.cachesize 60

ibm.xpath.cachesize 60

The Active Content Filtering Properties 61

The Resource Servlet Properties 65

xsp.expires.global 65

The Repeating Control Properties 66

xsp.repeat.allowZeroRowsPerPage 67

The Partial Update Properties 68

xsp.partial.update.timeout 68

The Link Management Properties 69

xsp.default.link.target 69

xsp.save.links 71

The Control Library Properties 73

xsp.library.depends 73

The Composite Data Properties 75

xsp.theme.preventCompositeDataStyles 76

Other Ways of Applying xsp.properties Settings 77

Viewroot Properties 77

Request Properties 78

Applying Properties Using a Theme 80

What Works Where? 81

Conclusion 81

Chapter 2 Working with Notes/Domino Configuration Files 83

INI Variables You Should Know About 83

The Java Heap 86

HTTPJVMMaxHeapSize Variable 88

HTTPJVMMaxHeapSizeSet Variable 89

JavaMaxHeapSize Variable 89

JavaMinHeapSize Variable 90

JavaEnableDebug Variable 90

JavaDebugOptions Variable 90

JavaUserClasses Variable 90

OSGI_HTTP_DYNAMIC_BUNDLES Variable 91

XPagesPreload Variable 92

XPagesPreloadDB Variable 93

When and Why Is Preloading Important? 93

Avoid Unnecessary Network Transactions in Your Application Code 95

Optimizing Client Memory Usage 96

vmarg.Xms 97

vmarg.Xmx 97

Enabling Extended Java Code with the java.policy File 97

JavaUserClasses 100

Conclusion 102

Chapter 3 Working with the Console 103

About the XSP Command Manager 103

How to Execute the XSP Command Manager Commands 103

show data directory 104

show program directory 105

show version 105

show settings 106

show modules 108

refresh 108

heapdump 109

javadump 109

systemdump 111

Working with the OSGi Console 112

diag 114

ss, ss , or

ss 116

start 119

stop 120

b 120

headers 121

help 122

How to Launch Notes/Designer Along with the OSGi Console 123

Common Console Commands You Should Know 126

help 127

load [task-name] 127

load [task-name] -? 128

quit 129

restart server 129

tell [task-name] quit 130

restart task [task-name] 130

show server 131

show conf [notes.ini variable] 132

set conf [notes.ini variable=value] 132

tell adminp [options] 132

load chronos [options] 133

load updall [path] [options] 134

load design [source] [target] [options] 134

load fixup [path] [options] 135

show tasks 136

show allports 136

show diskspace 137

show heartbeat 137

Conclusion 138

Chapter 4 Working with the XSP Client Side JavaScript Object 139

What Is the XSP Client Side JavaScript Object? 139

Summary of the XSP Client Side JavaScript Object Functions 145

The Public XSP Client Side JavaScript Object Functions 160

XSP.alert(message) : void 161

XSP.confirm(message) : boolean 162

XSP.error(message) : void 162

XSP.prompt(message, defaultValue) : string 163

XSP.djRequire(moduleName) : object 164

XSP.addPreSubmitListener(formId, listener, clientId, scriptId) : void 165

XSP.addQuerySubmitListener(formId, listener, clientId,

scriptId) : void 166

XSP.canSubmit() : boolean 167

XSP.allowSubmit() : void 168

XSP.setSubmitValue(submitValue) : void 169

XSP.getSubmitValue() : object 170

XSP.validateAll(formId, valmode, execId) : boolean 171

XSP.getFieldValue(node) : string 172

XSP.getDijitFieldValue(dj) : object 173

XSP.validationError(clientId, message) : void 174

XSP.scrollWindow(x, y) : void 176

XSP.partialRefreshGet(refreshId, options) : void 176

XSP.partialRefreshPost(refreshId, options) : void 177

XSP.attachClientFunction(targetClientId, eventType, clientScriptName) : void 179

XSP.attachClientScript(targetClientId, eventType, clientScript) : void 180

XSP.addOnLoad(listener) : void 181

XSP.showSection(sectionId, show) : void 182

XSP.findForm(nodeOrId) : object 183

XSP.findParentByTag(nodeOrId, tag) : object 183

XSP.getElementById(elementId) : object 184

XSP.hasDijit() : boolean 184

XSP.trim(s) : string 185

XSP.startsWith(s, prefix) : boolean 186

XSP.endsWith(s, suffix) : boolean 186

XSP.toJson(o) : string 187

XSP.fromJson(s) : object 187

XSP.log(message) : void 188

XSP.dumpObject(object) : string 189

How XPages Uses the Dojo Framework 189

Dojo Types and Attributes 190

Working with Dojo Dijits 193

IDs in the HTML Source and the Requirement to Use the “#{id:” Syntax 193

Scripts Accessing Dojo Controls Need to Use dijit.byId 195

Dojo Controls Are Not Available While the HTML Page Is Loading 196

Bad AJAX Requests to an XPage Can Cause Loss of Data 197

XPages Input Validation Can Interact with Dojo Layout Controls 198

Dojo Control Interaction with XPages Partial Update 199

Client-Side Debugging Techniques 201

XSP Object Debug Functions 201

Client-Side Debugging with Dojo 202

Other Miscellaneous Client-Side Debugging Information 204

Conclusion 207

Chapter 5 Server-Side Scripting 209

What Can I Do with Server Side JavaScript? 210

XPages Object Model 210

Server-Side Scripting Objects and System Libraries 210

Summary of Server-Side Global Functions 216

getComponent(id:String): UIComponent 219

getClientId(id:String): String 223

getLabelFor(component:UIComponent):UIComponent 224

getView(): UIViewRoot 225

getForm(): UIForm 225

save():void 226

Working with Java Made Simpler 226

Importing Java Packages into Server Side JavaScript 226

Creating Custom Java Classes 227

Creating Managed Beans 227

Conclusion 238

Chapter 6 Server-Side Debugging Techniques 239

The “Poor Man’s” Debugger 239

print(message) : void & println(message) : void 239

_dump(object) : void 241

Using try/catch Blocks 246

How to Set Up a Server for Remote Debugging 247

Debugging Java Code and Managed Beans 250

Debugging XPages Extension Plug-ins 261

How to Configure notes.ini and rcpinstall.properties for Logging 262

Interpreting a Stack Trace: Where to Go from Here? 268

Understanding the XPages Request Handling Mechanism 268

Understanding the XPages Request Processing Lifecycle 269

XPages Toolbox 275

Conclusion 276

Appendix A Definitive Resources 277

Appendix B Useful Online Resources 279

Appendix C Make Your Own Journal 281

Index 285

The New copy of this book will include any supplemental materials advertised. Please check the title of the book to determine if it should include any access cards, study guides, lab manuals, CDs, etc.

The Used, Rental and eBook copies of this book are not guaranteed to include any supplemental materials. Typically, only the book itself is included. This is true even if the title states it includes any access cards, study guides, lab manuals, CDs, etc.