+

Search Tips   |   Advanced Search

Debugging bundles at run time using the command-line console

The OSGi Applications command-line console is a set of wsadmin commands that we can use to explore or debug a specific set of bundles running on an application server. As an aid to debugging applications in a test environment, the console also includes commands to start and stop bundles.

You can explore or debug bundles by examining the contents of OSGi frameworks. A framework contains a collection of bundles, together with the packages and services associated with the bundles. There are two types of framework:

Isolated framework

An isolated framework contains the bundles that are defined exclusively for a specific application; each OSGi application runs in its own isolated framework. In a network deployment environment, there is one isolated framework for each server on which the application is installed. If an application includes one or more composite bundles, either as part of the application, or as an extension to the application, there is a separate isolated framework for each composite bundle.

Share bundle framework

There is a shared bundle framework per server, containing all the shared bundles that are available to the applications that are installed on that server. If the applications indirectly reference one or more composite bundles through package dependencies, there is a shared bundle framework for each composite bundle.

To work with a framework currently running, you first connect to the framework.

  1. Start the OSGi Applications command-line console.

    At a command prompt, run the osgiApplicationConsole.bat command (for Windows systems) or the osgiApplicationConsole.sh command (for Linux systems). You can run this command from the app_server_root/bin directory or from any profile_root/bin directory. The command takes the following optional parameters:

    -h

    The host name of the target machine. For example, machine1.hursley.ibm.com.

    -o

    The port number of the SOAP port of the target server. For example, 8880.

    -u

    The user ID, if the wsadmin connection is secured.

    -p

    The password, if the wsadmin connection is secured.

    For example: 

    app_server_root/bin/osgiApplicationConsole -h machine1.hursley.ibm.com -o 8880
    The wsadmin command prompt is displayed. This instance of wsadmin recognizes OSGi Applications console commands.

  2. Connect to an available framework.

    Use connect command to connect to a specific framework.

    If you know the framework name and version number, and the node and server on which the framework is running, we can use this information to connect. For example: 

    wsadmin>connect("com.ibm.ws.eba.helloWorldService.eba", "1.0.0", "wasNode1", "server1")

    Alternatively, use the list command to list all available frameworks and to provide a unique ID for each framework, then use this ID to connect. For example:

    1. List all available frameworks: 
      wsadmin>list()
      If you are connecting to an individual application server, this command might generate the following system response: 
      ID   Bundle                                Version  Node      Server
0    SharedBundles                         7.0.0    wasNode1  server1
1    com.ibm.ws.eba.helloWorldService.eba 1.0.0    wasNode1  server1
2    com.ibm.ws.eba.obr.fep.eba5.eba      1.0.0    wasNode1  server1
3    com.ibm.ws.eba.wab.componenttest      1.0.0    wasNode1  server1

    2. Connect to the com.ibm.ws.eba.helloWorldService.eba framework: 
      wsadmin>connect(1)
      If the command completes successfully it generates the following system responses: 
      CWSAJ0035I: Connecting to framework com.ibm.ws.eba.helloWorldService.eba_1.0.0 
on node wasNode1 and server server1.
CWSAJ0036I: Successfully connected to framework com.ibm.ws.eba.helloWorldService.eba_1.0.0.

    To connect to a different framework, run the connect command again. You do not need to disconnect from one framework before connecting to another framework.

  3. Work with the connected framework.

    Use one or more of the following commands to work with the framework to which you are connected:

    • List all available frameworks, and indicate the currently connected framework.

      Use the list command: 

      wsadmin>list()
      This command might generate the following system response: 
      ID   Bundle                                Version  Node      Server
0    SharedBundles                         7.0.0    wasNode1  server1
1    com.ibm.ws.eba.helloWorldService.eba 1.0.0    wasNode1  server1  <== Connected
2    com.ibm.ws.eba.obr.fep.eba5.eba      1.0.0    wasNode1  server1
3    com.ibm.ws.eba.wab.componenttest      1.0.0    wasNode1  server1

    • Display summary information about each of the bundles in the framework.

      Use the ss command: 

      wsadmin>ss()

      "ss" stands for "short status". This command might generate the following system response: 

      ID      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.6.1.R36x_v20100806
1       ACTIVE      com.ibm.samples.websphere.osgi.blog.app_1.0.0
2       ACTIVE      com.ibm.samples.websphere.osgi.blog_1.0.0
3       ACTIVE      com.ibm.samples.websphere.osgi.blog.persistence_1.0.0
4       ACTIVE      com.ibm.samples.websphere.osgi.blog.web_1.0.0
5       ACTIVE      com.ibm.samples.websphere.osgi.blog.api_1.0.0

    • Display comprehensive information about all of the bundles in the framework, and the services that they register or consume.

      Use the bundles command: 

      wsadmin>bundles()
      This command might generate the following system response.

      Information about the bundles that you included in the application is listed as bundle 2 and subsequent bundles. Bundles 0 and 1 are system artifacts; do not modify or rely on these bundles. Although the detail for bundle 0 is not shown in the following example, this bundle typically generates much more information than the other bundles. 

      org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  Id=0, Status=ACTIVE  Location=System Bundle
...
com.ibm.samples.websphere.osgi.blog.app_1.0.0 [1]
  Id=1, Status=ACTIVE  Location=com.ibm.samples.websphere.osgi.blog.app_1.0.0
...
com.ibm.samples.websphere.osgi.blog_1.0.0 [2]
  Id=2, Status=ACTIVE  
Location=reference:file:/C:/IBM/WebSphere/AppServer/profiles/profile01/
installedEBAs/com.ibm.samples.websphere.osgi.blog.app_1.0.0/byValue/
98b31e7a-4375-45fa-be20-d34b06f5c8b8.3/3/
  Registered Services 
{com.ibm.samples.websphere.osgi.blog.api.BloggingService}={service.id=46, osgi.service.blueprint.compname=bloggingServiceComponent
}

{org.osgi.service.blueprint.container.BlueprintContainer}={osgi.blueprint.
container.symbolicname=com.ibm.samples.websphere.osgi.blog,service.id=47, osgi.blueprint.container.version=1.0.0}
  No services in use.
com.ibm.samples.websphere.osgi.blog.persistence_1.0.0 [3]
  Id=3, Status=ACTIVE  
Location=reference:file:/C:/IBM/WebSphere/AppServer/profiles/profile01/
installedEBAs/com.ibm.samples.websphere.osgi.blog.app_1.0.0/byValue/
98b31e7a-4375-45fa-be20-d34b06f5c8b8.1/1/
  Registered Services 
{javax.persistence.EntityManagerFactory}={osgi.unit.provider=org.apache.openjpa.
persistence.PersistenceProviderImpl,service.id=42,osgi.unit.name=blogExample, osgi.unit.version=1.3.0,org.apache.aries.jpa.container.managed=true,org.apache.
aries.jpa.default.unit.name=false}

{javax.persistence.EntityManagerFactory}={osgi.unit.provider=org.apache.openjpa.
persistence.PersistenceProviderImpl,service.id=43,org.apache.aries.jpa.proxy.factory=true, osgi.unit.name=blogExample,osgi.unit.version=1.3.0,org.apache.aries.jpa.container.managed=true, org.apache.aries.jpa.default.unit.name=false}

{com.ibm.samples.websphere.osgi.blog.persistence.api.BlogPersistenceService}={service.id=44, osgi.service.blueprint.compname=persistenceImpl}

{org.osgi.service.blueprint.container.BlueprintContainer}={osgi.blueprint.container.
symbolicname=com.ibm.samples.websphere.osgi.blog.persistence,service.id=45, osgi.blueprint.container.version=1.0.0}
  No services in use.
com.ibm.samples.websphere.osgi.blog.web_1.0.0 [4]
  Id=4, Status=ACTIVE  
Location=reference:file:/C:/IBM/WebSphere/AppServer/profiles/profile01/
installedEBAs/com.ibm.samples.websphere.osgi.blog.app_1.0.0/byValue/
98b31e7a-4375-45fa-be20-d34b06f5c8b8.2/2/
  Registered Services 
{javax.servlet.ServletContext}={service.id=48,osgi.web.contextpath=/blog, osgi.web.version=1.0.0,osgi.web.symbolicname=com.ibm.samples.websphere.osgi.blog.web}

{org.osgi.service.blueprint.container.BlueprintContainer}={osgi.blueprint.container.
symbolicname=com.ibm.samples.websphere.osgi.blog.web,service.id=49, osgi.blueprint.container.version=1.0.0}
  No services in use.
com.ibm.samples.websphere.osgi.blog.api_1.0.0 [5]
  Id=5, Status=ACTIVE  
Location=reference:file:/C:/IBM/WebSphere/AppServer/profiles/profile01/
installedEBAs/com.ibm.samples.websphere.osgi.blog.app_1.0.0/byValue/
98b31e7a-4375-45fa-be20-d34b06f5c8b8.0/0/
  No registered services.
  No services in use.

    • Display comprehensive information about a given bundle in the framework.

      Use the bundle command. Specify the ID of the bundle to examine. The bundle ID values are one of the outputs of the ss command.

      This command lists the information associated with the specified bundle. For example the bundle symbolic name, the bundle version, the services that the bundle registers, the services that are consumed by the bundle, and whether the bundle is a fragment or a host bundle.

      For example: 

      wsadmin>bundle(3)
      This command might generate the following system response: 
      com.ibm.samples.websphere.osgi.blog.persistence_1.0.0 [3]
  Id=3, Status=ACTIVE  
Location=reference:file:/C:/IBM/WebSphere/AppServer/profiles/profile01/
installedEBAs/com.ibm.samples.websphere.osgi.blog.app_1.0.0/byValue/
98b31e7a-4375-45fa-be20-d34b06f5c8b8.1/1/
  Registered Services 
{javax.persistence.EntityManagerFactory}={osgi.unit.provider=org.apache.openjpa.
persistence.PersistenceProviderImpl,service.id=42,osgi.unit.name=blogExample, osgi.unit.version=1.3.0,org.apache.aries.jpa.container.managed=true,org.apache.
aries.jpa.default.unit.name=false}

{javax.persistence.EntityManagerFactory}={osgi.unit.provider=org.apache.openjpa.
persistence.PersistenceProviderImpl,service.id=43,org.apache.aries.jpa.proxy.factory=true, osgi.unit.name=blogExample,osgi.unit.version=1.3.0,org.apache.aries.jpa.container.managed=true, org.apache.aries.jpa.default.unit.name=false}

{com.ibm.samples.websphere.osgi.blog.persistence.api.BlogPersistenceService}={service.id=44, osgi.service.blueprint.compname=persistenceImpl}

{org.osgi.service.blueprint.container.BlueprintContainer}={osgi.blueprint.container.
symbolicname=com.ibm.samples.websphere.osgi.blog.persistence,service.id=45, osgi.blueprint.container.version=1.0.0}
  No services in use.
  No exported packages
  Imported Packages
  Imported Packages
    com.ibm.samples.websphere.osgi.blog.persistence.api; 
    version="1.0.0"<com.ibm.samples.websphere.osgi.blog.api_1.0.0 [3]>
    javax.persistence; version="1.1.0"<org.eclipse.osgi_3.6.1.R36x_v20100806 [3]>
  No fragment bundles
  No host bundles
  No named class spaces   Required bundles
    org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
    com.ibm.samples.websphere.osgi.blog.api_1.0.0 [5]

    • Display header information about a given bundle.

      Use the headers command. Specify the ID of the bundle to examine. The bundle ID values are one of the outputs of the ss command.

      For example: 

      wsadmin>headers(2)
      This command might generate the following system response: 
      Ant-Version = Apache Ant 1.7.1
Bundle-ActivationPolicy = lazy
Bundle-ManifestVersion = 2
Bundle-Name = Blog Core Services Bundle
Bundle-SymbolicName = com.ibm.samples.websphere.osgi.blog
Bundle-Vendor = IBM Bundle-Version = 1.0.0
Created-By = 2.4 (Your Corporation)
Import-Package = com.ibm.samples.websphere.osgi.logging;version="[1.0.0,1.1.0)", com.ibm.samples.websphere.osgi.blog.api;version="[1.0.0,1.1.0)", com.ibm.samples.websphere.osgi.blog.comment.persistence.api;version="[1.0.0,1.1.0)", com.ibm.samples.websphere.osgi.blog.persistence.api;version="[1.0.0,1.1.0)"
Manifest-Version = 1.0

    • Display information about the packages that are imported or exported by the framework.

      Use the packages command. Optionally, specify either or both of the following parameters to select a particular package or subset of packages:

      bundle ID

      Display information about the exported packages for this bundle.

      The bundle ID values are one of the outputs of the ss command.

      package name

      Display information about the specified package.

      Command syntax: 

      wsadmin>packages()
wsadmin>packages(bundle_id)
wsadmin>packages(package_name)

      Example using a bundle ID: 

      wsadmin>packages(5)
      This command might generate the following system response: 
      com.ibm.samples.websphere.osgi.blog.persistence.api; version="1.0.0"
<com.ibm.samples.websphere.osgi.blog.api_1.0.0 [5]>
  com.ibm.samples.websphere.osgi.blog_1.0.0 [2] imports
  com.ibm.samples.websphere.osgi.blog.persistence_1.0.0 [3] imports 
com.ibm.samples.websphere.osgi.blog.comment.persistence.api; version="1.0.0"
<com.ibm.samples.websphere.osgi.blog.api_1.0.0 [5]>
  com.ibm.samples.websphere.osgi.blog_1.0.0 [2] imports 
com.ibm.samples.websphere.osgi.blog.api; version="1.0.0"
<com.ibm.samples.websphere.osgi.blog.api_1.0.0 [5]>
  com.ibm.samples.websphere.osgi.blog_1.0.0 [2] imports
  com.ibm.samples.websphere.osgi.blog.web_1.0.0 [4] imports

      Example using a package name: 

      wsadmin>packages("com.ibm.samples.websphere.osgi.blog.comment.persistence.api")
      This command might generate the following system response: 
      com.ibm.samples.websphere.osgi.blog.comment.persistence.api; version="1.0.0"
<com.ibm.samples.websphere.osgi.blog.api_1.0.0 [5]>
  com.ibm.samples.websphere.osgi.blog_1.0.0 [2] imports

    • Display information about the services that are currently registered by the framework. For each service this information includes the service interfaces, the bundle that registered the service, and any bundles that consume the service.

      Use the services command. Optionally, specify either or both of the following parameters to select a particular service or subset of services:

      service ID

      Display information about a specified service.

      filter

      Display information about all services that match the filter.

      The filter must comply with the OSGi filter format as defined in section 3.2.7 of the OSGi Service Platform Release 4 Version 4.2 Core Specification.

      Command syntax: 

      wsadmin>services()
wsadmin>services(service_id)
wsadmin>services("(&(prop1=value_1)(prop2=value_2))")

      Example using a service ID: 

      wsadmin>services(2)
      This command might generate the following system response: 
      {org.osgi.service.packageadmin.PackageAdmin}={service.id=2, service.ranking=2147483647,service.vendor=Eclipse.org - Equinox, service.pid=0.org.eclipse.osgi.framework.internal.core.PackageAdminImpl}
  Registered by bundle: org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  Bundles using service:
    org.eclipse.osgi_3.6.1.R36x_v20100806 [0]

      Example using a single property filter: 

      wsadmin>services("(objectClass=org.osgi.service.packageadmin.PackageAdmin)")
      This command might generate the following system response: 
      {org.osgi.service.packageadmin.PackageAdmin}={service.id=2, service.ranking=2147483647,service.vendor=Eclipse.org - Equinox, service.pid=0.org.eclipse.osgi.framework.internal.core.PackageAdminImpl}
  Registered by bundle: org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  Bundles using service:
    org.eclipse.osgi_3.6.1.R36x_v20100806 [0]

      Example using a multiple property filter: 

      wsadmin>services("(&(objectClass=javax.resource.Referenceable)(ibm.private.jndi.object=true))")
      This command might generate the following system response: 
      {java.lang.reflect.InvocationHandler,com.ibm.websphere.rsadapter.WSDataSource,java.sql.Wrapper, javax.sql.CommonDataSource,javax.resource.Referenceable,javax.sql.DataSource}={service.id=35, osgi.jndi.service.name=jdbc/pgc,ibm.private.jndi.object=true}
  Registered by bundle: org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  No bundles using service.
{java.lang.reflect.InvocationHandler,com.ibm.websphere.rsadapter.WSDataSource,java.sql.Wrapper, javax.sql.CommonDataSource,javax.resource.Referenceable,javax.sql.DataSource}={service.id=36, osgi.jndi.service.name=jdbc/DefaultEJBTimerDataSource,ibm.private.jndi.object=true}
  Registered by bundle: org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  No bundles using service.
{java.lang.reflect.InvocationHandler,com.ibm.websphere.rsadapter.WSDataSource,java.sql.Wrapper, javax.sql.CommonDataSource,javax.resource.Referenceable,javax.sql.DataSource}={service.id=39, osgi.jndi.service.name=jdbc/lrsched,ibm.private.jndi.object=true}
  Registered by bundle: org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  No bundles using service.
{javax.resource.Referenceable,javax.resource.cci.ConnectionFactory}={service.id=40, osgi.jndi.service.name=eis/jdbc/pgc_CMP,ibm.private.jndi.object=true}
  Registered by bundle: org.eclipse.osgi_3.6.1.R36x_v20100806 [0]
  No bundles using service.

    • Update the cached runtime information about the framework.

      It can take some time for the system to gather the runtime information about the framework and the bundles running within it. Therefore, when you run the osgiApplicationConsole command, the command-line console caches the runtime information. If we make changes to the currently selected framework, for example by updating or adding bundles, these changes are not reflected in the output of the command-line console commands until you run the refresh command.

      You can also update this runtime information by restarting the OSGi Applications command-line console. However, you then have to reconnect to the framework. It is quicker to use the refresh command.

      Command syntax: 

      wsadmin>refresh()

    • Stop a bundle.

      Use the stop command to stop the bundle specified by a given bundle ID. The bundle ID values are one of the outputs of the ss command.

      • The OSGi Applications command-line console is intended primarily as a method of debugging applications. In a production environment, you would normally use the administrative console or equivalent administrative commands to start and stop applications.

      • Do not use the stop command on any bundles under the shared bundle framework, on system bundles, or on the bundles that represent system artifacts (bundle ID 0 and 1), otherwise serious errors can result.

      For example: 

      wsadmin>stop(5)
      This command might generate the following system response: 
      CWSAJ0042I: Stopping Bundle com.ibm.samples.websphere.osgi.blog.api_1.0.0.
CWSAJ0034I: Bundle com.ibm.samples.websphere.osgi.blog.api stopped successfully.

    • Start a bundle.

      Use the start command to start the bundle specified by a given bundle ID. The bundle ID values are one of the outputs of the ss command.

      • The OSGi Applications command-line console is intended primarily as a method of debugging applications. In a production environment, you would normally use the administrative console or equivalent administrative commands to start and stop applications.

      • Do not use the start command on any bundles under the shared bundle framework, on system bundles, or on bundles that represent applications (bundle ID 0 and 1), otherwise serious errors can result.

      For example: 

      wsadmin>start(5)
      This command might generate the following system response: 
      CWSAJ0040I: Starting Bundle com.ibm.samples.websphere.osgi.blog.api_1.0.0.
CWSAJ0032I: Bundle com.ibm.samples.websphere.osgi.blog.api started successfully.

    • Display help information about the console commands.

      Use the help command to display a summary of the runtime commands and their uses.

      Command syntax: 

      wsadmin>help()
      This command generates the following system response: 
      CWSAJ0025I:      OSGi application console

Display commands: These commands work only if connected to a framework 
ss()                - This command gives the summary information about the installed bundles.
bundles()           - This command gives comprehensive information about the installed bundles.
packages()          - This command gives information about the imported/exported packages.
services()          - This command gives information about the registered Services.

bundle(<bundleID>)  - This command gives information about the specified bundle
headers(<bundleID>) - This command gives information about the headers associated with the 
                      specified bundle
packages(<bundle ID>) - This command gives information about the exported packages for this bundle.
packages(<package Name>) - This command gives information about the specified package.
services(<service ID>) - This command gives information about the specified service.
services(<OSGI Filter>) - This command gives information about the services matching the filter.

refresh() - This command refreshes the internal OSGi application console cache with the latest 
            information about the state of the framework.

Framework commands:

list() - This command lists the available frameworks that we can connect to.
connect(<Framework id>) - This command connects to the specified framework.
connect(<Bundle Name>, <Bundle Version>, <Node Name>, <Server Name>)
                 - This command connects to the specified framework.

Controlling Bundles:

start(<bundleID>) - This command starts the requested bundle.
stop(<bundleID>  - This command stops the requested bundle.


Parent topic: Debugging bundles at run time


Related concepts

  • OSGi application isolation and sharing
  • Composite bundles


    Related tasks

  • Extending a deployed OSGi application