4.2 dm Shell Command Reference

4.2 dm Shell Command Reference
Prev	4. The dm Shell	Next

This section contains reference information about the following dm Shell commands:

exit Command

Use the exit command to exit from the dm Shell session.

The exit command does not have any options.

bundle Command

Use the bundle command to manage the lifecycle of bundles deployed to @dms@ and to gather information about deployed bundles, such as diagnostic information, header information, and so on.

The following table lists the options you can specify for this command.

Table 4.2. Options of the bundle Command

Option	Descrption
list	Displays the list of bundles that are currently installed to the current dm Server instance. With the exception of a few kernel bundles and their services, which dm Server uses to administer the user region, none of the kernel is visible to user installed artifacts; rather, only the bundles installed in the user region are visible. Each bundle is identified by an internal `ID` which you can then use with the other `bundle` commands that manage a particular bundle, such as `start id`. The `list` command also displays the version of the bundle, along with its state, which is one of the following standard OSGi lifecycle states: Installed: The bundle is installed but its dependencies have not yet been resolved. Resolved: The bundle is resolved and you can now start it. Uninstalled: The bundle is uninstalled and you can not use it. Starting: The bundle is in the process of starting. Active: The bundle is running and you can now use it. Stopping: The bundle is in the process of stopping. Use one of the other `bundle` command to change the state of a bundle. For example, use the `bundle start id` command to change the state of a bundle from `Installed` to `Active`.
examine id	Displays detailed information about the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle. In addition to the information provided by the `bundle list` command (id, full name, version, and state), the `examine` command specifies whether the bundle includes a Spring application context (or is Spring Powered) and the exact physical location of the bundle JAR file. The `examine` also provides the full list of packages that the bundle imports, as well as the bundles that in turn export these imported packages. Finally, the command displays the packages that the current bundle exports, and then in turn the list of other installed bundles that are currently importing these exported packages.
start id	Starts the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle. To start a bundle, it must have already been resolved by dm Server, or in other words, be in the OSGi `Resolved` state. After dm Server successfully starts the bundle, it is listed in the `Active` state.
stop id	Stops the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle. When you stop a bundle, it goes from the OSGi `Active` state to the `Resolved` state, and you must re-start it if you want to use the application that the bundle contains.
refresh id	Updates the contents of the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle. Use this command if you have changed the contents of the bundle JAR file and you want to refresh the artifact as installed in the OSGi framework.
uninstall id	Uninstalls the specified bundle from dm Server. Use the `bundle list` command to get the internal id of a particular bundle. When the uninstall process is complete, the bundle does not show up in the list of bundles displayed by the `bundle list` command. If you want to use the application in the bundle, you must re-install it using the `install` command.
diag id	Provides diagnostic information about the specified bundle. In particular, this command displays information about the imported packages that dm Server could not resolve. Use the `bundle list` command to get the internal id of a particular bundle.
headers id	Displays the complete list of manifest headers of the specified bundle. Use the `bundle list` command to get the internal id of a particular bundle. The manifest headers include: `Import-Package`, `Module-Type`, `Bundle-SymbolicName`, and so on.

The following examples show how to use this command.

First, use the bundle list command to view all the installed bundles; note the last one that is in a Resolved state (and many entries have been removed for simplicity):

:> bundle list

Id   Name                                       Version                State 

0    org.eclipse.osgi                           3.5.1.R35x_v20091005   ACTIVE
1    com.springsource.region.user               0.0.0                  ACTIVE
2    org.springframework.aop                    3.0.0.RC1              RESOLVED
3    org.springframework.asm                    3.0.0.RC1              RESOLVED

(entries removed...)

60   swf-booking-mvc.war                        0.0.0                  RESOLVED

Then use the bundle start to start the swf-booking-mvc.war bundle:

:> bundle start 60

bundle swf-booking-mvc.war:0.0.0 started successfully

The following example shows how to view the headers of the swf-booking-mvc.war bundle (only the first few lines are shown):

:> bundle headers 60

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
Implementation-Title: swf-booking-mvc
Implementation-Version: 2.0.3.RELEASE
....

config Command

Use the config command to view and manage the configuration artifacts that have been installed to dm Server. A configuration artifact is simply a properties file that is associated with a user application that is contained in a bundle. Using configuration artifacts, you can manage the configuration of a user application completely separately from the bundle that contains the application.

The following table lists the options you can specify for this command.

Table 4.3. Options of the config Command

Option	Descrption
list	Lists the configuration artifacts that are currently installed in dm Server. The `list` command displays the full name of each installed configuration artifact, its version, and its current state. Configuration artifacts have similar lifecycles to other OSGi artifacts, such as bundles, and so the list of states in which a configuration can be in is the same as those of bundles; see the bundle command for the list of possible states.
examine name [version]	Displays information about the specified configuration artifact. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the `config list` command to view all configuration artifacts and versions currently installed in dm Server. A configuration artifact must be active for you to examine it; if it is not currently active, use `config start` to start it and thus change its state to `Active`. The command first displays the factory pid of the configuration artifact as well as the complete location of the bundle to which the configuration artifact is associated. The command then lists all the properties that make up the configuration, as well as their current value.
start name [version]	Starts the specified configuration artifact and makes it visible to the internal configuration sub-system of dm Server. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the `config list` command to view all configuration artifacts and versions currently installed in dm Server. Starting the configuration sets its state to `Active`.
stop name [version]	Stops the specified configuration artifact and makes it invisible to the internal configuration sub-system of dm Server. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the `config list` command to view all configuration artifacts and versions currently installed in dm Server. Stopping the configuration sets its state to `Resolved`.
refresh name [version]	Updates the contents of the specified configuration artifact to the internal configuration sub-system of dm Server. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the `config list` command to view all configuration artifacts and versions currently installed in dm Server. Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to dm Server and the associated bundle.
uninstall name [version]	Uninstalls the specified configuration artifact and make it completely unavailable to dm Server. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed. Use the `config list` command to view all configuration artifacts and versions currently installed in dm Server. Stopping the configuration removes it from dm Server's list of deployed artifacts and it will not show up when you perform a `config list`.

The following example shows how to use this command to list the installed configuration artifacts.

:> config list

Name                                      Version                          State
com.springsource.kernel                   0.0.0                           ACTIVE
com.springsource.kernel.jmxremote.access  0.0.0                           ACTIVE
com.springsource.kernel.region            0.0.0                           ACTIVE
com.springsource.kernel.users             0.0.0                           ACTIVE
com.springsource.osgi.medic               0.0.0                           ACTIVE
com.springsource.repository               0.0.0                           ACTIVE
com.springsource.server.repository.hosted 0.0.0                           ACTIVE

The next example shows how to refresh the configuration artifact com.springsource.osgi.medic:

:> config refresh com.springsource.osgi.medic

configuration com.springsource.osgi.medic:0.0.0 refreshed successfully

Finally, to view the properties of a configuration artifact, and their current values, use config examine:

:> config examine com.springsource.osgi.medic

Factory pid:     
Bundle Location: file:lib/kernel/com.springsource.kernel.shell-2.0.0.D-20091107203259.jar

Properties:
    dump.root.directory:
        serviceability/dump
    log.dump.bufferSize:
        10000
    log.dump.level:
        DEBUG
    log.dump.pattern:
        [%d{yyyy-MM-dd HH:mm:ss.SSS}] %-28.28thread %-64.64logger{64} %X{medic.eventCode} %msg %ex%n
    log.wrapSysErr:
        true
    log.wrapSysOut:
        true
    service.pid:
        com.springsource.osgi.medic

package Command

Use the package command to view the complete list of packages exported by all bundles installed to dm Server, as well as examine a particular exported package in more detail.

The following table lists the options you can specify for this command.

Table 4.4. Options of the package Command

Option Descrption

list Displays all the exported packages for all bundles in dm Server. In addition to the package name, the command displays the version of the exported package and the id of the bundle that contains the exported package. You can examine the bundle by using the command bundle examine id.

Option	Descrption
list	Displays all the exported packages for all bundles in dm Server. In addition to the package name, the command displays the version of the exported package and the `id` of the bundle that contains the exported package. You can examine the bundle by using the command `bundle examine id`.
examine name version	Displays details about the exported bundle. You must specify both the name of the exported package and its version; use `package list` to view the exact names and version. This command provides the following additional information about the exported package: The name and version of the bundle that exports the package. This means that the package name is explicitly listed in the bundle's `MANIFEST.MF` file as part of the `Export-Package` header. Any attributes that are part of the `Export-Package`, in addition to `version`. The directives that are part of the `Export-Package` header. A typical directive is `uses`, which declares up-front constraints on a number of other packages. The list of all bundles that import the package.

examine name version

Displays details about the exported bundle. You must specify both the name of the exported package and its version; use package list to view the exact names and version.

This command provides the following additional information about the exported package:

The name and version of the bundle that exports the package. This means that the package name is explicitly listed in the bundle's MANIFEST.MF file as part of the Export-Package header.
Any attributes that are part of the Export-Package, in addition to version.
The directives that are part of the Export-Package header. A typical directive is uses, which declares up-front constraints on a number of other packages.
The list of all bundles that import the package.

The following example shows how to list all the exported packages for all bundles installed on dm Server:

:> package list

Name                                          Version                   Providing Bundle

com.springsource.kernel.agent.dm              2.0.0.D-20091110110152    6  
com.springsource.kernel.artifact.bundle       2.0.0                     1  
com.springsource.kernel.artifact.library      2.0.0                     1  
com.springsource.kernel.core                  2.0.0.D-20091110110152    1  
com.springsource.kernel.deployer.app.spring   2.0.0.D-20091110110152    7  
com.springsource.kernel.deployer.core         2.0.0.D-20091110110152    1  
com.springsource.kernel.deployer.core.event   2.0.0.D-20091110110152    1  
com.springsource.kernel.dmfragment            2.0.0.D-20091110110152    16
com.springsource.kernel.install.artifact      2.0.0.D-20091110110152    1  
com.springsource.kernel.install.environment   2.0.0.D-20091110110152    1  
...
[data removed for clarity]

The following example shows how to examine a particular exported package:

:> package examine org.springframework.web.servlet 3.0.0.RC1

Providing Bundle: org.springframework.web.servlet 3.0.0.RC1 [55]

Attributes:

Directives:
    uses:
        javax.servlet, javax.servlet.http, org.springframework.beans,
        org.springframework.context, org.springframework.context.event,
        org.springframework.context.i18n, org.springframework.ui,
        org.springframework.ui.context, org.springframework.util,
        org.springframework.web.context, org.springframework.web.multipart
    x-equinox-ee:
        -1
    x-internal:
        false

Imported By:
    com.springsource.server.splash 2.0.0.D-20091110115520 [59] at [3.0.0, 3.1.0)
    com.springsource.server.repository.hosted-2.0.0.D-20091109225604-com.springsource.server.repository.hosted.web 2.0.0.D-20091109225604 [56] at [2.5.6, 3.1.0)
    org.springframework.js 2.0.8.RELEASE [54] at [2.5.6.SEC01, 3.1.0)
    com.springsource.server.admin.web 2.0.0.D-20091110115520 [50] at [3.0.0, 3.1.0)

par Command

Use the par command to view all the PARs currently installed in dm Server, view details about a particular PAR and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.

The following table lists the options you can specify for this command.

Table 4.5. Options of the par Command

Option	Descrption
list	Displays all the PARs that are currently installed in dm Server. The `list` command displays the full name of each installed PAR, its version, and its current state. PARs have similar lifecycles to other OSGi artifacts, such as bundles, and so the list of states in which a PAR can be in is the same as those of bundles; see the bundle command for the list of possible states.
examine name version	Displays information about the specified PAR; you are required to identify the PAR with both its name and its version. Use the `par list` command to view all installed PAR files and their versions. The command displays the following information: The current state of the PAR (see the bundle command for the full list of possible states). Whether the PAR is scoped. Scoping specifies whether dm Server should deploy the members of the PAR in their own scope; when scoping is disabled, dm Server deploys the artifacts into the global scope and they are accessible for access by all other artifacts. Whether the PAR is atomic. When a PAR is atomic, dm Server manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then dm Server starts all the PAR artifacts. If one artifact fails to start, then dm Server stops all other artifacts in the PAR. The individual members, or children, of the PAR. These could be other PARs, plans, bundles, configuration artifacts, and so on.
start name version	Starts the specified PAR. You must specify both the full name of the PAR as well as the version you want to start. Use the `par list` command to get the list of PARs currently installed in dm Server. To start a PAR, it must have already been resolved by dm Server, or in other words, be in the OSGi `Resolved` state. After dm Server successfully starts the PAR, it is listed in the `Active` state.
stop name version	Stops the specified PAR. You must specify both the full name of the PAR as well as the version you want to stop. Use the `par list` command to get the list of PARs currently installed in dm Server. When you stop a PAR, it goes from the OSGi `Active` state to the `Resolved` state, and you must re-start it if you want to use the application that the PAR contains.
refresh name version	Updates the contents of the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the `par list` command to this information. Use this command if you have changed the contents of the PAR file and you want to refresh the artifact as installed in the OSGi framework.
uninstall name version	Uninstalls the specified PAR. You must specify both the name and version of the PAR you want to refresh. Use the `par list` command to this information. When the uninstall process is complete, the PAR will not show up in the list of PARs displayed by the `par list` command. If you want to use the application in the PAR, you must re-install it using the `install` command.

The following example shows how to list the PARs that have been installed in dm Server:

:> par list

Name                                         Version                      State

com.springsource.server.repository.hosted    2.0.0.D-20091109225604          ACTIVE

The following example shows how to examine a particular PAR file:

:> par examine com.springsource.server.repository.hosted 2.0.0.D-20091109225604

State:  ACTIVE
Scoped: true
Atomic: true

Children:
    bundle com.springsource.server.repository.hosted.core 2.0.0.D-20091109225604
    bundle com.springsource.server.repository.hosted.web 2.0.0.D-20091109225604
    bundle com.springsource.server.repository.hosted-synthetic.context 2.0.0.D-20091109225604

Finally, the following example shows how to refresh an installed PAR file:

:> par refresh my.exciting.par 1.2.0

par my.exciting.par 1.2.0 refreshed successfully

plan Command

Use the plan command to view all the plans currently installed in dm Server, view details about a particular plan and manage its lifecycle, such as starting, stopping, refreshing, and uninstalling it.

The following table lists the options you can specify for this command.

Table 4.6. Options of the plan Command

Option	Descrption
list	Displays all the plans that are currently installed in dm Server. The `list` command displays the full name of each installed plan, its version, and its current state. Plans have similar lifecycles to other OSGi artifacts, such as bundles, and so the list of states in which a plan can be in is the same as those of bundles; see the bundle command for the list of possible states.
examine name version	Displays information about the specified plan; you are required to identify the plan with both its name and its version. Use the `plan list` command to view all installed plans and their versions. The command displays the following information: The current state of the plan (see the bundle command for the full list of possible states). Whether the plan is scoped. Scoping specifies whether dm Server should deploy the members of the plan in their own scope; when scoping is disabled, dm Server deploys the artifacts into the global scope and they are accessible for access by all other artifacts. Whether the plan is atomic. When a plan is atomic, dm Server manages the lifecycle of all its member artifacts as a single entity, which means if one artifact member is started, then dm Server starts all the plan artifacts. If one artifact fails to start, then dm Server stops all other artifacts in the plan. The individual members, or children, of the plan. These could be other plans, PARs, bundles, configuration artifacts, and so on.
start name version	Starts the specified plan. You must specify both the full name of the plan as well as the version you want to start. Use the `plan list` command to get the list of plans currently installed in dm Server. To start a plan, it must have already been resolved by dm Server, or in other words, be in the OSGi `Resolved` state. After dm Server successfully starts the plan, it is listed in the `Active` state.
stop name version	Stops the specified plan. You must specify both the full name of the plan as well as the version you want to stop. Use the `plan list` command to get the list of plans currently installed in dm Server. When you stop a plan, it goes from the OSGi `Active` state to the `Resolved` state, and you must re-start it if you want to use the application that the plan contains.
refresh name version	Updates the contents of the specified plan. You must specify both the name and version of the plan you want to refresh. Use the `plan list` command to this information. Use this command if you have changed the contents of the plan file and you want to refresh the artifact as installed in the OSGi framework.
uninstall name version	Uninstalls the specified plan. You must specify both the name and version of the plan you want to refresh. Use the `plan list` command to this information. When the uninstall process is complete, the plan will not show up in the list of plans displayed by the `plan list` command. If you want to use the application in the plan, you must re-install it using the `install` command.

The following example shows how to list the plans that have been installed in dm Server:

:> plan list

Name                                    Version                            State
com.springsource.kernel.region.springdm 2.0.0                             ACTIVE
com.springsource.server.admin.plan      2.0.0                             ACTIVE
com.springsource.server.web             2.0.0                             ACTIVE

The following example shows how to examine a particular plan:

:> plan examine com.springsource.server.web 2.0.0

State:  ACTIVE
Scoped: false
Atomic: false

Children:
    bundle com.springsource.osgi.webcontainer.tomcat 1.0.0.CI-85
    bundle com.springsource.osgi.webcontainer.core 1.0.0.CI-85
    bundle com.springsource.server.web.tomcat 2.0.0.D-20091109223734
    bundle com.springsource.server.web.core 2.0.0.D-20091109223734
    bundle com.springsource.server.web.dm 2.0.0.D-20091109223734

The following example shows how to stop a currently Active plan:

:> plan stop com.springsource.server.web 2.0.0   

plan com.springsource.server.web:2.0.0 stopped successfully

The following example shows how to start a plan:

:> plan start com.springsource.server.web 2.0.0

plan com.springsource.server.web:2.0.0 started successfully

service Command

Use the service command to view all the services that have been registered in the OSGi service registry of dm Server. You can also examine specific services to discover its properties, the bundle that publishes the service, and any bundles that might consume the service.

The following table lists the options you can specify for this command.

Table 4.7. Options of the service Command

Option	Descrption
list	Displays the list of services that are currently registered in the OSGi service registry of dm Server. Each service is identified by an internal `ID` which you can then use with the `service examine` command to view the details about a particular service. The `list` command also displays the object class that implements the service and the internal `id` of the bundle that provides the service.
examine id	Displays detailed information about the specified service. Use the `service list` command to get the internal id of a particular service. This command displays the properties of the service, such as the object class that implements the service, the name of the bundle that publishes the service and any bundles that consume the service.

The following example shows how to use list the services currently registered in the OSGi service registry:

:> service list

Id  Object Class(es)                                            Providing Bundle

1   org.osgi.service.packageadmin.PackageAdmin                                 0
2   org.osgi.service.permissionadmin.PermissionAdmin, ...                      0
3   org.osgi.service.startlevel.StartLevel                                     0
4   org.eclipse.osgi.service.debug.DebugOptions                                0
5   java.lang.ClassLoader                                                      0
6   org.eclipse.osgi.framework.log.FrameworkLog                                0
7   org.eclipse.osgi.framework.log.FrameworkLog                                0

... (entries removed)

65 com.springsource.osgi.webcontainer.core.spi.ServletContainer               35
66 com.springsource.osgi.webcontainer.core.WebContainer                       34
67 com.springsource.server.web.core.WebApplicationRegistry                    36
... (entries removed)

The following example shows how to examine a particular service:

:> service examine 38

Properties:
    Bundle-SymbolicName:
        com.springsource.kernel.services
    Bundle-Version:
        2.0.0.D-20091110110152
    objectClass:
        com.springsource.repository.Repository
    org.springframework.osgi.bean.name:
        repository
    service.id:
        38

Publisher: com.springsource.region.user 0.0.0 [1]

Consumer(s):
    com.springsource.kernel.userregion 2.0.0.D-20091110110152 [2]

install Command

Use the install command to deploy an artifact to dm Server. The artifact can be a bundle, PAR, plan, or configuration artifact.

The install command takes a single parameter: the URI of the artifact you want to deploy. For example, to deploy a bundle on the local computer, use the file scheme:

file://full-pathname-to-artifact

After you execute the install command, dm Server attempts to resolve the artifact's dependencies, and if it is successful, puts it in the Resolved state. At that point, you must start the artifact to be able to actually use it.

The following example shows how to install a bundle called swf-booking-mvc.war located in the /home/apps directory of the computer on which the dm Shell is being run:

:> install file://home/apps/swf-booking-mvc.war

Artifact bundle swf-booking-mvc.war 0.0.0 installed

The following example shows how to use the bundle list command to ensure that the bundle was indeed installed to dm Server; if you had installed a different kind of artifact, for example a plan, then you would use the appropriate command (such as plan list):

:> bundle list

Id   Name                             Version                State 

0    org.eclipse.osgi                 3.5.1.R35x_v20091005   ACTIVE
1    com.springsource.region.user     0.0.0                  ACTIVE

... (entries removed for clarity)

59   com.springsource.server.splash   2.0.0.D-20091110115520 ACTIVE 
60   swf-booking-mvc.war              0.0.0                  RESOLVED

Note that the swf-booking-mvc.war file is in the Resolved state. The following examples start the bundle, and then examine it to ensure that it is in the Active state:

:> bundle start 60

bundle swf-booking-mvc.war:0.0.0 started successfully


:> bundle examine 60

Id:              60
Name:            swf-booking-mvc.war
Version          0.0.0
State:           ACTIVE
Spring Powered:  true
Bundle Location: file:/home/juliet/dmServer2.0/springsource-dm-server-2.0.0.CI-468/work/com.springsource.kernel.deployer_2.0.0.D-20091110110152/deployer.staging/1642D0F2E664A7826F85ABC0DF360C81087D45F3/swf-booking-mvc.war/

Imported Packages:
    javax.crypto.interfaces [0.0.0, 0.0.0]
        exported by org.eclipse.osgi 3.5.1.R35x_v20091005 [0]
    org.omg.CosNaming.NamingContextPackage [0.0.0, 0.0.0]
        exported by org.eclipse.osgi 3.5.1.R35x_v20091005 [0]
    org.omg.DynamicAny.DynAnyFactoryPackage [0.0.0, 0.0.0]
        exported by org.eclipse.osgi 3.5.1.R35x_v20091005 [0]
    ...

shutdown Command

Use the shutdown command to shut down the dm Server instance to which you are connected. When dm Server is shutdown, the shell returns you to the operating system prompt.

The shutdown command does not have any options.

The following example shows how to use this command.

:> shutdown

Shutdown MBean called
prompt$

help Command

Use the help command on its own to get a list of all available dm Shell commands. If you specify a particular command to the help command, then you will get the list of options that you can pass to the command.

For example:

:> help


    bundle - Management and examination of bundle artifacts
    config - Management and examination of configuration artifacts
    help
    install - Install (deploy) an artifact to the server
    package - Management and examination of exported packages
    par - Management and examination of PAR artifacts
    plan - Management and examination of plan artifacts
    service - Examination of services
    shutdown


:> help bundle

bundle list                            - List all bundle artifacts that are
                                         currently installed
bundle examine   [ id | name version ] - Examine a bundle artifact
bundle start     [ id | name version ] - Start a bundle artifact. Starting this
                                         artifact starts it in the OSGi
                                         framework.
bundle stop      [ id | name version ] - Stop a bundle artifact. Stopping this
                                         artifact stops it in the OSGi
                                         framework.
bundle refresh   [ id | name version ] - Refresh a bundle artifact. Refreshing
                                         this artifact updates its contents in
                                         the OSGi framework.
bundle uninstall [ id | name version ] - Uninstall a bundle artifact
bundle diag      [ id | name version ] - Provide diagnostics for a bundle
                                         artifact
bundle headers   [ id | name version ] - Show the headers for a bundle artifact