earlier than delving into the inner workings of the OSGi console, it's most appropriate to in short clarify OSGi. OSGi stands for Open capabilities Gateway initiative framework. This framework allows for software to be written and completed as unbiased components. In OSGi-talk, these add-ons are known as bundles. OSGi is utilized in a wide range of purposes, from customer courses comparable to Eclipse and IBM Lotus Notes, to cell phones, to server purposes comparable to IBM Lotus Domino. because of their modular nature, OSGi bundles can also be began, stopped, and debugged on someone groundwork, without the need for stopping or restarting the total platform. each the Domino server and the Notes customer use Eclipse’s implementation of OSGi (Equinox) as their OSGi runtime platform.
OSGi became introduced to the Domino platform in unlock eight.5.2. in consequence, in Domino 8.5.2, the XPages runtime became repackaged to run as OSGi bundles (instead of simply an everyday collection of Java JARS), often known as Eclipse plug-ins.
The OSGi console makes it possible for for the enter of instructions that the OSGi platform then performs. The platform posts the results of such instructions again to the console. The OSGi platform itself has a whole host of commands that can simplify the troubleshooting of issues. The OSGi console can help developers in constructing XPages controls and applications, as well as helping support personnel in diagnosing runtime issues. builders who prolong the XPages runtime by using growing libraries will find the OSGi console commands to be a very potent tool in inspecting complications. The OSGi console is of specific use when the developer/administrator should recognize even if particular person plug-ins (or units of plug-ins) are loading accurately or which version of a plug-in is in use.
As mentioned previous, OSGi is embedded inside each the Notes customer and the Domino server. depending on the place your XPages utility is operating (no matter if on the client or the server), your system of getting access to the OSGi console will range. They start through explaining a way to entry the OSGi console on the Domino server.
OSGi is embedded within the HTTP task on the Domino server, consequently, the OSGi console is all started immediately every time the HTTP assignment is began. OSGi console commands are routed to the OSGi console by way of the HTTP project. it really is, when getting into an OSGi console command on the Domino server, the user must tell the HTTP task to route the designated command to the OSGi console—for example:tell http osgi <<command>>
right here, <<command>> is the identify of the OSGi console command. Any OSGi command will also be carried out the use of the previous syntax.
When it involves OSGi instructions, every developer and administrator should still know a few rudimentary instructions. These instructions will also be your “go to” commands when complications come up—say, in the event you suspect bundle loading could be an element. Even when you don't suppose that bundle loading is the issue, it is often superior to first confirm that the bundle is really loaded earlier than continuing with other debugging recommendations.
desk three.2 lists some of the more well-known OSGi commands that can be found to use for diagnosing plug-in considerations on the Domino server (and additionally the Notes customer). In desk 3.2, bundle-symbolic-name is referenced substantially. this is the identify wherein the OSGi platform references bundles. bundle-symbolic-identify correlates without delay to the Bundle-SymbolicName happen header, commonly stated because the plug-in name.desk 3.2. OSGi Console instructions
tell http osgi diag <bundle-symbolic-identify>
Diagnoses the popularity of the bundle whose identify is provided. Determines no matter if the bundle is resolved and, if no longer, states why the bundle isn't resolved.
inform http osgi ss <bundle-symbolic-name>
Lists the reputation of all bundles within the system. Optionally, a symbolic name or a symbolic identify prefix will also be offered to gain the reputation of a particular bundle or a subset of bundles.
inform http osgi delivery <bundle-symbolic-name>
starts the bundle with the designated symbolic identify.
inform http osgi stop <bundle-symbolic-name>
Stops the bundle with the particular symbolic identify.
tell http osgi b <bundle-symbolic-name>
Prints metadata regarding the specific bundle.
tell http osgi headers <bundle-symbolic-name>
Lists the OSGi headers for the targeted bundle.
inform http osgi support
Lists all of the OSGi command available on the server, along with some text describing every command.
all the instructions listed in desk three.2 will also be entered via the Domino server console, with the results of such commands being printed lower back to the console, as illustrated in figure 3.4.
figure three.four. operating an OSGi command on the Domino Server Console
all the commands referenced in table three.2 can alternatively take the bundle identification as a parameter (as an alternative of the bundle-symbolic-identify). The bundle identity is a numeric identification that the OSGi runtime assigns to the bundle during platform initialization. The id may vary from instance to illustration of the platform, but users might locate it simpler to input than having to enter the complete bundle symbolic identify. Examples of the way to examine and use the bundle identity are given later during this chapter.
infrequently does a single OSGi console command answer the entire questions about why a plug-in isn't loading or working as anticipated. right here sections explain in improved detail the right way to use every of these instructions and the consequences you can expect to peer from executing such instructions.diag <bundle-symbolic-identify>
here is one of the crucial valuable commands for your arsenal and should likely be the one you’ll use most often when diagnosing issues. you can use this command to determine whether a bundle is resolved inside the OSGi platform. The reputation lower back by using this command should be certainly one of right here:
If No unresolved constraints is the returned repute, it means that the device has recognized the bundle and that every one dependencies of the bundle are convinced. When an Unresolved constraint reputation is lower back, it suggests that one or extra bundles or applications that the bundle requires are lacking or cannot be loaded. it's price noting here that a bundle might nevertheless fail to delivery however the OSGi console reviews that the bundle has been resolved. If a bundle fails to birth and is resolved, some code in the bundle’s activator doubtless is failing (throwing an exception).
sample usage:inform http osgi diag com.ibm.xsp.core
checklist 3.8 indicates the usual output of running the diag command towards the com.ibm.xsp.core plug-in.list three.eight. outcomes of working the diag Command in opposition t a specific Bundle—a success Case > tell http osgi diag com.ibm.xsp.core 10/17/2011 09:43:14 PM preliminary@reference:file:../../shared/eclipse/plugins/com.ibm.xsp. core_8.5.three.20110629-1645/ 10/17/2011 09:forty three:14 PM No unresolved constraints.
in this case, the diag command stories that there have been No unresolved constraints in opposition t the entered bundle symbolic identify—in different words, the system recognizes the given bundle. Upon nearer examination, the user can gain extra advice concerning the bundle in query. it may well investigate where the bundle being used by way of the platform is put in, and the platform-assigned bundle identity can even be got.
From reading the console output, the consumer can see that the bundle is put in to ../../shared/eclipse/plugins/com.ibm.xsp.core_8.5.three.20110629-1645. The area specified is relative to the osgi/rcp/eclipse listing, which is a toddler of the Domino program directory. in this case, the console output shows that the plug-in is installed at: <domino application listing>/osgi/shared/eclipse/plugins.
eventually, the output states the platform-assigned bundle id for the specified bundle. 119 is the identification assigned to this bundle in this instance. As mentioned prior to now, the OSGi instructions listed here can use the bundle id interchangeably. during this example, executing the following command has similar output to that in checklist three.eight.
sample usage:tell http osgi diag 119
checklist three.9 suggests sample output of running the diag command in an unsuccessful state of affairs.record three.9. effect of operating the diag Command towards a particular Bundle—Error Case > tell http osgi diag com.ibm.xsp.extlib.sbt 09/09/2011 04:05:fifty one PM replace@../../../statistics/domino/workspace/functions/eclipse/plugins/com. ibm.xsp.extlib.sbt_8.5.three.201108111413.jar  09/09/2011 04:05:fifty one PM Direct constraints which can be unresolved: 09/09/2011 04:05:51 PM lacking host com.ibm.xsp.extlib_0.0.0.
In checklist three.9, you can see that the OSGi platform reports that the bundle in query isn't resolved as a result of a lacking dependency. they are able to see from the console output that the OSGi platform has basically discovered the bundle that they are seeking for (com.ibm.xsp.extlib.sbt), however as one of the crucial bundles that com.ibm.xsp.extlib.sbt is dependent upon is not resolved, the com.ibm.xsp.extlib.sbt bundle does not get resolved itself. searching a little extra carefully at the console output, they will examine here:
The bundle com.ibm.xsp.extlib.sbt is put in at ../../../information/domino/workspace/applications/eclipse/plugins/com.ibm.xsp.extlib.sbt_220.127.116.11108111413.jar. They now know that this path is relative to the <domino software directory>/osgi/rcp/eclipse listing. hence, they will deduce that com.ibm.extlib.sbt is put in on the <domino application directory>/facts/domino/workspace/applications/eclipse/plugins/ directory.
The OSGi platform–assigned bundle id for this bundle is 116.
One different tidbit of information can also be extracted from the console output, during this case. The remaining line of the output tells us that the host is lacking:lacking host com.ibm.xsp.extlib_0.0.0
This tells us that the bundle they are trying to find (com.ibm.xsp.extlib.sbt) is, basically, a plug-in fragment, and the unresolved constraint (com.ibm.xsp.extlib) is the host plug-in.ss, ss <bundle-symbolic-identify>, or ss <bundle-name-prefix>
corresponding to the diag command, this command right away determines the fame of a selected bundle—or all the bundles put in within the platform. users can optionally specify a bundle name or a bundle identify prefix to get the repute of certain bundles. The again fame shows the bundle identification, state, and bundle name of all bundles. in many situations, this command is just as valuable because the diag command since it also experiences the repute of a bundle. This command doesn't inform the user why a specific bundle is not loading, nonetheless it does tell the person the state of a bundle.
pattern usage:inform http osgi ss
record 3.10 suggests the outcomes of running the ss command without any parameters.list 3.10. outcome of working the ss Command without any Bundle identify Parameter > tell http osgi ss 09/09/2011 01:46:07 PM Framework is launched. 09/09/2011 01:forty six:07 PM id State bundle09/09/2011 01:46:07 PM 0 lively org.eclipse. osgi_3.4.3.R34x_v20081215-1030-RCP20110624-1648 09/09/2011 01:46:07 PM Fragments=fifty seven, 76, 88, 89, 235 09/09/2011 01:forty six:07 PM 1 RESOLVED org.eclipse.equinox. event_1.1.0.v20080225 09/09/2011 01:forty six:07 PM Fragments=32 09/09/2011 01:46:07 PM 2 RESOLVED com.ibm.pvc.jndi.issuer. java.nl_6.2.three.20110625-0109 09/09/2011 01:forty six:07 PM grasp=71 09/09/2011 01:forty six:07 PM 3 RESOLVED com.ibm.eclipse.equinox. preferences.nl_6.2.three.20110624-1648 09/09/2011 01:forty six:07 PM grasp=eighty five 09/09/2011 01:46:07 PM 4 <<LAZY>> com.ibm.icu. base_3.8.1.v20080530 09/09/2011 01:forty six:07 PM 5 RESOLVED com.ibm.pvc.servlet. jsp_18.104.22.16810625-0109 09/09/2011 01:forty six:07 PM 6 RESOLVED org.apache.commons. logging_1.0.four.20110625-0109
listing 3.10 lists a subset of the tips that shows when this command is run in a normal server ambiance. although, the checklist does exhibit the entire tips needed to remember the output of the command.
The command outputs a few important items of suggestions about each and every bundle:
pattern usage:inform http osgi ss com.ibm.xsp.extlib
list 3.eleven suggests the influence of running the ss command with a bundle prefix special.checklist three.11. outcomes of working the ss Command, Specifying a Bundle Prefix > inform http osgi ss com.ibm.xsp.extlib 09/09/2011 02:25:36 PM Framework is launched. 09/09/2011 02:25:36 PM identity State Bundle 09/09/2011 02:25:36 PM 108 RESOLVED com.ibm.xsp.extlib. conns_22.214.171.12410724 09/09/2011 02:25:36 PM master=117 09/09/2011 02:25:36 PM 109 RESOLVED com.ibm.xsp.extlib. domino_126.96.36.199107241628 09/09/2011 02:25:36 PM grasp=117 09/09/2011 02:25:36 PM 112 RESOLVED com.ibm.xsp.extlib. oneui_188.8.131.52107241628 09/09/2011 02:25:36 PM grasp=117 09/09/2011 02:25:36 PM a hundred and fifteen RESOLVED com.ibm.xsp.extlib. stime_184.108.40.206107241628 09/09/2011 02:25:36 PM grasp=117 09/09/2011 02:25:36 PM 117 energetic com.ibm.xsp. extlib_220.127.116.11107241628
corresponding to record three.10, listing 3.eleven suggests the effects of executing the ss command, most effective this time the command is handed a bundle symbolic name as a parameter. The ss command finds all bundles on the gadget that both delivery with the parameter or have a bundle symbolic identify that is a similar because the parameter. checklist three.eleven lists the entire bundles, along with their bundle id and state.
table 3.3 lists all of the viable states of an OSGi bundle.desk three.three. OSGi Bundle States
The bundle is uninstalled and is unusable.
The bundle has been installed, however the platform has now not yet resolved it.
The bundle has been resolved and is equipped to be all started.notice that it remains possible for the bundle to fail to delivery, although it has been resolved through the environment.
corresponding to RESOLVED, the platform has resolved the bundle and is able to be begun. The bundle isn't yet active since it has been configured (via its bundle show up) to be initialized lazily–that's, only when an additional lively bundle references the bundle will it be activated.
The bundle is within the procedure of starting. both a further bundle has specifically led to the bundle to birth (by using regarding a class within the bundle) or the user has manually started the bundle by means of the console. infrequently is a bundle during this state since it is transient.
The bundle is within the procedure of shutting down. akin to beginning, a bundle hardly is during this state.
The bundle is working inside the OSGi platform.
builders and directors may still be aware that, on the Domino server, the state of a bundle isn't endured from one session to the subsequent—it really is, after the HTTP task is restarted, any bundles that have been begun manually within the previous session must be started once more. fortuitously, 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 way of appending -s [state] to the command syntax.
pattern utilization:inform http osgi ss -s active
determine 3.5 shows the output of running the ss command with the -s energetic argument.
determine 3.5. outcome of working the ss command within the Domino server consolebeginning <bundle-symbolic-name>
This command requests that the platform manually birth the exact bundle. Calling this command does not make sure that the designated bundle will be began. An exception can nonetheless happen right through bundle initialization that might trigger the bundle initialization to fail. Performing an ss command after the delivery command studies the fame of the bundle. This command is positive when a new bundle has been installed on the server, but the administrator or developer is not ready to restart the HTTP task to birth the brand new bundle.
pattern usage:inform http osgi delivery com.ibm.xsp.extlib.sbt
figure 3.6 shows that, via working a mix of the ss and begin instructions, a bundle will also be started and its state can also be verified.
determine 3.6. outcome of running the beginning and ss commands in the consolestop <bundle-symbolic-name>
This command tells the platform to stop the specific bundle. clients should be cautious when calling this on a construction atmosphere. In some cases, it might not be viable for the platform to stop the bundle. If here is the case, the cause could be printed to the console.
pattern usage:inform http osgi cease com.ibm.xsp.extlib.sbt
determine three.7 shows how working a mixture of the ss and forestall command stops a bundle and verifies its state.
determine three.7. influence of working the beginning and ss commands in the consoleb <bundle-symbolic-identify>
This command prints all metadata relating to the specified bundle. The metadata comprises imported programs, required bundles, exported packages, bundle region, and the like. This command is useful when the developer needs to straight away verify that the bundle loaded through the platform has the meta information that the developer believes it has.
sample usage:tell http osgi b com.ibm.xsp.extlib
checklist 3.12 indicates a subset of the output from operating the b command towards a particular bundle.list three.12. sample effect of running the b Command towards a detailed Bundle inform http osgi b com.ibm.xsp.extlib 09/09/2011 02:15:21 PM update@../../../information/domino/workspace/applications/eclipse/plugins/com. ibm.xsp.extlib_18.104.22.168107241628NTF.jar  09/09/2011 02:15:21 PM id=117, repute=<<LAZY>> facts Root=C:program information\IBM\Lotus\Domino\facts\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 capabilities in use. 09/09/2011 02:15:21 PM Exported programs 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.movements.client; edition="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.movements.customer.records; version="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.client.dojo; edition="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.moves.client.dojo.fx; edition="0.0.0"[exported] 09/09/2011 02:15:21 PM com.ibm.xsp.extlib.actions.server; edition="0.0.0"[exported] headers <bundle-symbolic-identify>
This command causes the OSGi header assistance for the distinct bundle to be printed to the console. This command is easy for checking advice such as the programs that a selected bundle exports or the bundles that the specified bundle depends upon. all of the assistance saved in the bundle’s show up.mf file is printed to the console.
sample usage:tell http osgi headers com.ibm.xsp.extlib.sbt
listing 3.13 suggests the outcomes of working the headers command on the Domino server console.checklist 3.13. pattern effect of working the headers Command with a certain Bundle identify tell http osgi headers com.ibm.xsp.extlib.sbt 09/09/2011 04:34:52 PM Bundle headers: 09/09/2011 04:34:fifty two PM Bundle-ClassPath = .,lib/httpclient- 4.0.1.jar,lib/httpcore-four.0.1.jar,lib/commons-codec-1.three.jar,lib/ oauth-20100527.jar,lib/ oauth-customer- 20090617.jar,lib/oauth-client-20100527.jar,lib/oauth-httpclient4- 20090913.jar,lib/oauth-issuer-20100527.jar 09/09/2011 04:34:52 PM Bundle-ManifestVersion = 2 09/09/2011 04:34:52 PM Bundle-identify = IBM Social business Toolkit 09/09/2011 04:34:fifty two PM Bundle-SymbolicName = com.ibm.xsp.extlib. sbt;singleton:=true 09/09/2011 04:34:fifty two PM Bundle-vendor = IBM 09/09/2011 04:34:52 PM Bundle-version = eight.5.3.201108111413 09/09/2011 04:34:52 PM Export-package = com.ibm.xsp.extlib.fragment,com.ibm.xsp.extlib.mannequin,com.ibm.xsp.extlib. elements,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.safety. authorization,com.ibm.xsp.extlib.safety .authorization.beans,com.ibm.xsp.extlib.protection.oauth_10a,com.ibm.xsp. extlib.protection.oauth_10a.servlet 09/09/2011 04:34:52 PM Fragment-Host = com.ibm.xsp.extlib 09/09/2011 04:34:fifty two PM manifest-edition = 1.0
listing three.13 lists various OSGi headers. that you could find a full list of OSGi headers and their descriptions within the legitimate OSGi specification: www.osgi.org/down load/r4v43/r4.core.pdf.aid
This command tells the OSGi platform to print all commands that it supports, along with a short description of each and every command.
pattern usage:tell http osgi assist
determine three.8 shows the sample output from working the assist OSGi command on the Domino server console.
figure 3.8. influence of operating the help command in the console