Kit Manager Bundle

The Kit Manager Bundle installs and uninstalls kits or demos composed of several bundles.

To install/uninstall a kit, you specify an absolute path or a relative to the script base URL path to a script with installation commands to be executed by the framework. The Kit Manager Service locates the script, reads its content, contacts the Parser Service of the ProSyst Util Bundle and forwards for execution the commands found in the script.

Contents:

• Bundle Information
  • Bundle JAR
  • Import
  • Export
• Console Commands
  • Kitman Group Commands
  • An Example of How to Use Kit Manager Commands
• Principles of Work
  • Install Scripts Loaded by Default
  • Writing Your Own Scripts
  • Script Relative Location
  • Bundle Base URL
  • Using the Repair Option at Kit's Installation
  • Adding Kits to the Kit Manager
    • Static List of Kits
    • Dynamically Generated List of Kits
  • Executing a Kit's Install Script at Framework Startup
  • Avoiding Bundle Duplication
• Services
  • Kit Manager Service
  • Pluggable Commands
• System Properties
  • Usage Examples
• Troubleshooting
• References

Bundle Information

Bundle JAR

The JAR of the Kit Manager Bundle is kitman.jar and is located in the bundles directory.

Import

Export

com.prosyst.mbs.services.kitmanager - provides access to the Kit Manager Service.

Console Commands

The Kit Manager Bundle provides a group of string commands called kitman. These commands allow install/uninstall kits via install scripts, view information about the status of the kit components as well as get the dependencies of the bundles included in a kit.

You enter the kitman group with the kitman/ command.

Tip: To get the parameters and descriptions of kitman commands, type help. To get the options supported by these commands, use help -d. To view command shortcuts, use help -s. To view detailed help for a single command, for example the install command, type install?.

Kitman Group Commands

The following table describes the commands of the Kit Manager.

Note: If invoking a command using the kit's name, wrap that name in quotation marks - for example install "the kit name goes here".

An Example of How to Use Kit Manager Commands

1. To view and manage kits, we should switch to the kitman command group:

   kitman/

2. Supposing that we are to install an imaginary kit with name "My Kit" and kit ID equal to 5, there are two possible ways to do it.
   • Installing the kit via its name:
     install "My Kit"
   • Installing the kit via its ID:
     • To view the kit's ID:
       list
     • To install the kit
       install 5
3. Supposing that we finished our job with "My Kit", there are two ways to uninstall it:
   • Using kit's name
     uninstall -i "My Kit"
   • Using kit's ID
     uninstall -i 5

Principles of Work

Install Scripts Loaded by Default

By default, bin/pscripts and the sub directories of demo contain the install scripts for most of the mBS demos and kits, such as the Jini Driver (see Jini package), X10 CM11A support (see X10 package), the mBedded Browser (see Browser package), etc. These install scripts install bundles from the bundles directory of the mBS, which is included in all packages.

Writing Your Own Scripts

Install script files contain commands with syntax legal to the Parser Service of the ProSyst Util Bundle. They should be written in a simple text format and have the TXT extension.

Install Script Tokens. To make the Kit Manager Service recognize an install script, the script should start with a commented Kit-Name token, i.e. the token must be preceded by the "#" symbol. This token marks the file as an install script when the Kit Manager examines preliminary specified directories for install scripts in order to generate a list of kits (see "Adding Kits to the Kit Manager").

You may also insert information about the name, vendor and version of each bundle that is to be installed. For this purpose, before the installation command use the Bundle-Name, Bundle-Vendor and Bundle-Version tokens, which must be comments as well. The Kit Manager uses these tokens to analyze dependencies of kit's bundles and to check if there are bundles, already installed in the framework, that satisfy some of these dependencies (for example, there are bundles which versions are equal or higher than the ones specified in the installed script).

Placing Commands in an Install Script. Initially, the Parser Service holds the base and fw group commands, and it is recommended that you use mainly them to install bundle kits and demos. The basic command for installation is the install one (shortcut as i) from the fw command group:

• To install and start a bundle with the install command, you should add the -s option.
• The Kit Manager Service does not support the -S option.
• Each command should be written in a separate line.
• Consider the bundle base URL if installing a bundle.

Note: It is not advisable to use commands that require a bundleID as argument, because the framework dynamically assigns IDs.

An Example Install Script. Following is an example install script (Listing 1.1), which installs a bundle which JAR is kitbundle.jar located in the directory from which the framework is started. Note the Kit-Name token in the beginning of the script.

#Kit-Name: My Kit
fw/
#Bundle-Name: Kit Bundle
#Bundle-Vendor: Kit Vendor
#Bundle-Version: 1.0
i -s /kitbundle.jar

Script Relative Location

You locate install scripts through relative paths. These paths are related to the mbs.script.base system property, which points to the home directory of the Framework Professional Edition Package - the script base URL. The full location of the script is then composed of the script base URL and the specified install script location. It is recommended that you put a "/" at the end of mbs.script.base. The default value of the script base URL is set to the installation directory of the Framework Professional Edition Package , so that you can directly call the install scripts of the provided demos.

Note: The script base URL should contain a communication protocol identifier, such as http://. For the local file system this is file:///. If the bundle base URL points to a remote machine, access to that URL must be provided. For example, if an HTTP URL is assigned, it should be registered as a resource in an HTTP server running on the target machine.

Bundle Base URL

When you are installing a bundle, you specify its location either as a JAR file in the local system or an URL. The location is considered relative to the bundle base URL set by the mbs.bundles.base system property. In result, the full path to the bundle is composed of the bundle base URL and the one passed to the install command.

To avoid placing the bundle base URL as a prefix in the location, you should insert a "/" in front of the location. In such case, the framework looks for the specified bundle in the directory from which the framework is activated. For example, at installation the location of a bundle which JAR is kitbundle.jar in a folder called kitbundles, can be specified in the following ways:

install -s /kitbundles/kitbundle.jar

The framework searches for kitbundles/kitbundle.jar in the directory from which the framework is started. For example, in bin/vms/jdk.

install -s kitbundles/kitbundle.jar

The framework loads kitbundles/kitbundle.jar from <base_URL>/kitbundles/kitbundles.jar, where <bundles_base_URL> is the value of the mbs.bundles.base property.

When installing bundles through the Kit Manager Service, the value of the bundle base URL is temporarily changed to <script_base_URL><bundles_base_URL> supposing that the script base URL is the home directory of the kit's components. After the operations recorded in the install script are executed, the bundle base URL receives its old value.

Note: If supplied as an absolute path or a URL, the bundle base URL should contain a communication protocol identifier, such as http://. For the local file system this is file:///. If the bundle base URL points to a remote machine, access to that URL must be provided. For example, if an HTTP URL is assigned, it should be registered as a resource in an HTTP server running on the destination machine.

Tip: You can change the mbs.bundles.base value in the install script using the set system command if some bundles necessary for the kit's correct work are located outside of the script base location.

Using the Repair Option at Kit Installation

By using the repair option, you can make the Kit Manager Service replace the bundle information from the install script (name, vendor and version) with the one in the bundle manifest. For instance, this operation may be used to save updating the versions of the bundles in a kit if this is already done in their manifests.

If the repair option is on, installed bundles are filtered according to the data in the manifests of the kit's bundles. If there are already installed bundles that satisfy these criteria, then the information in their manifests substitutes the one provided by the kit's script.

Adding Kits to the Kit Manager

The Kit Manager manages kits found in a static list loaded from a file and in a dynamic list, generated on inspecting for install scripts a set of directories.

Static List of Kits

The static list contains a ready list of kits to include in the Kit Manager for subsequent installation/uninstallation. For example, this list is convenient in case the device on which the framework runs has no file system. Then, the Kit Manager can install a kit reading the necessary data from a file located somewhere in the network.

You provide the static list in an XML-like file and specify its location with the mbs.kitlist.url system property. In this file, for each kit you must supply the following tags:

• <name> - the kit name
• <script> - the location of the kit's install script as a path relative to the script base URL or as an absolute location

You should place the attributes of each kit in a separate line.

Listing 1.2 shows how to define a static list of kits to install.

<name>Kit One</name><script>/kitone/install.txt</script>
<name>Kit Two</name><script>/kittwo/install.txt</script>

Dynamically Generated List of Kits

The Kit Manager inspects for install scripts a list of user-specified directories including their sub directories and generates a dynamic list of kits. Next, it appends found kits to the ones from the static list.

You specify directories to examine for install scripts, separated by semicolons (;), in the mbs.kitlist.dirs system property. Directories should be relative to the script base URL or as absolute paths. By default, mbs.kitlist.dirs includes the bin/pscripts and /demo folders related to the script base URL (the Framework Professional Edition Package home directory).

Note: If the script base URL is a URL (not a local path), then dynamic listing is not possible.

Note: If a list location is specified as a URL, it must contain a valid protocol identifier such as http://. For the local file system this is file:///. If a location points to a remote machine, access to it must be provided. For example, if an HTTP URL is assigned, it should be registered as a resource in an HTTP server running on the destination machine.

Executing a Kit's Install Script at Framework Startup

The Kit Manager offers the opportunity to execute a script, specified with the mbs.kitman.startup system property, at framework startup. The script can be located at a file:/, http:// or ftp:// URL or can be placed in the exec base URL.

Avoiding Bundle Duplication

To avoid duplicating bundles running in the framework, the Kit Manager Service compares the locations of the bundles to be installed with the ones of the bundles already installed in the framework. The name, vendor and version attributes in an install script are optional, but if present the Kit Manager Service will use them to compare bundles by these criteria. If a match by all three criteria is found, for example a bundle with version higher or equal to the one written in the script is considered a match for the version criterion, the bundle from the kit is skipped.

Note: Install scripts can be executed straight from the framework console with the exec system command. In this case, no check for matching bundles is performed. The kit's uninstallation must be done manually - the user must know which bundles participate in the kit and uninstall them with the uninstall <BUNDLE_ID> fw group command.

Services

Kit Manager Service

The Kit Manager Service supports installing/uninstalling bundles by using scripts. This allows you to specify all necessary bundles to form a kit and the correct order for installing them. The service is represented by the com.prosyst.mbs.services.kitmanager.KitManagerService interface.

Installing Kits. By calling the installKit method of the Kit Manager Service (com.prosyst.mbs.services.kitmanager.KitManagerService) you can install kits in the framework. This method takes two parameters:

• The relative location of the kit's install script
• The repair flag that can be true to turn repair on or false otherwise

The installKit method returns an InstallStatus object that contains an eventual message about installation failure.

The example that follows loads in the Kit Manager Service an install script (Listing 1.1), called install.txt. Supposing that the install script and kitbundle.jar are placed in the c:/kit/ local directory, the mbs.script.base property is preliminary set to file:///c:/kit/ so that the service can find the script and forward its commands for execution. To avoid appending the bundle base URL to the script base URL, a "/" is placed in front of the bundle JAR location (see the Listing 1.1). An example code that loads install.txt with repair on can be:

  import org.osgi.framework.BundleActivator;
  import org.osgi.framework.BundleContext;
  import org.osgi.framework.ServiceReference;
  import com.prosyst.mbs.services.kitmanager.KitManagerService;
 
  public class KitManTester implements BundleActivator {
    ServiceReference kitManRef = null;
    KitManagerService kitMan;
    String location = "install.txt";
    
    public void start(BundleContext bc) {
      kitManRef = bc.getServiceReference(KitManagerService.class.getName());
      if(kitManRef != null) {
        kitMan = (KitManagerService)bc.getService(kitManRef); 
      }
      try { 
        kitMan.installKit(location, true);
      } catch(java.io.IOException ioexc) {
        ioexc.printStackTrace();
      }
    }
 
    public void stop(BundleContext bc) {
      bc.ungetService(kitManRef);
    }
  }

Uninstalling Kits. If you want to uninstall a kit, you can use the uninstallKit method of the Kit Manager Service specifying the install script of the kit. The service retrieves the IDs of the kit's bundles from a custom database, called "KITMAN", in the DB Bundle. Next, a dependence analysis is performed to find out whether some external bundle depends on a bundle included in the kit or not. If such relation is discovered, no uninstallation is performed. Instead, the DependencyList object returned by the uninstallKit method lists all found dependencies.

The doUninstall flag of the uninstallKit method allows you to:

• Analyze dependencies when set to false
• Automatically uninstall the kit if no dependencies are found. If another kit uses the bundles of the one to be uninstalled, the Kit Manager does not execute uninstallation.

When the Kit Manager discovers kit dependencies, the bundle using it can prompt its users for the correct behavior, that is, whether to uninstall all bundles or to uninstall only independent bundles.

For example supposing that kit B depends on a bundle from kit A and the user wants to uninstall kit A. Consider the cases:

• The user chooses not to uninstall the bundles, on which kit B depends. In this case, you can retrieve the IDs of all independent bundles of kit A by calling the getIndependentBundles method of DependencyList. Then, you can use them as input parameters to the uninstallList method in KitManagerService.
• The user chooses to uninstall all bundles in kit A, no matter that the operation of kit A will be disturbed. In this case, you can call getAllBundles from DependencyList to get the IDs of all kit's bundles and then pass them to the uninstallList method.

Listing Available Kits. You make the Kit Manager Service list the currently available kits by calling the listKits method. You receive a Vector of strings, which contains a kits' list formed using the rules discussed above.

Viewing Kit's Status. Developers can also examine the status of a kit through the analyseKit method of the Kit Manager Service. The result is represented by a KitStatus object that wraps the status of the kit, which can be "installed", "not installed", "present" and with "bad script". You can also get the status of the kit's bundles.

Pluggable Commands

The Kit Manager Bundle registers the com.prosyst.util.pcommands.PluggableCommands service, which contains a collection of console commands arranged in a group, called kitman. These commands are stored in the command set of the Parser Service provided by the ProSyst Util Bundle and are redirected to the framework's runtime console and to Telnet.

System Properties

To configure runtime the Kit Manager bundle, you can use the following system properties:

For more information about setting system properties, refer to the System Properties chapter.

Usage Examples

This chapter discusses three different situations that emerge when tuning the system properties previously described.

• The first one comes out if the framework, kit's bundles and install script are on the local machine. You may benefit from the default values of the above properties if you place kit's bundles in the bundles directory of the framework and copy the install script to bin/pscripts. Then, no system setup is necessary to install the kit.
• The second situation is if the framework, kit's bundles and install script are on a machine in the LAN, for example named "home_gateway". The home directory of the framework is shared as "fw_root". In this case, to take advantage of the default property value:
  • The kit's bundles should be located in bundles and the install script in bin/pscripts of the shared framework.
  • Then, only set mbs.script.base to file://home_gateway/fw_root/.

  The Kit Manager locates the install script by searching in mbs.script.base + mbs.kitlist.dirs, that is in file://home_gateway/fw_root/bin/pscripts.

  Next, the Kit Manager loads for execution the commands from the install script. Kit's bundles are retrieved from the mbs.script.base + mbs.bundles.base directory, which results in file://home_gateway/fw_root/bundles/ (the i -s kitbundle.jar command is interpreted as i -s file://home_gateway/fw_root/bundles/kitbundle.jar) .

• The third situation arises when the following components are registered under the "/install" alias on an HTTP server host called "home_gateway" (http://home_gateway/install/) :
  • a static kit list, which is called mykitlist.txt and contains a single kit with properties:
    

    <name>My Kit</name><script>myinstallscript.txt</script>

    
    Hence, the name of the kit is "My Kit" and its install script is myinstallscript.txt.
  • The install script myinstallscript.txt
  • The bundles of the kit as JAR files

  To successfully install the kits listed in mykitlist.txt, you should set the following property values:

  • mbs.kitlist.url equal to http://home_gateway/install/mykitlist.txt
  • mbs.script.base equal to http://home_gateway/install/

    In result, on installing "My Kit" the bundles are passed by the HTTP server to the framework and are then deployed.

Troubleshooting

The Kit Manager saves the IDs of installed kits' bundles in a database, called "KITMAN", in the DB Bundle. After updating the DB Bundle, the databases will be deleted from the storage and the Kit Manager will not remember which kits it installed.

References

• Kit Manager Service API.
• Framework Commands.

Utility Bundles