The most important tasks that can be performed through mConsole are the tasks related to administration and monitoring of OSGi frameworks. The current document describes how to administrate framework bundles, configurations, properties, etc. through mConsole.
Contents:
mConsole envelops a wide range of functions related to framework administration and monitoring, based on a convenient user interface. The features of the application could be summarized into the following:
In addition, the following features could be added by selecting the respective options:
The main tabs of the central pane are called Bundles, Packages and Remote Console.
The Bundles tab contains bundle and framework related information.
The Packages tab indicates that you are viewing information about the packages currently available in the framework.
The Remote Console tab indicates you have entered the built-in remote console.
The available menus are General, Bundles, Packages, Permissions (only if the server is in security mode), Resources (only if the framework is an mBS with Resource Management switched on) and Help.
|
* - This menu appears only if the connected framework is in security mode
** - This menu appears only if the connected framework is an mBS with the Resource Management option switched on
For convenience, some of the menu commands have their analogues on the toolbars. You can show/hide this toolbar as well as fully customize it. See Changing the Default Settings of Your mConsole for details.
The available toolbars are:
It shows up on rightclicking the mouse over the name of a bundle from the tree. All of the commands are the same as those in the Bundles menu.
Figure 1: Popup menu
mConsole possesses a collection of shortcut keys invoking the menu commands. There are two types of shortcuts in mConsole: command-specific, and formed with Alt + some key (underlined). Command-specific shortcuts are indicated near the command they arise. Figure 5 shows an example of both types.
Figure 2: Shortcuts for the menu commands
See mConsole General Description: Logging In
an OSGi Framework.
You can see the framework properties of the connected framework by selecting the Framework (root) node of the bundle tree and then the Framework Properties subtab of the right pane. (it appears by default after login to the framework). You can see properties of the software and the system here, as well as the current start levels of the framework.
Figure 3: Framework properties
The value of the Framework Start Level field indicates the current start level of the framework. As defined by the OSGi Service Platform Specification 3.0, the framework start level is used to determine which bundles to be started. A bundle will be started only if its bundle start level is no bigger than the start level of the framework. You can change the framework start level by typing it in the Framework Start Level field or by using the arrow keys. After setting the new value, press Set.
The value of the Initial Bundle Start Level field shows the default start level of bundles (each bundle may have its own start level defined, and then the value of the Initial Bundle Start Level field will be assigned to all bundles that do not have an otherwise defined start level). You can change the initial bundle start level by typing it in the Initial Bundle Start Level field or by using the arrow keys. After setting the new value, press Set.
Runtime information is available in the Runtime Info subtab that appears when you select the Framework (root) node of the bundle tree. It includes information about the running threads, memory properties (total RAM, used memory and free memory) and server classpath. This information is not editable from mConsole. You can only update the displayed information by pressing the Refresh button.
Figure 4: Runtime information
The running threads are sorted into thread groups according to the groups created by the framework's VM and the running bundles. This sorting is for convenience. Each thread is also characterized with its priority.
The Packages tab allows you to browse the available packages in the connected framework, and view miscellaneous information about them.
This view allows you to browse the list of packages in the tree on the left. The available versions of each package are listed in the node of the package. Unfold it if you want to browse them.
Figure 5.1: Package view
If a package version is displayed with the 
icon, this means that this version is really exported by a bundle in the framework.
If the display icon is 
,
the package has importers but is not exported by any bundle.
If you select this view, you can browse the available packages according to the bundle and classloader exporting them. Unfold a bundle from the tree to see all available classloaders for it. If you select a particular classloader, you can see all packages it exports. However, you cannot see information such as versions, importers, etc. Use the Package View if you need such information.
Figure 5.2: Bundle view
mConsole allows printing of the most essential information about the packages of a bundle by invoking the Packages -> Print command.
After invoking the Print command, the Page Setup dialog appears prompting you to indicate the printer and page settings. When ready, press OK.
Figure 5.3: Print dialog
To view or manage the current system properties, invoke the System Properties
dialog. This is done in one of the three ways: with Bundles -> Server
Properties, the 
button from the toolbar, or the Ctrl+P keyboard shortcut.
Figure 6: System properties dialog
To get a group of properties responding to a common criterion, select the proper filter type from the Filter Type falling list (none, starts with, ends with or contains). Type the letters/digits or word(s) you are searching for in the text field on the right and then press Get Properties. If you do not specify a filter, all server system properties will be displayed.
If you are searching for a particular property, type its name in the Property field. Now you can:
After finishing with all changes, press Close.
Note: If some of your bundles uses the system property set in this way, you must stop and then restart the bundle so that it will reflect the changes in the server properties.
For mBS framework with the Resource Manager switched on, mConsole allows you to view the resources currently occupied by the framework and the maximum resources allowed for it. These resources are managed by the Resource Manager integrated in the System Bundle of the mBS framework. See its description for details.
You can view the default resource restrictions for bundles in the framework by invoking the Resources -> Default System Resources menu command, or pressing the Resources button. A new dialog appears, showing the resource management settings.
Figure 7.1: Viewing the framework's default resources
The resource allocation diagram is invoked through Resources -> Show
diagram menu command or the 
button. It allows you to view in a diagram form the resources (such as used
memory, free memory, native libraries, etc.) occupied or allocated to each of
the bundles currently installed on the framework. The available properties are
defined by the Resource Manager of the System Bundle.
You can switch between the resource types by selecting the corresponding option from the Resources combo box of the diagram dialog.
 Figure 7.2.1: Resource allocation diagram: Archives |
 Figure 7.2.2: Resource allocation diagram: Active threads |
The default permissions are those which are initially granted to bundles when the framework is in security mode. They are determined by the Permission Admin Service as defined by the OSGi Specification.
Note: To be able to view and edit default permissions, the connected OSGi framework must be running in security mode, i.e. with the Permission Admin Service active. If there is no Permission Admin, you will not be able to see the Permissions menu, toolbar and tab. See Starting the mBedded Server Framework with Security for more information.
To define new default permissions:
button from the Permissions toolbar. You will see the Default Permissions
dialog.
Figure 8.1: Defining default permissions
The Default Permissions dialog that appears contains the available
default permissions. They are listed in the Permission Types section.
Most often, the default permission is java.security.AllPermission.
If you select a permission from the list, its properties will appear in
the Name, Description and Actions sections.
The Name section represents the name of the permission. It is specific
for each permission type. For example, if you want to get the OSGi HTTP
Service, you should pass as Name "org.osgi.service.http.HTTPService".
Some permissions do not require name.
The Description section contains the fully-qualified Java class
name of the permission. If you again want to get the HTTP Service, the Description
passed to it will be: org.osgi.framework.ServicePermission.
This field is automatically filled by the application.
The Actions section contains all possible actions that the permission will bring to bundles. This field is again specific for the permission type, and may be omitted for some permissions. For example: "get", "get,register", "*", etc.
Figure 8.2: Selecting a permission
To shut down the framework, invoke Bundles -> Shutdown Server. This will stop the running OSGi framework. Note that when you restart it, all bundles and services will be returned to their state before the shutdown. For instance, if a bundle is ACTIVE when you shut down the server, it will be returned to this state when you restart the server, and if it is RESOLVED, the bundle will be resolved when the server is restarted.
The bundle tree is shown when you enter the Bundles tab of mConsole. It displays all bundles running in the framework, sorted according to their categories. It allows you to manage the framework properties, bundles and configurations.
The root node of the bundle tree is the Framework node (
).
If you select it, you can see the framework properties
and runtime information.
A bundle category is displayed with the 
icon. If you unfold a category node, you will see the bundles it contains. Active
(started) bundles are shown with the 
icon. Inactive (resolved or installed) bundles are shown with the 
icon.
Some bundle nodes can be unfolded too. These are the bundles that contain configuration
resources. A single configuration is displayed with the 
icon. A factory configuration is displayed with the 
icon.
Figure 9.1: Components of the bundle tree
To view general information about a bundle, select it from the bundle tree. General information appears in the General subtab of the right pane.
Figure 9.2: General bundle properties
Most of the information displayed in the General tab is non-editable.
The ID property indicates the ID assigned to this bundle by the framework. The State property indicates the current state of the lifecycle of the bundle (ACTIVE, RESOLVED, INSTALLED, etc.). The Location field indicates the URL of the bundle JAR file. The Category field contains the bundle category.
The Start Level field is the only editable field in this section. It indicates the current start level of the bundle. To define a new value, type it directly in the editable text field or use the up and down arrows next to the field. When ready with the new value, press Set.
The Persistently Started field shows if the current bundle is marked by the framework as persistently started or persistently stopped.
The Manifest Header section shows information extracted from the bundle's manifest. The headers are contained in the left column and their corresponding values are placed in the right column of the table.
The Registered Interfaces section is an important feature of the bundle's services. It indicates the service interfaces this bundle has exported.
The Description field shows a free-text description of the bundle.
To view the services exported by a particular bundle, select it from the bundle tree and enter the Services subtab of the right pane.
Figure 10: Services tab
The uppermost pane of the Services tab contains a list of all services (displayed with their IDs) exported by this bundle. If you select a service from this list, the information about it will be displayed in the rest of the panes of this tab.
The Service ID field shows the ID of the selected service.
The Object Classes pane shows all object classes under which this service is registered (a single service can be registered under more than one object class).
The Service Properties section shows the registration properties and their values of the selected service.
The Bundles that Use This Service section lists all bundles in the framework that use this service (i.e. import it from the framework).
This is possible only if the connected server is in security mode, i.e. with the OSGi Permission Admin Service active. See also Starting the mBS Framework with Security for more information.
If you select a bundle from the tree, a new tab appears on the right: the Permissions tab.
Figure 11.1: The selected bundle's default permissions
The Permission Types pane contains a list of all default permissions the bundle currently owns. The Info pane contains the information about the selected permission.
The Name section represents the name of the permission. It is specific
for each permission type. For example, if you want to get the OSGi HTTP Service,
you should pass as Name "org.osgi.service.http.HttpService".
Some permissions do not require name.
The Description section contains the fully-qualified Java class name
of the permission and, optionally, some description of it. If you again want
to get the HTTP Service, the Description passed to it will be: org.osgi.framework.ServicePermission.
This field is automatically filled by the application.
The Actions section contains all possible actions that the permission will bring to bundles. This field is again specific for the permission type, and may be omitted for some permissions. For example: "get", "get,register", "*", etc.
To define a new default permission:
Figure 11.2: Selecting a permission
Note: Viewing a bundle's resources is possible only on mBS with Resource Manager switched on. If the connected framework is not an mBS or does not have the Resource Manager activated, you will not see the Resource Monitor tab, the Resources menu and toolbar.
To view the resources that the bundle needs and is allowed to use, select it from the bundle tree and enter the Resource Monitor subtab of the right pane.
This tab is divided into two sections. The Resource Requirements section contains all resources (data storage space, new/old segment size, etc.) that the bundle needs. These resources are described in the resource requirement XML file contained in its JAR.
The Resource Allocations section describes the resources (native libraries, data storage, used memory, allocated memory, etc.) currently occupied by the bundle.
You can print the bundle resource information by pressing the Print button at the bottom of the pane or by invoking the Resources -> Print command.
Figure 12: Viewing a bundle's resources
To view or edit the configuration resources of a bundle, enter the Bundles tab. If the bundle contains configurable resources (not all bundles do), then the bundle's node in the bundle tree can be unfolded and its configurations will appear as subnodes of the bundle.
When you select a bundle configuration, its properties appear in the right pane in an mConsole GUI component called property editor.
Figure 13.1: General property editor for factory configurations
A property editor is a GUI component of mConsole that allows you to view and edit the configurable resources of a bundle.
There are two types of property editors: custom editors, and a default property editor (also called general property editor). Custom property editors can be created for each service configuration with specific properties. Some of the services distributed with the ProSyst mBS packages have such. For all services without a custom property editor, the general property editor, built in mConsole, is invoked.
The general property editor exists in two variants: one for single configurations and one for factory configurations.
Editing a Single Configuration. The general property editor for single configurations is shown in Figure 13.2.1. Below the list of available properties, there is a set of buttons for manipulating the displayed configuration.
Figure 13.2.1: General property editor for single configurations
To edit the value of a configuration property:
Note: The new value you have defined for a property will not be set to the configuration if you don't press the Set button!
To edit the properties contained in the current configuration:
Figure 13.2.2: Selecting the set of properties that
will be available in the configuration
The Refresh button refreshes the editor's pane to reflect any changes occurred to it while it has been open.
If you want to restore the default settings of the current configuration (as
contained in its MetatypeProvider), press Defaults.
Editing a Factory Configuration. The general property editor for factory configurations is displayed in Figure 13.1. The uppermost pane lists the configurations instances (displayed with their PIDs) contained in the factory. You can switch among them by selecting them from the list. The selected PID's properties will appear below.
Editing the properties contained in a configuration instance is done as described in Editing a Single Configuration.
To create a new configuration instance:
Figure 13.3.1: Creating a new configuration instance
To remove a configuration, select it from the list and press Remove.
A custom property editor may contain any components, and its usage may be different from the usage of the general property editor. Figure 13.4 shows a sample custom property editor (the one of the Log Bundle).
Figure 13.4: Custom property editor (the one of the Log
Bundle in this case)
We cannot include a procedure for working with custom property editors here because each such editor can contain its own specific components and principles for work. Using the custom property editor for each ProSyst bundle having such is included in the bundle's description document.
By installing a bundle you provide its resources to the framework but without activating it.
Hint: You can enable mConsole to start bundles automatically after installing them by checking the Start bundle after installing option (General -> Settings -> Bundles).
After a bundle is installed, it is in RESOLVED or INSTALLED state. A bundle is in RESOLVED state if all package dependencies are satisfied. mConsole takes care during the installation to inform the users if there are some packages missing. If you install the bundle without the other related bundles, it will be in INSTALLED state. When you have all package dependencies satisfied, the bundle is ready to be started.
A bundle can be installed from a file location on the local machine or reached through a given remote URL.
To install a new bundle:
button
from the Bundles toolbar
Figure 14.1: Installing a bundle from JAR file
Figure 14.2: Installing a bundle from URL
Tip: When you are installing a bundle from a URL, make sure it is a valid.
When installing a bundle from a local file path, its installation location, with which it will be identified in the framework, depends on the bundle installation settings defined in the Bundles tab of the Settings dialog. If the "Use internal HTTP server when installing" option is turned on (it is on by default), then the bundle location will be an HTTP-based URL containing the bundle's alias defined in the HTTP Server settings (you don't need to manually create bundle aliases because mConsole automatically creates an alias for each bundle JAR file pointed for installation). If this option is turned off, however, but the HTTP server is still running, the installation location will be again an HTTP URL. The only difference is that the PMP Service will be used to deliver the bundle to the framework, not the internal HTTP server. If the HTTP server is stopped, the bundle location will be a file URL (such as "C:\mBeddedServer\bundles\devicem.jar").
Troubleshooting: If mConsole refuses to install your JAR as a bundle, this might be due to a wrong manifest header or any other problem with the JAR or its components. To learn the exact reason, click Details from the error dialog that appears.
If there is a bundle you want to remove from the server, select it from the bundle tree and choose the Uninstall Bundle command. With this command, the bundle is taken to UNINSTALLED state. It removes the bundle permanently and it no longer exists on the server.
Note: If you are connected to an mBedded Server and have enabled lazy update, the bundle JAR will still be available in the framework after uninstalling if there are importers of its packages. If this is some other OSGi framework or the mode of the mBS is eager update, uninstalling the bundle will lead to problems with the performance of dependent bundles.
When you start a bundle, it begins operating withing the framework, i.e gets/registers services, creates threads, registers listeners, etc. Before that, the bundle is only installed, i.e. only its exported packages are available to other bundles.
To start a bundle, use the Bundle -> Start Bundle command or some of its analogues.
Troubleshooting: If you have any problems starting a bundle, this may be due to unavailable packages that this bundle imports. In such case, mConsole displays a dialog pane describing the missing packages and asks you whether you want your bundle to be installed anyway. You must install the bundles exporting the missing packages to be able to start the bundle.
A similar problem might arise if there is an incorrect header in your bundle manifest. To learn the exact problem, click Details from the error dialog that appears (Figure 14.3).
Stopping a bundle means taking it from ACTIVE to RESOLVED state. Use the Stop Bundle command of the Bundle menu or some of its analogues.
Warning: If you stop a bundle that other active bundles are dependent on, this will most probably lead to problems with the performance of these bundles!
If a bundle that has already been installed or started has changed, you need to update it so that the changes will be reflected in the Framework.
Note: For ProSyst mBS, there are two ways to update a bundle: with eager update or with lazy update. You can choose between them in the Bundle-Related Settings.
Eager update - this is the default update mode for mBS. Let's have a bundle which exports some packages used by a number of bundles. If this bundle is updated, the new JAR may not provide the same packages or the same versions of the packages. So what happens to the importers of the missing packages? They become stopped and then, if the new bundle JAR again exports them (with the same or higher version), become started by a new classloader. If the used packages are not provided, they remain stopped.
Lazy update - in this mode the old bundle JAR and the package versions provided by it remain available in the framework and can be used by the importers. Those bundles do not become restarted. The old JAR is called zombie. The new updated JAR becomes started but does not export its packages until all users of the zombie's packages become stopped. When all of them become stopped, the zombie bundle disappears and the new JAR provides its packages.
Warning: On invoking this command or some of its alternatives, the bundle is uninstalled before it becomes updated. If you perform a lazy-update operation, this may cause the same problems as stopping it.
You will be able to indicate a local path or a URL. See Figure 14.1 and Figure 14.2.
Once installed with the Framework, bundles declare various types of dependencies, such as classpath, native code, package and service dependencies.
To view the import/export dependencies (package dependencies) of a bundle, select it from the bundles' tree and choose Bundles -> Bundle Diagram or rightclick the mouse over the bundle and choose Bundle Diagram from the popup menu. The information that appears is displayed in the form of a diagram or plain text, depending on the option selected in Options -> Settings (see Bundle-Related Settings).
 |
 |
| Figure 15.1: A graphical bundle diagram | Figure 15.2: A plain text bundle diagram |
In the diagram shown in Figure 15.1 and 15.2, the selected bundle is the DB
Bundle. It imports the com.prosyst.util.hash, com.prosyst.mbs.framework.flash
and com.prosyst.util.io packages from the System Bundle, and the
com.prosyst.util.ref package from the ProSyst Util Bundle. The
export package is the com.prosyst.mbs.services.db, consumed by
the Config Bundle and the UserAdmin Bundle.
Every bundle shown on a certain bundle diagram has a link to its own diagram.
If you choose the graphical representation of the bundle dependencies, you will see which bundles export packages to the selected bundle and which bundles import packages from it, in turn.
If you choose the textual representation, you can see more detailed information about the dependencies of the current bundle. You can learn the packages this bundle exports and imports, and which bundles they are exported to or imported from, respectively.
The remote console tool is reached by entering the Remote Console tab of the main window. This is a standard console allowing you to fire mBedded Server console commands to the connected server. It is based on PMP's custom event system.
If you do not redirect these streams to the remote console, you will not be able to view the messages sent by bundles or services. They will be displayed in the default console of the framework. You will only be able to send commands.
Redirecting console output is done with the following command in the mConsole remote console:
fw>$dump Sets the current output to the System.out and System.err.
After finishing your work with mConsole, you may wish to reset the default
settings. To do so, you only need to retype dump in mConsole's
remote console:
fw>$dump Returns the standard system output.
The properties of the remote console may be edited by entering the Container Console tab of the Settings dialog, the Ctrl+O shortcut keys, or rightclicking the mouse over the console.
Figure 16: The remote console
To manage the properties of your mConsole, choose General -> Settings
or press the 
button from the toolbar. The default tabs contained in this dialog are described
in mConsole General Description: Changing
the Default Settings of Your mConsole.
When you establish connection to an OSGi framework, a new tab appears to the
Settings dialog - the Bundles tab. It allows you to manage bundle-related
settings.
To customize the behaviour of mConsole on bundle-related events, enter the Bundles tab of the Settings dialog. It contains four sections:
Note: This option is available for users with administrative rights only!
Figure 17: Bundle-related settings
ProSyst mConsole works successfully with other vendor OSGi frameworks, and can execute basic bundle operations - install/start/stop/update of bundles, as well as can provide basic bundle and framework information. mConsole does not support only functionality related to resource management and package administration.
You can run the ProSyst bundles needed for PMP support and for communication with mConsole by using OSGi services implemented by other vendors - Package Admin service, Permission Admin service, Conditional Permission Admin service, HTTP Service, Log Service, Metatype Service, Configuration Admin service, User Admin Service, Device Manager, Preferences Service, Service Component Runtime, Event Admin service, etc.
These PMP-required bundles are:
It is expected that the vendor of the target OSGi framework provides the base OSGi and J2ME packages necessary for resolving the above bundles.
Note: To be able to connect the mConsole to the R4 Reference Implementation in case the framework does not run its OSGi User Admin, install the ProSyst bundle, listed above, with the mbs.useradmin.anonymousConnect system property set to true prior to installing the User Admin Extension Full Bundle. Otherwise, you have to restart the bundle.
Note: The javax.microedition.io J2ME package is not exported by the R4 Reference Implementation and Eclipse Equinox OSGi frameworks. It is expected that the underlying JVM supplies the package. For resolving reasons mainly, the javax.microedition.io package is available in the ProSyst Util Full Bundle with the JVM having priority over the ProSyst Util Full Bundle.
