A Practical Primer for XPages Application Development, Debugging, and Performance
Using XPages, Lotus® Notes® and Domino® developers can quickly create state-of-the-art web, mobile, and Notes client business applications using standard technologies like HTML, JavaScript, CSS, and XML. Now, there’s a perfect portable XPages quick reference for every working developer. Straight from the experts at IBM®, XPages Portable Command Guide offers fast access to working code, tested solutions, expert tips, and example-driven best practices. Drawing on their unsurpassed experience as IBM XPages lead developers and customer consultants, the authors explore many lesser known facets of the XPages runtime, illuminating these capabilities with dozens of examples that solve specific XPages development problems. Using their easy-to-adapt code examples, you can develop XPages solutions with outstanding performance, scalability, flexibility, efficiency, reliability, and value.
Covers lots of commands and parameters related to
- XPages behavior modification through xsp.properties
- Notes/Domino configuration files
- XSP Command Manager and OSGi Console
- The XSP Client-Side JavaScript Object
- Server Side JavaScript scripting
- Server Side JavaScript debugging via global functions, simple programming constructs, and logging
- Instantly access all XPages commands: Use this book as your quick offline solutions resource
- Logical how-to topic groupings provide one-stop research
- Compact size makes it easy to carry with you—wherever you go
- “Create Your Own Journal” section with blank, lined pages makes it easy to personalize this book for your needs
- “What Do You Want to Do?” chart inside the front cover helps you quickly find specific tasks
Designed for all Lotus and Domino developers with at least some XPages experience, XPages Portable Command Guide is the ideal companion and follow-up to Mastering XPages from IBM Press, the world’s #1 book on XPages technology.
Table of Contents:
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
About the Author :
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.
