Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop OSGi applications > Develop and deploying an OSGi application


Debug bundles at run time using the command-line console

We can use the wsadmin-based OSGi Applications command-line console to explore or debug the bundles associated with a specific OSGi application or shared bundle framework.


About this task

The OSGi Applications command-line console is a set of wsadmin commands that you 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.

Every OSGi application that is currently running is viewed by the command-line console as a separate framework. On each application server that is running an OSGi application, there is also one shared bundle framework.

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


Procedure

  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). We can run this command from the WAS_HOME/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: 

    WAS_HOME/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.

    You use the 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, you 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



    v 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



    v 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 artefacts; 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 v4.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 you 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 artefacts (bundle ID 0 and 1), because this can cause serious errors.

      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), because this can cause serious errors.

      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 you 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: Develop and deploying an OSGi application

Related concepts:

About OSGi Applications
OSGi application isolation and sharing

Related tasks:

Create a service bundle
Create a client bundle
Create an OSGi application
Deploy an OSGi application as a business-level application
Secure OSGi Applications

Related reference:

OSGi Applications: Troubleshooting tips
Task topic Feedback
Copyright IBM Corporation 2009, 2011. All Rights Reserved.
This information center is powered by Eclipse technology.

+

Search Tips   |   Advanced Search