Framework Access service

The FrameworkAccess service provides access to some special functionality offered by the framework. It is published under the com.prosyst.mbs.framework.access.FrameworkAccess interface name.

The FrameworkAccess service allows you to perform many operations as it is described in the following paragraphs.

Registering bundle

This service is registered by the System bundle.

Storage-related functionality

• Install bundles "from file" benefiting from the factory storage support – In the case of the Storage on top of java.io, the framework supports installing bundles "from file". In brief, this means installing bundle JAR files without copying the JAR files to the framework persistent storage.

  The method of the FrameworkAccess service for installing bundles "from file" at runtime is installBundleFromFile.

• Install and get a bundle onto external memory or partition (for example, on a flash memory card) – In some cases it is required to store a bundle installed in an OSGi framework on a specific location, by reason of persistence, safety or portability.

  The method of the FrameworkAccess service for installing a bundle placing it in a separate storage root directory is installBundleInSpecificStorage.

  Next, you can get the storage roots saved in the framework by using the getStorageRoots methods and get the bundles installed in such a specific root by using the getBundlesInRoot method. To get the time when a specific storage root was mounted (i.e. the time when the relevant root was plugged in the OSGi-enabled device), use the getLastMountTime method.

• To notify the framework that a specific storage root is plugged, use the storageDirStateChanged method with the Plugged flag equal to true. To unmount a storage root, e.g. in case of clean-up, call the method with isPlugged equal to false.

Manage Lazy bundles

When in lazy mode, the framework introduces a model for lazy initialization and activation of bundles registering services and of bundles referencing a specific service. Such bundles remain idle and are not really started until there is a real need for it – when a registered service is called by some bundle or when a requested service becomes available by some bundle. See the Lazy initialization document for more information.

The FrameworkAccess service contains the following methods related to lazy bundles:

• getLazyState – Returns the lazy state of a bundle.
• isLazyServiceReferenced – Indicates if a service is still lazy and is waiting for a bundle to request in order to become registered in the framework.
• startLazy – Starts a bundle, preserving its lazy features.

Save information in the Framework Log

Gain access to the Framework Log through the getFrameworkLogger method. Saving logs to the Framework Log allows for adding log messages to the framework-generated logs, employing a pre-initialized instance of com.prosyst.util.Logger in accordance with the configuration of the Framework Log (your logs will be shown in the console or written to a file). According to the value of the system property mbs.log.file.dir the Framework Log determines whether to write logs to the console or to a file. If the property is not specified (the default case), incoming logs will be forwarded to the framework console and the getFrameworkLogger method will return a com.prosyst.util.log.ConsoleLogger object. Otherwise, in the case that the value of the mbs.log.file.dir property represents an actual directory on the local file system, the getFrameworkLogger method will return a com.prosyst.util.log.FileLogger object. Logs written by using this FileLogger will be stored in the designated directory. Refer to the com.prosyst.util.log API documentation for more information about on using ConsoleLogger and FrameworkLogger.

Configure at runtime the type of generated debug information

The framework is capable of producing and printing clear debug messages about the operation of its modules. It supports different levels of debug information, each level associated with a specific module. These levels can be changed at runtime by using the debug method of the FrameworkAccess service. In the params String[] argument, you should specify the required debug levels as follows:

• 0 – No debug
• 1 – Debug messages from the Framework core
• 2 – Debug messages from the Package Manager
• 3 – Debug messages from the Service Manager
• 4 – Debug messages from the Event Manager
• 5 – Debug messages from the Bundle Manager
• 6 – Debug messages from the Class Provider about class loading
• 7 – Debug messages from the Storage
• 8 – Debug messages about processing the startup bundles list file
• 9 – Debug messages about URL Handlers
• 10 – Basic set of security debug messages
• 11 – Extended set of security debug messages
• 12 – Full set of security debug messages
• 14 – Debug messages about start level processing
• 15 – Debug messages from the FrameworkAccess service
• 16 – Debug messages from the Fault Manager
• 17 – Debug messages from Certificate Manager
• 18 – Debug messages about execution of framework commands
• 19 – Debug messages from the Transaction Manager

Fire framework events

In some cases it is important to signal a specific event related to the framework, usually when a severe error occurs. You can use the event mechanism implemented in the framework – call the postFrameworkEvent method of the FrameworkAccess service to fire an org.osgi.framework.FrameworkEvent to all interested org.osgi.framework.FrameworkListeners in the framework.

Access bundles and some of their internal components

• Get entries and resources of specific bundles – A bundle can directly get the input stream to a resource of another bundle without the need to retrieve the entry/resource URL from the corresponding org.osgi.framework.Bundle and call URL.openStream(). This features is implemented in the getEntry and getResource methods.
• Get bundles by specific manifest header key – Some bundles use manifest headers to communicate resource paths, specific dependencies, etc. Such headers can be specified in the mbs.bundles.cacheHeaders system property. Then, interested management bundles can invoke the getBundles and hasHeader methods to quickly find the bundles containing a cached header in their manifests. Otherwise, if the header is not included in the cache list, the FrameworkAccess service will check all bundles for the required header.
• Get bundles by their location – In some cases, it is convenient to retrieve a bundle by using its path instead of by its ID or by checking all installed bundles for the desired location. The getBundle method of the FrameworkAccess service provides this feature to bundle developer.
• Access the bundle context allocated to another bundle – The getBundleContext provides access to the BundleContext dedicated to the specified bundle.

Get service references and services for "Fake" bundles

Management bundles can use the getServiceReference, getServiceReferences and getService Framework Access methods on behalf of "fake" bundles – entities that do not follow the bundle definition strictly. For example, an OSGi-aware application instance (MIDlet, Xlet, etc.) can be considered as such a "fake" bundle.

Write down measurement data or trigger a measurement event

The log and trigger methods provide access to the functionality of the Framework Measurement module so that bundles can, respectively, write information about measured parameters and make the framework measure the consumed memory or number of active threads. Refer to the "Framework Measurement" document for more information.

Get the state stamp of the framework

Each time the framework changes its state, that is, there is a change in the resolving information (e.g. a new bundle is installed), the state stamp increments thus signaling the change.

Clear the storage garbage

The Storage module can be forced to delete all the uninstalled bundles and unused data from the framework storage. The clearStorageGarbage method of the FrameworkAccess service provides access to this command.

Group related permissions into functional groups

The FrameworkAccess service allows creating and managing functional groups of permission, which can be used with the Conditional Permission Admin service for optimized permission checks (refer to the "Using a group of permissions for a single permission entry" section of the Conditional Permission Admin service document). The functionality related to functional permission groups is defined in a separate interface, com.prosyst.mbs.framework.policy.PolicyManager, extended by the interface of the FrameworkAccess service. The FrameworkAccess service keeps permission group definitions in a file within the framework storage so as to easily restore the definitions on framework restarts.

Each functional group has alias, description and set of permissions. The alias and description can be localized so as to enable a user interface application to show a meaningful name and information about the permission group. The support of localized group attributes is based on the Resource Bundle utility exported by the framework.

To create a functional permission group, use the createFunctionalGroup method. In case you will not localize the group's alias and description, you might pass null for group's description, localization file, and localization source bundle. On success, the method returns a FunctionalGroup instance – you can use it to get the content of the group as well as change its localization settings.

If you want to provide locale-specific group alias and description, follow the next instructions:

1. Create the .properties files, called with a common base name, containing the locale-specific entries according to the requirements of the Resource Bundle utility, and place them in a common directory within the relevant bundle. For example, my_perm_group.properties, my_perm_group_de.properties and my_perm_group_fr.properties within the my_l10n directory of the bundle JAR file.
2. Call the createFunctionalGroup method specifying:
   1. The key for the localized alias preceded with %.
   2. The key for the description, again preceeded with %.
   3. The Bundle object for the bundle holding the .properties files.
   4. The base name of the Resource Bundle represented by the collection of the .properties files. For example, the base name for the files from step #1 is my_l10n/my_perm_group.

The example below defines a functional permission group with localized alias and description:

import org.osgi.framework.BundleContext;
import org.osgi.service.permissionadmin.PermissionInfo;
import com.prosyst.mbs.framework.access.FrameworkAccess;
import com.prosyst.mbs.framework.policy.FunctionalGroup;

public class MyGroupPermissions {
  // The bundle context received from the OSGi framework
  BundleContext bc;
  // The instance of the FrameworkAccess service taken from OSGi framework service registry
  FrameworkAccess fwAccess;    
       . . .
  private void addGroup() {
    PermissionInfo info1 =
        new PermissionInfo("(" + PACK_PERM_TYPE + " \"org.osgi.framework\" \"import\")");
    PermissionInfo info2 =
        new PermissionInfo("(" + PACK_PERM_TYPE + " \"org.osgi.service.metatype\" \"import\")");
    PermissionInfo info3 =
        new PermissionInfo("(" + SERVICE_PERM_TYPE + " \"org.osgi.service.metatype.MetaTypeService\" \"get\")");
    // Create the permission group defining localized attributes for it
    FunctionalGroup group =
        fwAccess.createFunctionalGroup("%alias", "%description",
                                       bc.getBundle(), "my_l10n/my_perm_group",
                                       new PermissionInfo[] {info1, info2, info3}, true);
  }
}

To update the permissions in a group, use again the createFunctionalGroup method with the same alias key.

Access the arguments to the framework main class

An application might use specific command line arguments passed to the main class of the framework com.prosyst.mbs.impl.framework.Start. To access the command line arguments to the Start class, call the getMainArgs method of the FrameworkAccess service.

Register a uncaught exception manager

A Uncaught Exception Manager is called when an exception in not processed in a thread. To register such a manager, call the setUncaughtExceptionManager method of the FrameworkAccess service.