- About the XSP Command Manager
- How to Execute the XSP Command Manager Commands
- Working with the OSGi Console
- How to Launch Notes/Designer Along with the OSGi Console
- Common Console Commands You Should Know
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
How to Execute the XSP Command Manager Commands
Commands are executed via the XSP Command Manager similar to any other command on the Domino server. The XSP Command Manager is running within the HTTP task, so the commands it executes must be fed through the HTTP task, as in this example:
tell http xsp <<xsp command manager command>>
Table 3.1 lists all the XSP Command Manager Commands.
Table 3.1. XSP Command Manager Commands
|
Command Name |
Description |
|
show data directory |
Shows the location of the Domino server's data directory. |
|
show program directory |
Shows the location of the Domino server's program directory. |
|
show version |
Displays the exact version of the XPages runtime that is installed and running on the Domino server. |
|
show settings |
Shows all the variables/properties that have been set on the server's bootstrap.properties file. If a bootstrap.properties file does not exist, the XPages runtime provides reasonable recommended defaults. |
|
show modules |
Displays the modules loaded in the system. The XPages runtime dynamically loads each Domino database as a web application module. |
|
refresh |
Causes the services in the XPages runtime to be refreshed. This is mainly reserved for future use. |
|
heapdump |
Performs a live dump of all objects on the Domino server's Java heap. Creates a dump file that must be read by other tools (such as the Eclipse Memory Analyzer); the file is not human readable. |
|
javadump |
Performs a Java dump, sometimes referred to as a thread dump or JavaCore dump, of the Domino server's JVM. The information collected during the dump operation is stored in human-readable format. |
|
systemdump |
Performs a full system dump, sometimes referred to as a core dump, of the Domino server's JVM. The dump information is platform specific and contains all the memory, process, and thread information for the JVM at the time the dump occurred. |
These commands can greatly aid administrators and developers when trying to analyze particular issues. The dump commands are of particular importance because they perform diagnostic dumps on the server’s JVM but do not cause the JVM or the server to stop operation.
show data directory
As the name suggests, this command simply tells the user where the Domino server’s data directory resides on the operating system’s file system. In a Domino server environment, the data directory stores all the databases that are available through the Domino server. The location of this directory is significant because all applications running on the server will reside in this directory or within a subdirectory of this directory.
Sample usage:
tell http xsp show data directory
Figure 3.1 shows the results of running the show data directory command on a Domino server.
){kind=link}
)
Figure 3.1. Result of running the show data directory command
show program directory
This command tells the user where the Domino server’s program directory resides on the operating system’s file system. This command can be convenient for developers who are not familiar with a particular setup of an individual server machine. The command enables developers or administrators to quickly identify the file system location of the Domino server’s program directory.
Sample usage:
tell http xsp show program directory
Listing 3.1 shows the result of running the show program directory command in the Domino server console.
Listing 3.1. Result of Running the show program directory Command in the Console
> tell http xsp show program directory 09/20/2011 10:52:33 PM C:\Program Files\IBM\Lotus\Domino
show version
This command shows the exact version of the XPages runtime that is installed and running on the Domino server. The version number is updated only when upgrading from one release to another of XPages core runtime. Adding or upgrading extensions such as the XPages Extension library does not update the version number. This command typically is used when a developer or administrator needs to confirm which version of the XPages runtime is running on a particular server. New features are added to the XPages runtime with each release. These features can range from new properties on existing controls to entirely new controls. Over time, a developer or administrator must confirm that the version of XPages runtime is at the appropriate release level for the applications running on the server. This command enables the developer or administrator to quickly confirm the XPages runtime version.
Sample usage:
tell http xsp show version
Listing 3.2 shows how to determine the version of the XPages runtime.
Listing 3.2. Result of Running the show version Command in the Console
> tell http xsp show version 09/20/2011 04:34:21 PM XSP Runtime Version: [DSI8.5.3] 20110629.1645
In the previous example, the version number can be broken down as follows:
- The DSI prefix is a constant, which does not vary from release to release.
- 8.5.3 represents the Major.Minor.Maintenance version number. The first digit is updated with each major feature release, the second digit is updated with each minor feature release, and the last digit is updated with each maintenance release.
- The final number (20110629.1645) represents the time stamp (yyyyMMdd.hhmm) at which the build in question occurred.
show settings
This command makes a request to the XPages runtime to print all the settings in use by the runtime. By default, the XPages runtime is configured with a host of default settings. These settings can be overwritten by adding a bootstrap.properties file to the xsp directory, which resides in the Domino server’s program directory (for example C:\domino\xsp). As a result of being able to override the default settings in the XPages runtime (via bootstrap.properties), it is not guaranteed that the XPages runtime defaults will apply from server to server. This command enables developers and administrators to quickly list all the current settings without needing to manually access various file system locations to determine which properties are being applied.
Sample usage:
tell http xsp show settings
Listing 3.3 shows the XPages runtime default settings being output to the Domino server console.
Listing 3.3. Result of Running the show settings Command in the Console (Default Case)
> tell http xsp show settings 09/16/2011 11:24:26 AM xsp.commas.not.delimiters.in.cookie=false 09/16/2011 11:24:26 AM com.ibm.faces.USE_UNENCODED_CONTEXT_PATH=/xsp 09/16/2011 11:24:26 AM xsp.gc.on.shutdown=false 09/16/2011 11:24:26 AM xsp.sessionid.name=SessionID 09/16/2011 11:24:26 AM xsp.default.charset=UTF-8 09/16/2011 11:24:26 AM xsp.log.severe.stack.trace=false 09/16/2011 11:24:26 AM xsp.default.post.buffer.size=1024 09/16/2011 11:24:26 AM xsp.allow.cookie.sessionid=true 09/16/2011 11:24:26 AM xsp.global.context.path=/xsp 09/16/2011 11:24:26 AM xsp.send.set.cookie2.header=true 09/16/2011 11:24:26 AM xsp.max.cookies.per.session=50 09/16/2011 11:24:26 AM xsp.allow.packagenames=false 09/16/2011 11:24:26 AM xsp.allow.url.sessionid=true 09/16/2011 11:24:26 AM xsp.default.chunk.post.buffer.size=8
In some cases, it is necessary to set extra system settings or even overwrite existing settings. Being able to quickly analyze which settings have changed can be invaluable. Listing 3.4 shows a case in which some settings (xsp.sessionid.name) have been overwritten by bootstrap.properties and some new logging settings (log_configuration and logdir) have been added. Chapter 6, “Server-Side Debugging Techniques,” explains these settings
Listing 3.4. Result of Running the show settings Command in the Console
> tell http xsp show settings 09/16/2011 11:01:47 PM xsp.commas.not.delimiters.in.cookie=false 09/16/2011 11:01:47 PM com.ibm.faces.USE_UNENCODED_CONTEXT_PATH=/xsp 09/16/2011 11:01:47 PM xsp.gc.on.shutdown=false 09/16/2011 11:01:47 PM log_configuration=xsp/log.properties 09/16/2011 11:01:47 PM xsp.sessionid.name=FOOID 09/16/2011 11:01:47 PM xsp.default.charset=UTF-8 09/16/2011 11:01:47 PM xsp.log.severe.stack.trace=false 09/16/2011 11:01:47 PM xsp.default.post.buffer.size=1024 09/16/2011 11:01:47 PM xsp.allow.cookie.sessionid=true 09/16/2011 11:01:47 PM xsp.global.context.path=/xsp 09/16/2011 11:01:47 PM xsp.send.set.cookie2.header=true 09/16/2011 11:01:47 PM xsp.max.cookies.per.session=50 09/16/2011 11:01:47 PM xsp.allow.packagenames=false 09/16/2011 11:01:47 PM xsp.allow.url.sessionid=true 09/16/2011 11:01:47 PM logdir=c:/Domino/log 09/16/2011 11:01:47 PM xsp.default.chunk.post.buffer.size=8
show modules
Each Domino database (.NSF) that is running within the XPages runtime is loaded by the XPages runtime as an application module. The show modules command shows all the databases (NSF modules) that are currently running within the XPages runtime. This command also shows registered system service modules that the XPages runtime automatically loads. This command is convenient for server administrators who need to know which XPages applications are being served by the XPages runtime at any point in time.
Sample usage:
tell http xsp show modules
Listing 3.5 shows all the active modules running within a Domino server that has sessions open for three XPages applications.
Listing 3.5. Result of Running the show modules Command in the Console
> tell http xsp show modules 09/16/2011 11:47:36 AM XSP Resources 09/16/2011 11:47:36 AM Default Http Registry Module 09/16/2011 11:47:36 AM OSGI WebContainer Bridge Service 09/16/2011 11:47:36 AM oauthtokenstore.nsf 09/16/2011 11:47:36 AM lsdemo2011.nsf 09/16/2011 11:47:36 AM xpagessbt.nsf
In Listing 3.5, six modules are listed. Three of these modules are XPages runtime system modules; the other three modules represent XPages applications that are currently running on the server.
- xpagessbt.nsf, lsdemo2011.nsf, and oauthtokenstore.nsf are all XPages applications that were running on the server when the command was executed.
- XSP Resources is a module loaded by the XPages runtime; it is not configurable.
- Default Http Registry Module is a module loaded by the Domino web container; it is not configurable.
- OSGI WebContainer Bridge Service is a module loaded by the Domino to OSGi bridge; it is not configurable.
The core runtime modules are not configurable and can be removed or added to in future releases.
refresh
This command was implemented with future extensions of the XSP Command Manager’s HTTP service in mind. As of release 8.5.3 of the Domino server, this command does nothing. It is intended to be used with HTTP services and will enable services to be refreshed as necessary without restarting the HTTP task or the XPages runtime.
Sample usage:
tell http xsp refresh
heapdump
The heapdump command performs a live dump of all objects on the Domino server’s Java heap. The operation creates a dump file that must be read by third-party tools; the file is not human readable. The dump file can be read using tools such as the Eclipse Memory Analyser Tool (www.eclipse.org/mat). Because the dump file is written in the IBM JVM heap dump format, it is necessary to install further add-ons to the Eclipse Memory Analyser Tool to read the heap dump information. You can download the add-on for the Eclipse Memory Analyzer tool from www.ibm.com/developerworks/java/jdk/tools/dtfj.html. The heapdump command causes a dump file to be generated in the server’s program directory, as demonstrated in Figure 3.2.
){kind=link}
)
Figure 3.2. Result of running the heapdump command in the console
Sample usage:
tell http xsp heapdump
When configured, the Eclipse Memory Analyzer tool enables the user to read the content of the dump file and provide information on where memory is potentially being leaked and which objects are in use when the dump occurs. Figure 3.3 shows sample output from the Eclipse Memory Analyzer Tool.
){kind=link}
)
Figure 3.3. Eclipse Memory Analyzer Tool
javadump
Running the javadump command causes the server’s JVM to create a Java Dump file. Sometimes referred to as a thread dump or a Javacore dump, the dump information is written to disk in a human-readable format—the contents of the dump file can be opened with applications such as Microsoft Notepad. The information stored as a result of a javadump is generally diagnostic information relating to the threads, stacks, locks, and memory that were in use by the JVM when the dump occurred. Javadump files are of particular use where the developer or administrator needs to quickly obtain system information (such as operating system version, JVM version, and loaded threads).
The Javadump file is lightweight by nature and can help to quickly identify which threads are hung in the system.
Sample usage:
tell http xsp javadump
Listing 3.6 shows the console output when the javadump command is executed.
Listing 3.6. Result of Running the javadump Command in the Console
> tell http xsp javadump 10/18/2011 11:40:00 PM HTTP JVM: JVMDUMP034I User requested Java dump using 'C:\Program Files\IBM\Lotus\Dominojavacore.20111018.233959.8220.0001.txt' through com.ibm.jvm.Dump.JavaDump 10/18/2011 11:40:01 PM HTTP JVM: JVMDUMP010I Java dump written to C:Program Files\IBM\Lotus\Domino\javacore.20111018.233959.8220.0001.txt
In Listing 3.6, you can see the result of executing the javadump command. A Javadump file is written to the location specified in the console output. It is beyond the scope of this book to go into the details of reading the contents of dump files. However, in the case of Javadump files, a few tips can easily be bestowed upon the reader to make reading the contents of the Javadump file easier. The dump file can essentially be broken down into different sections:
- Date and time of the javadump.
- Operating system signal information (who initiated the javadump and how it was initiated). The signal information tells the reader whether the user initiated the dump or whether the operating system did so due to a program fault. The signal information is operating system specific.
- Java (JVM) version.
- Information about threads running when the javadump occurred.
- Operating system and processor details.
- Native libraries loaded by the JVM.
- Full command line, including arguments, that the Domino server used to launch the JVM.
- JVM monitor information.
- Current stack for each thread running within the JVM.
For further in-depth information on how to read the contents of the Javadump file, see the following article from IBM support:
www-01.ibm.com/support/docview.wss?uid=swg21181068
Alternatively, you can search for information on how to read a javacore dump file in your favorite Internet search engine.
systemdump
The systemdump command is the most intensive of the three dump commands available through the XSP Command Manager. As a result, the footprint of the resulting systemdump file can be quite large. The systemdump file contains detailed information on the JVM’s threads, memory, and active processes. When a Java application crashes as a result of general protection fault failure or as a result of a major JVM error, a systemdump file is generated by default.
Sample usage:
tell http xsp systemdump
Listing 3.7 shows the console output when the systemdump command is executed.
Listing 3.7. Result of Running the systemdump Command in the Console
09/20/2011 12:36:30 AM HTTP JVM: JVMDUMP034I User requested System dump using 'C:\Program Files\IBM\Lotus\Dominocore.20110920.003630.8220.0002.dmp' through com.ibm.jvm.Dump.SystemDump 09/20/2011 12:38:26 AM HTTP JVM: JVMDUMP010I System dump written to C:\Program Files\IBM\Lotus\Domino\core.20110920.003630.8220.0002.dmp
The dump file is stored in a platform-specific format and, as a result, must be read by tools specific to the platform on which the dump was created. The IBM Dump Analyzer enables you to read and analyze the contents of a system dump that is performed on the Domino server. For more information on the IBM Dump Analyzer tool, refer to the following websites:
- “Java Diagnostics, IBM Style, Part 1: Introducing the IBM Diagnostic and Monitoring Tools for Java—Dump Analyzer,” at IBM.com: www.ibm.com/developerworks/java/library/j-ibmtools1/
- “Installing the IBM Monitoring and Diagnostic Tools for Java—Dump Analyzer,” at IBM.com: www.tinyurl.com/IBMJavaDumpAnalyzer
The information generated by a system dump is extremely granular in nature. An XPage developer rarely will need to create a system dump because the information the dump generates details information about every process executing on the system, not just the information pertinent to the JVM. A system dump generally is needed only when the failure is as a result of complex interactions with programs running outside the Domino server.