This section contains reference information about the Virgo shell commands bundle, clhas, clexport, clload, config, packages, par, plan, service, install, shutdown, help, and exit.
Use the bundle
command to manage the lifecycle of bundles deployed in Virgo Kernel 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 8.2. Options of the bundle Command
Option | Description |
---|---|
list | Displays the list of bundles that are currently installed in the current Virgo Kernel instance. With the exception of a few kernel bundles and their services, which Virgo Kernel 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.
After Virgo Kernel successfully starts the bundle, it is listed in the |
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 |
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 Virgo Kernel. 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 Virgo Kernel could not resolve.
Use the Note that Virgo does not install unresolvable bundles. Instead is takes a state dump (for offline analysis using the web administration console) and fails the deployment. So bundles are only likely to become unresolvable in Virgo after an update operation. |
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 40 org.eclipse.virgo.kernel.userregionfactory 3.0.0.RELEASE ACTIVE 47 org.eclipse.equinox.cm 1.0.300.v20101204 ACTIVE 48 org.eclipse.virgo.kernel.userregion 3.0.0.RELEASE ACTIVE 49 org.eclipse.virgo.kernel.osgicommand 3.0.0.RELEASE ACTIVE 50 org.eclipse.osgi.services 3.3.0.v20110110 ACTIVE 51 com.springsource.org.apache.mina.core 2.0.2 ACTIVE 52 org.apache.felix.gogo.command 0.8.0.v201105062003 ACTIVE 53 org.apache.felix.gogo.runtime 0.8.0.v201105062003 ACTIVE 54 org.apache.felix.gogo.shell 0.8.0.v201107131313 ACTIVE 55 org.eclipse.equinox.console.supportability 1.0.0.20110722-2 ACTIVE 56 com.springsource.org.apache.sshd.core 0.5.0 ACTIVE 57 org.springframework.osgi.core 1.2.1 ACTIVE 58 S org.springframework.osgi.extender 1.2.1 ACTIVE 59 org.springframework.osgi.io 1.2.1 ACTIVE 60 org.eclipse.virgo.kernel.agent.dm 3.0.0.RELEASE ACTIVE 61 S org.eclipse.virgo.kernel.deployer.dm 3.0.0.RELEASE ACTIVE 62 org.eclipse.equinox.ds 1.3.0.v20110124-0830 ACTIVE 63 org.eclipse.equinox.util 1.0.200.v20100503 ACTIVE 64 com.springsource.org.aopalliance 1.0.0 ACTIVE 65 org.eclipse.virgo.kernel.dmfragment 3.0.0.RELEASE RESOLVED 66 org.springframework.aop 3.0.5.RELEASE ACTIVE 67 org.springframework.asm 3.0.5.RELEASE ACTIVE 68 org.springframework.beans 3.0.5.RELEASE ACTIVE 69 org.springframework.context 3.0.5.RELEASE ACTIVE 70 org.springframework.core 3.0.5.RELEASE ACTIVE 71 org.springframework.expression 3.0.5.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.RELEASE [8] <... remainder omitted ...> Consumed services: 1 org.osgi.service.packageadmin.PackageAdmin published by org.eclipse.osgi 3.7.0.v20110224 [0] <... remainder omitted ...> Fragments: org.eclipse.virgo.kernel.dmfragment 2.1.0.RELEASE [10] osgi>
Use the config
command to view and manage the configuration artifacts that have been installed in Virgo Kernel. 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 8.3. Options of the config Command
Option | Description |
---|---|
list | Lists the configuration artifacts that are currently installed in Virgo Kernel.
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 Virgo Kernel.
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 Virgo Kernel.
Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the
configuration artifact installed (which Virgo does not currently support).
Use the
Starting the configuration sets its state to |
stop name [version] | Stops the specified configuration artifact and makes it invisible to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the config list command to view all configuration artifacts and versions currently installed in Virgo Kernel.
Stopping the configuration sets its state to |
refresh name [version] | Updates the contents of the specified configuration artifact to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the config list command to view all configuration artifacts and versions currently installed in Virgo Kernel.
Use this command if you have changed the contents of the configuration artifact, and you want to make this information known to Virgo Kernel and the associated bundle. |
uninstall name [version] | Uninstalls the specified configuration artifact and make it completely unavailable to Virgo Kernel. Although you must specify the name of the configuration artifact, its version is optional unless you have multiple versions of the configuration artifact installed (which Virgo does not currently support). Use the config list command to view all configuration artifacts and versions currently installed in Virgo Kernel.
Stopping the configuration removes it from Virgo Kernel'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.console.ssh 0.0.0 ACTIVE osgi.console.telnet 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.repository Factory pid: Bundle Location: file:plugins/org.eclipse.virgo.kernel.services-3.6.0.M05.jar Properties: chain: ext,usr ext.searchPattern: repository/ext/{artifact} ext.type: external service.pid: org.eclipse.virgo.repository usr.type: watched usr.watchDirectory: repository/usr osgi>
Use the packages
command to view the complete list of packages exported by all bundles installed in Virgo Kernel, as well as examine a particular exported package in more detail.
The following table lists the options you can specify for this command.
Table 8.4. Options of the packages Command
Option | Description |
---|---|
list | Displays all the exported packages for all bundles in the uer region of Virgo Kernel. 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 package. You must specify both the name of the exported package and its version; use packages 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:packages 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:packages examine org.slf4j 1.6.1 Exporter: org.eclipse.virgo.region.user 0.0.0 [1] Attributes: None Directives: uses: org.slf4j.spi x-equinox-ee: -1 x-internal: false Importer(s): org.eclipse.virgo.kernel.agent.dm 2.1.0.RELEASE [7] Import-Package attributes: bundle-version: 0.0.0 version: [1.6.1,2.0.0) Import-Package directives: resolution: static <... remainder omitted ...> osgi>
Use the par
command to view all the PARs currently installed in Virgo Kernel, 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 8.5. Options of the par Command
Option | Description |
---|---|
list | Displays all the PARs that are currently installed in Virgo Kernel.
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 Virgo Kernel.
To start a PAR, it must have already been resolved by Virgo Kernel, or in other words, be in the |
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 Virgo Kernel.
When you stop a PAR, it goes from the |
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 Virgo Kernel:
osgi> vsh:par list Name Version State org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE ACTIVE osgi>
The following example shows how to examine a particular PAR file:
osgi> vsh:par examine org.eclipse.virgo.server.repository.hosted 2.1.0.RELEASE State: ACTIVE Scoped: true Atomic: true Children: bundle org.eclipse.virgo.server.repository.hosted.core 2.1.0.RELEASE bundle org.eclipse.virgo.server.repository.hosted.web 2.1.0.RELEASE bundle org.eclipse.virgo.server.repository.hosted-synthetic.context 2.1.0.RELEASE 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 Virgo Kernel, 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 8.6. Options of the plan Command
Option | Description |
---|---|
list | Displays all the plans that are currently installed in Virgo Kernel.
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 Virgo Kernel.
To start a plan, it must have already been resolved by Virgo Kernel, or in other words, be in the |
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 Virgo Kernel.
When you stop a plan, it goes from the |
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 Virgo Kernel:
osgi> vsh:plan list Name Version State org.eclipse.virgo.apps.admin.plan 2.1.0 ACTIVE org.eclipse.virgo.kernel.userregion.springdm 2.1.0 ACTIVE org.eclipse.virgo.web 2.1.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.agent.dm 2.1.0.RELEASE 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.deployer.dm 2.1.0.RELEASE osgi>
The following example shows how to stop a currently Active plan:
osgi> vsh:plan stop org.eclipse.virgo.web 2.1.0 plan org.eclipse.virgo.web:2.1.0 stopped successfully osgi>
The following example shows how to start a plan:
osgi> vsh:plan start org.eclipse.virgo.web 2.1.0 plan org.eclipse.virgo.web:2.1.0 started successfully osgi>
Use the service
command to view all the services that have been registered in the OSGi service registry of Virgo Kernel. You can also examine a specific service to discover its properties, the bundle that publishes the service, and any bundles that consume the service.
The following table lists the options you can specify for this command.
Table 8.7. Options of the service Command
Option | Description |
---|---|
list | Displays the list of services that are currently registered in the OSGi service registry of Virgo Kernel.
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 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 ...> 72 org.eclipse.gemini.web.core.spi.ServletContainer 38 73 org.eclipse.gemini.web.core.WebContainer 37 74 org.eclipse.virgo.web.core.WebApplicationRegistry 39 <... remainder omitted ...> osgi>
The following example shows how to examine a particular service:
osgi> vsh:service examine 73 Properties: objectClass: org.eclipse.gemini.web.core.WebContainer service.id: 73 Publisher: org.eclipse.gemini.web.core 1.1.0.RELEASE [37] Consumer(s): org.eclipse.virgo.web.core 2.1.0.RELEASE [39] osgi>
Use the install
command to deploy an artifact to Virgo Kernel. 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, Virgo Kernel 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:
osgi> vsh:install file://home/apps/swf-booking-mvc.war ... Artifact bundle swf-booking-mvc.war 0.0.0 installed
This command is particularly useful for installing an artifact from the Virgo repository, in which case use the repository:
scheme:
repository:artifact-type/bundle-symbolic-name/bundle-version
For example:
osgi> vsh:install repository:bundle/my.bundle/1.0 ... Artifact bundle my.bundle 1.0.0 installed osgi>
The following example shows how to use the bundle list
command to ensure that the bundle was indeed installed in Virgo Kernel; 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.6.1.R36x_v20100806 ACTIVE 1 org.eclipse.virgo.region.user 0.0.0 ACTIVE <... remainder omitted ...> 59 org.eclipse.virgo.server.splash 2.1.0.RELEASE 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.6.1.R36x_v20100806 [0] org.omg.CosNaming.NamingContextPackage [0.0.0, 0.0.0] exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0] org.omg.DynamicAny.DynAnyFactoryPackage [0.0.0, 0.0.0] exported by org.eclipse.osgi 3.6.1.R36x_v20100806 [0] <... remainder omitted ...> osgi>
Use the shutdown
command to shut down the Virgo Kernel instance to which you are connected. When Virgo Kernel is shut down, 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.
osgi> vsh:shutdown osgi> ... Connection closed by foreign host. prompt$
Use the clhas
command to list the entries contained in the bundles deployed in Virgo and to solve class loading issues.
The command accepts as a parameter a search pattern in the form path/resource. The resource part of the pattern can contain wildcards.
The output contains all bundles that have resources or classes matching the pattern. Since wildcards are allowed, the matching entities are listed as well.
The following examples show how to use this command.
Use the clhas
to view all bundles that contain Servlet
class:
osgi>clhas /javax/servlet/Servlet.class Bundles containing [/javax/servlet/Servlet.class]: 76 javax.servlet /javax/servlet/Servlet.class
Use the wildcard *
with clhas
to view all classes starting with Servlet
:
osgi> clhas /javax/servlet/Servlet* Bundles containing [/javax/servlet/Servlet*]: 76 javax.servlet /javax/servlet/ServletRequestAttributeEvent.class /javax/servlet/ServletRequest.class <... remainder omitted ...> /javax/servlet/Servlet.class <... remainder omitted ...>
The clhas
command can also be used with class name instead of resource path:
osgi> clhas javax.servlet.Servlet Bundles containing [javax/servlet/Servlet.class]: 76 javax.servlet /javax/servlet/Servlet.class
Please note that the command converts the class name to a path and appends class
extension by default.
To search for a resource with an extension different than class
you should use the resource path form:
osgi> clhas /LocalStrings.properties Bundles containing [/LocalStrings.properties]: 96 com.springsource.org.apache.catalina /org/apache/catalina/core/LocalStrings.properties /org/apache/tomcat/util/http/mapper/LocalStrings.properties /org/apache/catalina/loader/LocalStrings.properties <... remainder omitted ...>
The following example shows how to identify a possible ClassCastException
due to wrong packaging:
osgi>clhas /javax/servlet/Servlet.class Bundles containing [/javax/servlet/Servlet.class]: 76 javax.servlet /javax/servlet/Servlet.class 107 myapp /WEB-INF/classes/javax/servlet/Servlet.class
It's obvious that the javax.servlet
package should not be present in myapp
application and its packaging has to be changed. This problem can often be seen in WAR or web bundles that package Servlet/JSP classes by accident.
Use the clexport
command to list the bundles that export a class or package.
The command accepts as a parameter the fully qualified class name (in the form package.class).
The command checks to see if the provided class is actually contained in a bundle. If the class is not found in a bundle but its package is exported, then a hint [class not found, package only]
is displayed.
The following examples show how to use this command.
Use the clexport
to view all bundles that contain Servlet
class:
osgi> clexport javax.servlet.Servlet Bundles exporting [javax.servlet.Servlet]: 14 com.springsource.javax.servlet
If a bundle exports a package but does not contain the requested class, the output of the command will be similar to this:
osgi> clexport javax.servlet.ServletX Bundles exporting [javax.servlet.ServletX]: 14 com.springsource.javax.servlet [class not found, package only]
Use the clload
command to list the bundles that can load a class or to check if a specific bundle can load a class.
The command accepts as parameters either:
the fully qualified class name (in the form package.class)
the fully qualified class name (in the form package.class) and the symbolic name or id of the bundle that is to be tested
The command lists not only the bundle that successfully loaded the class, but also the one that actually provides the class. This is visualized with hints like [exported by 14 com.springsource.javax.servlet]
.
The following examples show how to use this command.
You can use the clload
to view all bundles that can load Servlet
class:
osgi> clload javax.servlet.Servlet Successfully loaded [javax.servlet.Servlet] from: 56 com.springsource.org.apache.taglibs.standard [exported by 14 com.springsource.javax.servlet] 54 org.eclipse.virgo.apps.admin.web [exported by 14 com.springsource.javax.servlet] 19 com.springsource.org.apache.commons.fileupload [exported by 14 com.springsource.javax.servlet] <... remainder omitted ...>
If a bundle is to be tested, then its id can be used as a command parameter:
osgi> clload javax.servlet.Servlet 19 Successfully loaded [javax.servlet.Servlet] using class loader from: 19 com.springsource.org.apache.commons.fileupload [exported by 14 com.springsource.javax.servlet]
Or the same class load test can specify the symbolic name of the bundle:
osgi> clload javax.servlet.Servlet com.springsource.org.apache.commons.fileupload Successfully loaded [javax.servlet.Servlet] using class loader from: 19 com.springsource.org.apache.commons.fileupload [exported by 14 com.springsource.javax.servlet]