This document discusses the program means to deploy and configure the bundles running on the backend hosts in an RM system.

Overview

Bundles intended to operate on the RM backend can be distributed in packages or as standalone bundles. In both cases, a backend bundle has a deployment target, which is the host role(s) identifying the hosts the bundle should run on. Then, the system takes care to deploy and manage the bundle on the specified target hosts.

A package contains bundles, which form a specific and relatively independent functionality. Packages should be packed in an JAR file with extension .pack.
Each package has meta data, which describes its basic attributes - name, version, etc., and the bundles (together with their deployment targets) it consists of. This meta data should be provided as a package descriptor in XML format. The descriptor should be in the META-INF folder of the .pack file. If you place the descriptor of the package in the packages directory of the RM distribution running on control center, then on restart the package bundles will be automatically located and deployed.

RM also supports package updates, which can be either as whole packages, containing all bundles defined for the package, or as package patches, containing only the bundles which need update. Patches are JARs with .patch extension. They also have XML descriptors, which describe the changes in the package attributes and the bundles to be updated.

The bundle deployment and maintenance is supported by the backend bundle inventory, which allows you to install packages, separate bundles, manage configuration dictionaries and permissions of bundles.

Accessing the Backend Bundle Inventory API

The backend bundle inventory is represented by the com.prosyst.mprm.admin.system.BackendBundleInventory interface. You can use it through the following System Configuration API components (both extending BackendBundleInventory):

• Configurator Manager service (com.prosyst.mprm.admin.system.ConfiguratorManager)

When using the Configurator Manager, you basically add separate bundles, not packages. The Configurator Manager is related to the persistent configuration of the system - no significant changes should be made.

• Configurator (com.prosyst.mprm.admin.system.ConfiguratorManager - can be got through the Configurator Manager)

When using Configurator, you can manage packages and standalone bundles. Package deployment requires confirmation with the Configurator.apply() method. This makes the system restart and reinitialize its settings.

As the Configurator object accumulates the changes, you can call apply all changes with a single call of apply().

Managing Packages

Packages can be basically managed through the Configurator. In addition, it is also possible to activate/deactivate backend bundle packages with the Configurator Manager.

Package Deployment

First, you must prepare the package bundles and its descriptor, and pack them in a .pack JAR. To get more information about package components, refer to Basic Concepts.

Then, you retrieve the Configurator from the Configurator Manager.

To add the package, call the addBundlePack method defined by the BackendBundleInventory interface. You should provide a stream to the .pack archive. As a result, you receive a BackendBundlePack object representing the deployed package.

After you finish all preparatory operations, call the apply method of Configurator to make RM save the changes.

Deploying a package on RM:
 

Management of a Deployed Package

Deployed backend bundle packages are represented as BackendBundlePack instances. You can access them through the Configurator Manager or the Configurator.
You can examine the content of the package - its main attributes (name, version and dependencies), and bundles.
You can activate or deactivate a package with the setActive method of the relevant BackendBundlePack instance. You are not allowed to deactivate the System package, which represents RM's core.
To enable or disable a optional package bundle after it has been deployed on RM, you can call the setBundleEnabled method. The bundle location within the package, required by this method can be retrieved with the getLocation method of the corresponding BackendBundle instance.

Package Resolving Tips:

• If a package depends on a missing one, the first one is automatically considered deactivated.
• Deactivation of a package automatically leads to deactivating the package(s) depending on it.

Package Update

To update a package, you need either a package including all defined bundles or a package patch holding only the bundles to be updated. For more help on what is included in a patch, see Basic Concepts.

After you get the package or patch ready, you can proceed with the update. Call the updatePack method of Configurator passing it the name of the package and the input stream to the package/patch archive.

As a result, you receive a BackendBundlePack object representing the updated package. See the "Package Deployment" chapter above for more information about using this object.

Updating a package through a patch:

Package Removal

Packages are removed from an RM system through the removeBundlePack method of Configurator.

Managing Backend Bundles

Except within packages, RM supports deployment of separate (alone) bundles on its backend hosts. It also provides methods for their administration.

Deploying Standalone Bundles

Separate bundles can be deployed through the Configurator Manager service or through the Configurator and this kind of operation. In the first case, requires no confirmation. You can use Configurator in case you do other changes with it so that they are set to the system altogether.

To add a bundle to the RM backend, call the addBundle method defined by the com.prosyst.mprm.admin.system.BackendBundleInventory interface. You should provide stream to the bundle JAR, and specify its deployment targets using the com.prosyst.mprm.admin.system.Roles class.

As a result, you receive a BackendBundle object representing the deployed bundle. With the methods of BackendBundle you can view basic information about the bundle.

Note that when a bundle is deployed on its deployment target(s), it is initially RESOLVED and should be explicitly started.

Deploying backend bundles:

Managing Deployed Backend Bundles

Deployed backend bundles are managed through a com.prosyst.mprm.admin.system.BackendBundleAdmin instance for a specific role or host. Such an instance can be obtained with the getBackendBundleAdmin method of the Configurator Manager. This method takes as parameter the ID of the backend host roles (null for all roles), the ID of a management server, or any role defined in the Roles class.
On a single host, operations through a BackendBundleAdmin instance are possible only runtime. You can not use it during host configuration.
BackendBundleAdmin represents bundles as DeployedBackendBundle objects.

Updating Backend Bundles

A backend bundle can be updated through the updateBundle method of com.prosyst.mprm.admin.system.BackendBundleInventory. The backend bundle inventory will update the bundles on the backend host and the information about the bundle in the system database.

Another type of bundle update is changing the bundle deployment target(s). You do this specific update with the updateBundleTargets method if BackendBundleInventory, specifying the new deployment targets.

Removing Backend Bundles

To remove a backend bundle, use the removeBundle method of BackendBundleInventory.

Managing Bundle Configurations

You can manage the configuration properties of a backend bundle, defined as outlined by the OSGi Configuration Admin Service specification. To introduce configuration properties, you can also benefit from the support of XML-based meta data definition provided by the Config Bundle.

Each bundle configuration (its meta data and default values) is defined in an XML, included in the bundle JAR, and has a default scope - it is applied to all roles. When a role-specific configuration instance is defined, the default configuration and role-specific instances overlap. In such case, the role-specific configuration will prevail on host startup.

Managing Singleton Configurations

You can set / get the singleton configuration of a backend bundle on a specific backend host with the setConfiguration / getConfiguration method of BackendBundleInventory. By using the setConfiguration method you can also define different configuration for backend hosts with a specific role (roles are provided as Roles class fields; null stands for all roles).

Options for Factory Configurations

You can generate a singleton configuration out of a defined configuration factory with the createFactoryConfiguration method of BackendBundleInventory. As a result, the persistent identity (PID) of the generated configuration is returned. Subsequently, you can use this PID to retrieve/change the configuration properties.

To retrieve the PIDs of the configurations created from a factory configuration, you can use the getPidsOfFactoryConfiguration method. Then, you can locate and change these configuration if necessary.

Retrieving Configuration Meta Type Providers

RM enables you to get the meta data of a singleton configuration or a factory configuration in the form of org.osgi.service.cm.MetaTypeProvider objects, whose usage and meaning is defined by the OSGi Metatype Specification.

Use the getMetaTypeProvider method to receive a MetaTypeProvider for a singleton configuration. If a bundle has more than one singleton configuration, use the getMetaTypeProviders method to retrieve the meta data of the configurations.

Next, you can use the MetaTypeProviders as defined by the OSGi Metatype Specification.

Managing Backend Bundle Permissions

You can manage the permissions of a backend bundle running on a backend framework with security through the methods of BackendBundleInventory implemented by the Configurator Manager (com.prosyst.mprm.admin.system.ConfiguratorManager).

In general, you can define bundle permissions for a host role (control center, management servers, and remote access servers) or for a particular management server. This information persists across host restart. You can assign a bundle permission on a specific host, but this information is valid only runtime.

Permission management of backend bundles is based on the Permission Admin service, running on each backend host framework, which implements the OSGi Permission Admin service (org.osgi.service.permissionadmin.PermissionAdmin). The Permission Admin service allows bundles of administration type to assign permissions to bundles. These permissions are based on the location of the bundles and may remain after framework restarts. The bundle location/permission collection pairs are kept in a permission table with locations being the keys. If there is no table entry for the location of a bundle, then a default set of permissions is used for check.

The assigned permissions are represented by the org.osgi.service.permissionadmin.PermissionInfo objects. Each PermissionInfo instance wraps the permission type (that is, a subclass of java.security.Permission), the permission name and the permission actions. Note that the permission type should have a constructor with two arguments - the permission name and actions.

To assign a new permission to a bundle, use the addPermission method of BackendBundleInventory specifying the target host role (null for all roles), bundle location on the host, and a PermissionInfo object describing the permission.

To change the permission set of a backend bundle installed running on a host with specific role, use the setPermission method. This method requires as input the ID of the target host role, the location of the bundle on the backend host and the new permissions of the bundle as a PermissionInfo array. All previously set permissions are removed.

To remove one or more permissions of a bundle, use the removePermission method specifying the permissions to be deleted.

As mentioned several paragraphs above, you can temporarily assign permissions to a bundle on a particular host at runtime - just specify host ID instead of role ID.

References

• Backend Bundles Configuration - Conceptual Guide.
• Configurator Manager and Configurator API Documentation
• Backend Bundle Inventory API Documentation
• OSGi Service Platform Release 4.