This chapter is from the book
This chapter is from the book
This chapter is from the book
Working with the OSGi Console
Before delving into the inner workings of the OSGi console, it is best to briefly explain OSGi. OSGi stands for Open Services Gateway initiative framework. This framework allows software to be written and executed as independent components. In OSGi-speak, these components are referred to as bundles. OSGi is used in a wide range of applications, from client programs such as Eclipse and IBM Lotus Notes, to mobile phones, to server applications such as IBM Lotus Domino. As a result of their modular nature, OSGi bundles can be started, stopped, and debugged on an individual basis, without the need for stopping or restarting the entire platform. Both the Domino server and the Notes client use Eclipse’s implementation of OSGi (Equinox) as their OSGi runtime platform.
OSGi was added to the Domino platform in release 8.5.2. As a result, in Domino 8.5.2, the XPages runtime was repackaged to run as OSGi bundles (instead of just a regular collection of Java JARS), also referred to as Eclipse plug-ins.
The OSGi console allows for the input of commands that the OSGi platform then performs. The platform posts the results of such commands back to the console. The OSGi platform itself has a whole host of commands that can simplify the troubleshooting of problems. The OSGi console can assist developers in developing XPages controls and applications, as well as assisting support personnel in diagnosing runtime issues. Developers who extend the XPages runtime by creating libraries will find the OSGi console commands to be a particularly powerful tool in analyzing problems. The OSGi console is of particular use when the developer/administrator needs to know whether individual plug-ins (or sets of plug-ins) are loading correctly or which version of a plug-in is in use.
As mentioned earlier, OSGi is embedded within both the Notes client and the Domino server. Depending on where your XPages application is running (whether on the client or the server), your method of accessing the OSGi console will vary. We start by explaining how to access the OSGi console on the Domino server.
OSGi is embedded within the HTTP task on the Domino server, as a result, the OSGi console is started automatically whenever the HTTP task is started. OSGi console commands are routed to the OSGi console via the HTTP task. That is, when entering an OSGi console command on the Domino server, the user must tell the HTTP task to route the specified command to the OSGi console—for example:
tell http osgi <<command>>
Here, <<command>> is the name of the OSGi console command. Any OSGi command can be executed using the preceding syntax.
When it comes to OSGi commands, every developer and administrator should know several rudimentary commands. These commands can be your “go to” commands when problems arise—say, when you suspect bundle loading might be a factor. Even when you do not think that bundle loading is the problem, it is often best to first confirm that the bundle is actually loaded before proceeding with other debugging techniques.
Table 3.2 lists some of the more commonly used OSGi commands that are available to use for diagnosing plug-in issues on the Domino server (and also the Notes client). In Table 3.2, bundle-symbolic-name is referenced extensively. This is the name by which the OSGi platform references bundles. bundle-symbolic-name correlates directly to the Bundle-SymbolicName manifest header, often referred to as the plug-in name.
Table 3.2. OSGi Console Commands
|
Command Syntax |
Description |
|
tell http osgi diag <bundle-symbolic-name> |
Diagnoses the status of the bundle whose name is provided. Determines whether the bundle is resolved and, if not, states why the bundle is not resolved. |
|
tell http osgi ss <bundle-symbolic-name> |
Lists the status of all bundles in the system. Optionally, a symbolic name or a symbolic name prefix can be provided to obtain the status of a particular bundle or a subset of bundles. |
|
tell http osgi start <bundle-symbolic-name> |
Starts the bundle with the specified symbolic name. |
|
tell http osgi stop <bundle-symbolic-name> |
Stops the bundle with the specified symbolic name. |
|
tell http osgi b <bundle-symbolic-name> |
Prints metadata relating to the specified bundle. |
|
tell http osgi headers <bundle-symbolic-name> |
Lists the OSGi headers for the specified bundle. |
|
tell http osgi help |
Lists all the OSGi command available on the server, along with some text describing each command. |
All the commands listed in Table 3.2 can be entered via the Domino server console, with the results of such commands being printed back to the console, as illustrated in Figure 3.4.
){kind=link}
)
Figure 3.4. Running an OSGi command on the Domino Server Console
All the commands referenced in Table 3.2 can alternatively take the bundle id as a parameter (instead of the bundle-symbolic-name). The bundle id is a numeric ID that the OSGi runtime assigns to the bundle during platform initialization. The ID might vary from instance to instance of the platform, but users might find it easier to input than having to enter the entire bundle symbolic name. Examples of how to determine and use the bundle id are given later in this chapter.
Rarely does a single OSGi console command answer all the questions on why a plug-in is not loading or operating as expected. The following sections explain in greater detail how you can use each of these commands and the results you can expect to see from executing such commands.
diag <bundle-symbolic-name>
This is one of the most valuable commands in your arsenal and will likely be the one you’ll use most frequently when diagnosing issues. You can use this command to determine whether a bundle is resolved within the OSGi platform. The status returned by this command will be one of the following:
- No unresolved constraints
- Unresolved constraint
If No unresolved constraints is the returned status, it suggests that the system has recognized the bundle and that all dependencies of the bundle are satisfied. When an Unresolved constraint status is returned, it suggests that one or more bundles or packages that the bundle requires are missing or cannot be loaded. It is worth noting here that a bundle might still fail to start even though the OSGi console reports that the bundle has been resolved. If a bundle fails to start and is resolved, some code in the bundle’s activator likely is failing (throwing an exception).
Sample usage:
tell http osgi diag com.ibm.xsp.core
Listing 3.8 shows the typical output of running the diag command against the com.ibm.xsp.core plug-in.
Listing 3.8. Result of Running the diag Command Against a Specific Bundle—Successful Case
> tell http osgi diag com.ibm.xsp.core 10/17/2011 09:43:14 PM initial@reference:file:../../shared/eclipse/plugins/com.ibm.xsp. core_8.5.3.20110629-1645/[119] 10/17/2011 09:43:14 PM No unresolved constraints.
In this case, the diag command reports that there were No unresolved constraints against the entered bundle symbolic name—in other words, the system recognizes the given bundle. Upon closer examination, the user can obtain further information about the bundle in question. It can determine where the bundle being used by the platform is installed, and the platform-assigned bundle id can also be obtained.
From reading the console output, the user can see that the bundle is installed to ../../shared/eclipse/plugins/com.ibm.xsp.core_8.5.3.20110629-1645. The location specified is relative to the osgi/rcp/eclipse directory, which is a child of the Domino program directory. In this case, the console output indicates that the plug-in is installed at: <domino program directory>/osgi/shared/eclipse/plugins.
Finally, the output states the platform-assigned bundle id for the specified bundle. 119 is the id assigned to this bundle in this example. As stated previously, the OSGi commands listed here can use the bundle id interchangeably. In this example, executing the following command has identical output to that in Listing 3.8.
Sample usage:
tell http osgi diag 119
Listing 3.9 shows sample output of running the diag command in an unsuccessful scenario.
Listing 3.9. Result of Running the diag Command Against a Specific Bundle—Error Case
> tell http osgi diag com.ibm.xsp.extlib.sbt 09/09/2011 04:05:51 PM update@../../../data/domino/workspace/applications/eclipse/plugins/com. ibm.xsp.extlib.sbt_8.5.3.201108111413.jar [116] 09/09/2011 04:05:51 PM Direct constraints which are unresolved: 09/09/2011 04:05:51 PM Missing host com.ibm.xsp.extlib_0.0.0.
In Listing 3.9, you can see that the OSGi platform reports that the bundle in question is not resolved as a result of a missing dependency. We can see from the console output that the OSGi platform has actually found the bundle that we are looking for (com.ibm.xsp.extlib.sbt), but as one of the bundles that com.ibm.xsp.extlib.sbt depends on is not resolved, the com.ibm.xsp.extlib.sbt bundle does not get resolved itself. Looking a little more closely at the console output, we can determine the following:
The bundle com.ibm.xsp.extlib.sbt is installed at ../../../data/domino/workspace/applications/eclipse/plugins/com.ibm.xsp.extlib.sbt_8.5.3.201108111413.jar. We now know that this path is relative to the <domino program directory>/osgi/rcp/eclipse directory. Hence, we can deduce that com.ibm.extlib.sbt is installed at the <domino program directory>/data/domino/workspace/applications/eclipse/plugins/ directory.
The OSGi platform–assigned bundle id for this bundle is 116.
One other tidbit of information can be extracted from the console output, in this case. The final line of the output tells us that the host is missing:
Missing host com.ibm.xsp.extlib_0.0.0
This tells us that the bundle we are looking for (com.ibm.xsp.extlib.sbt) is, in fact, a plug-in fragment, and the unresolved constraint (com.ibm.xsp.extlib) is the host plug-in.
ss, ss <bundle-symbolic-name>, or ss <bundle-name-prefix>
Similar to the diag command, this command quickly determines the status of a particular bundle—or all the bundles installed in the platform. Users can optionally specify a bundle name or a bundle name prefix to get the status of specific bundles. The returned status shows the bundle id, state, and bundle name of all bundles. In many situations, this command is just as useful as the diag command because it also reports the status of a bundle. This command does not tell the user why a particular bundle is not loading, but it does tell the user the state of a bundle.
Sample usage:
tell http osgi ss
Listing 3.10 shows the result of running the ss command without any parameters.
Listing 3.10. Result of Running the ss Command Without Any Bundle Name Parameter
> tell http osgi ss 09/09/2011 01:46:07 PM Framework is launched. 09/09/2011 01:46:07 PM id State Bundle 09/09/2011 01:46:07 PM 0 ACTIVE org.eclipse. osgi_3.4.3.R34x_v20081215-1030-RCP20110624-1648 09/09/2011 01:46:07 PM Fragments=57, 76, 88, 89, 235 09/09/2011 01:46:07 PM 1 RESOLVED org.eclipse.equinox. event_1.1.0.v20080225 09/09/2011 01:46:07 PM Fragments=32 09/09/2011 01:46:07 PM 2 RESOLVED com.ibm.pvc.jndi.provider. java.nl_6.2.3.20110625-0109 09/09/2011 01:46:07 PM Master=71 09/09/2011 01:46:07 PM 3 RESOLVED com.ibm.eclipse.equinox. preferences.nl_6.2.3.20110624-1648 09/09/2011 01:46:07 PM Master=85 09/09/2011 01:46:07 PM 4 <<LAZY>> com.ibm.icu. base_3.8.1.v20080530 09/09/2011 01:46:07 PM 5 RESOLVED com.ibm.pvc.servlet. jsp_2.1.0.20110625-0109 09/09/2011 01:46:07 PM 6 RESOLVED org.apache.commons. logging_1.0.4.20110625-0109
Listing 3.10 lists a subset of the information that displays when this command is run in a normal server environment. However, the listing does show all the information needed to understand the output of the command.
The command outputs several important pieces of information about each bundle:
- Bundle-id—for example, 2, which is the OSGi platform–assigned ID of the bundle.
- Bundle state—for example, RESOLVED, which is the state of the bundle within the OSGi platform. A bundle can have one of seven states. Table 3.3 explains all of these.
- Bundle name—for example com.ibm.eclipse.equinox.preferences.nl_6.2.3.20110624-1648, which is the bundle symbolic name with its version information appended to the name.
- Master or Fragments—for example, Master=71. This data tells whether the bundle in question is a plug-in or a fragment. If the bundle specifies neither Master nor Fragments, it is automatically implied that the bundle is a plug-in bundle. The digits corresponding to the fragments or plug-ins are the OSGi platform–assigned bundle ids of the fragments or the master plug-in of the bundle in question.
Sample usage:
tell http osgi ss com.ibm.xsp.extlib
Listing 3.11 shows the result of running the ss command with a bundle prefix specified.
Listing 3.11. Result of Running the ss Command, Specifying a Bundle Prefix
> tell http osgi ss com.ibm.xsp.extlib 09/09/2011 02:25:36 PM Framework is launched. 09/09/2011 02:25:36 PM id State Bundle 09/09/2011 02:25:36 PM 108 RESOLVED com.ibm.xsp.extlib. conns_8.5.2.20110724 09/09/2011 02:25:36 PM Master=117 09/09/2011 02:25:36 PM 109 RESOLVED com.ibm.xsp.extlib. domino_8.5.2.201107241628 09/09/2011 02:25:36 PM Master=117 09/09/2011 02:25:36 PM 112 RESOLVED com.ibm.xsp.extlib. oneui_8.5.2.201107241628 09/09/2011 02:25:36 PM Master=117 09/09/2011 02:25:36 PM 115 RESOLVED com.ibm.xsp.extlib. stime_8.5.2.201107241628 09/09/2011 02:25:36 PM Master=117 09/09/2011 02:25:36 PM 117 ACTIVE com.ibm.xsp. extlib_8.5.2.201107241628
Similar to Listing 3.10, Listing 3.11 shows the results of executing the ss command, only this time the command is passed a bundle symbolic name as a parameter. The ss command finds all bundles on the system that either start with the parameter or have a bundle symbolic name that is the same as the parameter. Listing 3.11 lists all the bundles, along with their bundle id and state.
Table 3.3 lists all the possible states of an OSGi bundle.
Table 3.3. OSGi Bundle States
|
State |
Description |
|
UNINSTALLED |
The bundle is uninstalled and is unusable. |
|
INSTALLED |
The bundle has been installed, but the platform has not yet resolved it. |
|
RESOLVED |
The bundle has been resolved and is in a position to be started.Note that it is still possible for the bundle to fail to start, even though it has been resolved by the environment. |
|
<<LAZY>> |
Similar to RESOLVED, the platform has resolved the bundle and is in a position to be started. The bundle is not yet ACTIVE because it has been configured (via its bundle manifest) to be initialized lazily–that is, only when another ACTIVE bundle references the bundle will it be activated. |
|
STARTING |
The bundle is in the process of starting. Either another bundle has specifically caused the bundle to start (by referring to a class within the bundle) or the user has manually started the bundle via the console. Rarely is a bundle in this state because it is transient. |
|
STOPPING |
The bundle is in the process of shutting down. Similar to STARTING, a bundle rarely is in this state. |
|
ACTIVE |
The bundle is running within the OSGi platform. |
Developers and administrators should be aware that, on the Domino server, the state of a bundle is not persisted from one session to the next—that is, after the HTTP task is restarted, any bundles that were started manually in the previous session must be started again. Luckily, the ss command has an argument for filtering all bundles in a given state. The ss command can filter the bundles based on their state, by appending -s [state] to the command syntax.
Sample usage:
tell http osgi ss -s active
Figure 3.5 shows the output of running the ss command with the -s active argument.
){kind=link}
)
Figure 3.5. Result of running the ss command in the Domino server console
start <bundle-symbolic-name>
This command requests that the platform manually start the specified bundle. Calling this command does not guarantee that the specified bundle will be started. An exception can still occur during bundle initialization that would cause the bundle initialization to fail. Performing an ss command after the start command reports the status of the bundle. This command is helpful when a new bundle has been installed on the server, but the administrator or developer is not in a position to restart the HTTP task to start the new bundle.
Sample usage:
tell http osgi start com.ibm.xsp.extlib.sbt
Figure 3.6 shows that, by running a combination of the ss and start commands, a bundle can be started and its state can be verified.
){kind=link}
)
Figure 3.6. Result of running the start and ss commands in the console
stop <bundle-symbolic-name>
This command tells the platform to stop the specified bundle. Users should be careful when calling this on a production environment. In some cases, it might not be possible for the platform to stop the bundle. If this is the case, the reason will be printed to the console.
Sample usage:
tell http osgi stop com.ibm.xsp.extlib.sbt
Figure 3.7 shows how running a combination of the ss and stop command stops a bundle and verifies its state.
){kind=link}
)
Figure 3.7. Result of running the start and ss commands in the console
b <bundle-symbolic-name>
This command prints all metadata relating to the specified bundle. The metadata includes imported packages, required bundles, exported packages, bundle location, and so on. This command is useful when the developer needs to quickly verify that the bundle loaded by the platform has the meta information that the developer believes it has.
Sample usage:
tell http osgi b com.ibm.xsp.extlib
Listing 3.12 shows a subset of the output from running the b command against a specified bundle.
Listing 3.12. Sample Result of Running the b Command Against a Specified Bundle
tell http osgi b com.ibm.xsp.extlib 09/09/2011 02:15:21 PM update@../../../data/domino/workspace/applications/eclipse/plugins/com. ibm.xsp.extlib_8.5.2.201107241628NTF.jar [117] 09/09/2011 02:15:21 PM Id=117, Status=<<LAZY>> Data Root=C:Program Files\IBM\Lotus\Domino\data\domino\workspace\.config org.eclipse.osgi\bundles\117\data 09/09/2011 02:15:21 PM No registered services. 09/09/2011 02:15:21 PM No services in use. 09/09/2011 02:15:21 PM Exported packages 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.client; version="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.client.data; version="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.client.dojo; version="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.client.dojo.fx; version="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.server; version="0.0.0"[exported]
headers <bundle-symbolic-name>
This command causes the OSGi header information for the specified bundle to be printed to the console. This command is convenient for checking information such as the packages that a specific bundle exports or the bundles that the specified bundle depends upon. All the information stored in the bundle’s manifest.mf file is printed to the console.
Sample usage:
tell http osgi headers com.ibm.xsp.extlib.sbt
Listing 3.13 shows the result of running the headers command on the Domino server console.
Listing 3.13. Sample Result of Running the headers Command with a Specified Bundle Name
tell http osgi headers com.ibm.xsp.extlib.sbt 09/09/2011 04:34:52 PM Bundle headers: 09/09/2011 04:34:52 PM Bundle-ClassPath = .,lib/httpclient- 4.0.1.jar,lib/httpcore-4.0.1.jar,lib/commons-codec-1.3.jar,lib/ oauth-20100527.jar,lib/ oauth-consumer- 20090617.jar,lib/oauth-consumer-20100527.jar,lib/oauth-httpclient4- 20090913.jar,lib/oauth-provider-20100527.jar 09/09/2011 04:34:52 PM Bundle-ManifestVersion = 2 09/09/2011 04:34:52 PM Bundle-Name = IBM Social Business Toolkit 09/09/2011 04:34:52 PM Bundle-SymbolicName = com.ibm.xsp.extlib. sbt;singleton:=true 09/09/2011 04:34:52 PM Bundle-Vendor = IBM 09/09/2011 04:34:52 PM Bundle-Version = 8.5.3.201108111413 09/09/2011 04:34:52 PM Export-Package = com.ibm.xsp.extlib.fragment,com.ibm.xsp.extlib.model,com.ibm.xsp.extlib. resources,com.ibm.xsp.extlib.sbt.activitystreams,com.ibm.xsp.extlib.sbt. activitystreams.entry,com.ibm.xsp. extlib.sbt.activitystreams.queue,com.ibm.xsp.extlib.sbt.connections,com. ibm.xsp.extlib.sbt.connections.meta,com.ibm.xsp.extlib.security. authorization,com.ibm.xsp.extlib.security .authorization.beans,com.ibm.xsp.extlib.security.oauth_10a,com.ibm.xsp. extlib.security.oauth_10a.servlet 09/09/2011 04:34:52 PM Fragment-Host = com.ibm.xsp.extlib 09/09/2011 04:34:52 PM Manifest-Version = 1.0
Listing 3.13 lists many different OSGi headers. You can find a full list of OSGi headers and their descriptions in the official OSGi specification: www.osgi.org/download/r4v43/r4.core.pdf.
help
This command tells the OSGi platform to print all commands that it supports, along with a short description of each command.
Sample usage:
tell http osgi help
Figure 3.8 shows the sample output from running the help OSGi command on the Domino server console.
){kind=link}
)
Figure 3.8. Result of running the help command in the console