This section contains reference information about the following Equinox Console Extension commands:
Use the bundle command to manage the lifecycle of bundles deployed to VWS 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 Web Server instance. With the exception of a few kernel bundles and their services, which Web 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
Use one of the other |
| 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 The |
| 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 Web Server, or in other words, be in the OSGi |
| 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 |
| 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 Web 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 |
| diag id | Provides diagnostic information about the specified bundle. In particular, this command displays information about the imported packages that Web 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: |
The following examples show how to use this command.
First, use the bundle list command to view all the installed bundles:
osgi> vsh bundle list Id Name Version State 0 org.eclipse.osgi 3.5.1.R35x_v20091005 ACTIVE 1 org.eclipse.virgo.region.user 0.0.0 ACTIVE 2 org.eclipse.virgo.kernel.userregion 2.1.0.BUILD-20100609153042 ACTIVE 3 org.eclipse.virgo.kernel.osgicommand 2.1.0.BUILD-20100609153042 ACTIVE 4 org.springframework.osgi.core 1.2.1 ACTIVE 5 S org.springframework.osgi.extender 1.2.1 ACTIVE 6 org.springframework.osgi.io 1.2.1 ACTIVE 7 org.eclipse.virgo.kernel.agent.dm 2.1.0.BUILD-20100609153042 ACTIVE 8 S org.eclipse.virgo.kernel.deployer.dm 2.1.0.BUILD-20100609153042 ACTIVE 9 com.springsource.org.aopalliance 1.0.0 ACTIVE 10 org.eclipse.virgo.kernel.dmfragment 2.1.0.BUILD-20100609153042 RESOLVED 11 org.springframework.aop 3.0.0.RELEASE ACTIVE 12 org.springframework.asm 3.0.0.RELEASE ACTIVE 13 org.springframework.beans 3.0.0.RELEASE ACTIVE 14 org.springframework.context 3.0.0.RELEASE ACTIVE 15 org.springframework.core 3.0.0.RELEASE ACTIVE 16 org.springframework.expression 3.0.0.RELEASE ACTIVE osgi>
The following example shows how to view the headers of the org.springframework.osgi.extender bundle (only the first few lines are shown):
osgi> vsh bundle examine 5
Id: 5
Name: org.springframework.osgi.extender
Version 1.2.1
State: ACTIVE
Spring Powered: true
Bundle Location: file:<... omitted ...>/org.springframework.osgi.extender-1.2.1.jar/
Imported Packages:
org.springframework.osgi.context [1.2.1, 1.2.1]
exported by org.springframework.osgi.core 1.2.1 [4]
<... remainder omitted ...>
Exported Packages:
org.springframework.osgi.extender 1.2.1
<... remainder omitted ...>
Published services:
58 org.springframework.beans.factory.xml.NamespaceHandlerResolver
consumed by org.springframework.osgi.extender 1.2.1 [5]
consumed by org.eclipse.virgo.kernel.deployer.dm 2.1.0.BUILD-20100609153042 [8]
<... remainder omitted ...>
Consumed services:
34 org.eclipse.virgo.kernel.shim.serviceability.TracingService
published by org.eclipse.virgo.region.user 0.0.0 [1]
<... remainder omitted ...>
Fragments:
org.eclipse.virgo.kernel.dmfragment 2.1.0.BUILD-20100609153042 [10]
osgi> Use the config command to view and manage the configuration artifacts that have been installed to Web 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 Web Server.
The |
| 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 Web Server.
A configuration artifact must be active for you to examine it; if it is not currently active, use 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 Web 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 Web Server.
Starting the configuration sets its state to |
| stop name [version] | Stops the specified configuration artifact and makes it invisible to the internal configuration sub-system of Web 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 Web Server.
Stopping the configuration sets its state to |
| refresh name [version] | Updates the contents of the specified configuration artifact to the internal configuration sub-system of Web 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 Web Server.
Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to Web Server and the associated bundle. |
| uninstall name [version] | Uninstalls the specified configuration artifact and make it completely unavailable to Web 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 Web Server.
Stopping the configuration removes it from Web Server's list of deployed artifacts and it will not show up when you perform a |
The following example shows how to use this command to list the installed configuration artifacts.
osgi> vsh config list Name Version State org.eclipse.virgo.kernel 0.0.0 ACTIVE org.eclipse.virgo.kernel.jmxremote.access 0.0.0 ACTIVE org.eclipse.virgo.kernel.userregion 0.0.0 ACTIVE org.eclipse.virgo.kernel.users 0.0.0 ACTIVE org.eclipse.virgo.medic 0.0.0 ACTIVE org.eclipse.virgo.repository 0.0.0 ACTIVE osgi>
To view the properties of a configuration artifact, and their current values, use config examine:
osgi> vsh config examine org.eclipse.virgo.medic
Factory pid:
Bundle Location: file:lib/kernel/org.eclipse.virgo.kernel.shell-2.1.0.BUILD-20100609153042.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:
org.eclipse.virgo.medic
osgi> Use the package command to view the complete list of packages exported by all bundles installed to Web 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 Web 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 following example shows how to list all the exported packages for all bundles installed:
osgi> vsh package list Name Version Providing Bundle javax.accessibility 0.0.0 0 javax.activation 0.0.0 0 javax.activation 1.1.1 0 <... remainder omitted ...> osgi>
The following example shows how to examine a particular exported package:
osgi> vsh package examine org.slf4j 1.5.10
Exporter: org.eclipse.virgo.region.user 0.0.0 [1]
Attributes:
None
Directives:
uses:
org.slf4j.impl, org.slf4j.spi
x-equinox-ee:
-1
x-internal:
false
Importer(s):
org.eclipse.virgo.kernel.userregion 2.1.0.BUILD-20100609153042 [2]
Import-Package attributes:
bundle-version:
0.0.0
version:
[1.5.10,2.0.0)
Import-Package directives:
resolution:
static
<... remainder omitted ...>
osgi> Use the par command to view all the PARs currently installed in Web 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 Web Server.
The |
| 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:
|
| 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 Web Server.
To start a PAR, it must have already been resolved by Web Server, or in other words, be in the OSGi |
| 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 Web Server.
When you stop a PAR, it goes from the OSGi |
| 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 |
The following example shows how to list the PARs that have been installed in Web Server:
osgi> vsh par list Name Version State org.eclipse.virgo.server.repository.hosted 2.0.0.D-20091109225604 ACTIVE osgi>
The following example shows how to examine a particular PAR file:
osgi> vsh par examine org.eclipse.virgo.server.repository.hosted 2.0.0.D-20091109225604
State: ACTIVE
Scoped: true
Atomic: true
Children:
bundle org.eclipse.virgo.server.repository.hosted.core 2.0.0.D-20091109225604
bundle org.eclipse.virgo.server.repository.hosted.web 2.0.0.D-20091109225604
bundle org.eclipse.virgo.server.repository.hosted-synthetic.context 2.0.0.D-20091109225604
osgi> Finally, the following example shows how to refresh an installed PAR file:
osgi> vsh par refresh my.exciting.par 1.2.0 par my.exciting.par 1.2.0 refreshed successfully osgi>
Use the plan command to view all the plans currently installed in Web 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 Web Server.
The |
| 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:
|
| 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 Web Server.
To start a plan, it must have already been resolved by Web Server, or in other words, be in the OSGi |
| 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 Web Server.
When you stop a plan, it goes from the OSGi |
| 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 |
The following example shows how to list the plans that have been installed in Web Server:
osgi> vsh plan list Name Version State org.eclipse.virgo.kernel.region.springdm 2.0.0 ACTIVE org.eclipse.virgo.server.admin.plan 2.0.0 ACTIVE org.eclipse.virgo.server.web 2.0.0 ACTIVE osgi>
The following example shows how to examine a particular plan:
osgi> vsh plan examine org.eclipse.virgo.kernel.userregion.springdm 2.1.0
State: ACTIVE
Scoped: false
Atomic: false
Children:
bundle org.eclipse.virgo.kernel.deployer.dm 2.1.0.BUILD-20100609153042
bundle org.springframework.osgi.io 1.2.1
bundle org.springframework.osgi.extender 1.2.1
bundle org.springframework.osgi.core 1.2.1
bundle org.eclipse.virgo.kernel.agent.dm 2.1.0.BUILD-20100609153042
osgi> The following example shows how to stop a currently Active plan:
osgi> vsh plan stop org.eclipse.virgo.server.web 2.0.0 plan org.eclipse.virgo.server.web:2.0.0 stopped successfully osgi>
The following example shows how to start a plan:
osgi> vsh plan start org.eclipse.virgo.server.web 2.0.0 plan org.eclipse.virgo.server.web:2.0.0 started successfully osgi>
Use the service command to view all the services that have been registered in the OSGi service registry of Web 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 Web Server.
Each service is identified by an internal |
| 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:
osgi> vsh 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 <... remainder omitted ...> 65 com.springsource.osgi.webcontainer.core.spi.ServletContainer 35 66 com.springsource.osgi.webcontainer.core.WebContainer 34 67 org.eclipse.virgo.server.web.core.WebApplicationRegistry 36 <... remainder omitted ...> osgi>
The following example shows how to examine a particular service:
osgi> vsh service examine 38
Properties:
Bundle-SymbolicName:
org.eclipse.virgo.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):
org.eclipse.virgo.kernel.userregion 2.0.0.D-20091110110152 [2]
osgi> Use the install command to deploy an artifact to Web 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, Web 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 Equinox Console Extension 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 Web 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):
osgi> vsh 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 <... remainder omitted ...> 59 org.eclipse.virgo.server.splash 2.0.0.D-20091110115520 ACTIVE 60 swf-booking-mvc.war 0.0.0 RESOLVED osgi>
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:
osgi> vsh bundle start 60
bundle swf-booking-mvc.war:0.0.0 started successfully
osgi> vsh bundle examine 60
Id: 60
Name: swf-booking-mvc.war
Version 0.0.0
State: ACTIVE
Spring Powered: true
Bundle Location: file:<... omitted ...>/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]
<... remainder omitted ...>
osgi> Use the shutdown command to shut down the Web Server instance to which you are connected. When Web 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$
Use the help command on its own to get a list of all available Equinox Console Extension 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:
osgi> vsh help
bundle - Management and examination of bundle artifacts
config - Management and examination of configuration artifacts
exit - Exit the kernel shell environment
help - Get help on commands
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 - Shutdown Virgo Kernel
osgi> vsh 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
osgi>