com.prosyst.mbs.framework.access
Interface FrameworkAccess

public interface FrameworkAccess

This interface represents a service, whose methods allow execution of additional framework operations as pluggable commands.

Method Summary

void	clearStorageGarbage(java.io.PrintStream stream) This method clears the garbage of the framework storage.
boolean	debug(java.lang.String[] params, java.io.PrintStream stream) Changes the debug state of the framework.
boolean	deleteFunctionalPermissionGroup(java.lang.String alias) Delete a functional permission group from the list of groups.
void	flushDumps() Flushes file output stream to which System.out is redirected, so that all dumps are saved.
Bundle	getBundle(java.lang.ClassLoader cl)
Bundle	getBundle(java.lang.String location) Returns the bundle, which has the specified location.
BundleContext	getBundleContext(Bundle b) Get the BundleContext of the supplied Bundle.
java.lang.String	getBundleFilePath(Bundle bundle) This method return the name of the archive, where the framework stores the specified bundle.
Bundle[]	getBundles(java.lang.String key) Returns a list with all installed bundles, which have key as a manifest header.
Bundle[]	getBundlesInRoot(java.lang.String storageRoot) Returns all bundles that are installed under this storage root.
java.io.InputStream	getEntry(Bundle bundle, java.lang.String name, java.lang.String cname) Reads a resource from bundle
java.lang.String	getFileUrl(java.net.URL resourceUrl) Convert a storage URL to a file URL.
com.prosyst.util.log.Logger	getFrameworkLogger() This method is used to retrieve the logger used by the framework, so for example the Log bundle can use the same logger to store it's entries.
int	getFrameworkStateStamp() Get the framework's resolve info state stamp.
long	getLastMountTime(java.lang.String storageRoot) This method returns the last time, when that storage was mounted (e.g.
int	getLazyState(Bundle b) Returns the lazy state of the bundle.
java.io.InputStream	getResource(Bundle bundle, java.lang.String name) Reads a resource from bundle
java.lang.Object	getService(ServiceReference reference, Bundle b) Get a service object for this (fake) bundle
ServiceReference	getServiceReference(java.lang.String name, Bundle b) Get a service reference for this (fake) bundle
ServiceReference[]	getServiceReferences(java.lang.String name, java.lang.String filter, Bundle b) Get a all references for this (fake) bundle, that match the specified filter
java.lang.String[]	getStorageRoots() Lists all storage roots created with installBundleInSpecificStorage .
boolean	hasHeader(Bundle b, java.lang.String header) Checks if the specified bundle's manifest contains the specified header
Bundle	installBundleFromFile(java.lang.String location, boolean dataFilesInMainStorage) When the bundle is installed by the BundleContext, the framework copies the bundle jar file in the storage.
Bundle	installBundleFromFile(java.lang.String location, java.lang.String fileName) Install a bundle "from file", but with a location different from its file name.
Bundle	installBundleInSpecificStorage(java.lang.String storageRoot, java.lang.String location, java.io.InputStream in, boolean setSymbolicNameAsLocation) Install a bundle from input stream.
boolean	isLazyServiceReferenced(ServiceReference ref) Checks if this service is lazy.
void	log(java.lang.String measurement, boolean display) Logs a measurement.
void	postFrameworkEvent(int type, Bundle b, java.lang.Throwable t) Publish a FrameworkEvent
void	setResolvable(boolean flag, Bundle b) Sets resolving flag of a bundle
void	startLazy(Bundle b) Tries to put the bundle in the active lazy state.
void	storageDirStateChanged(java.lang.String dirName, boolean isPlugged) Notify the framework that a flash card with an installed bundle is unplugged or plugged.
boolean	storeFunctionalPermissionGroup(java.lang.String alias, PermissionInfo[] permissions, boolean store) Write all information needed to create a functional permission group
void	trigger(java.lang.String module) Forces measurements for process, heap and flash memory.
boolean	ungetService(ServiceReference reference, Bundle b) Ungets the specified service from the specified bundle.
void	ungetServices(java.util.Vector serviceReferences, Bundle b) Unget all services for this (fake) bundle.
void	updateBundle(Bundle b, java.lang.String url, boolean keep, java.io.PrintStream stream) Updates the bundle with the specified ID without deleting its data files.

Method Detail

installBundleFromFile

Bundle installBundleFromFile(java.lang.String location,
                             boolean dataFilesInMainStorage)
                             throws BundleException

When the bundle is installed by the BundleContext, the framework copies the bundle jar file in the storage. If the bundle is installed by this method, the framework wouldn't copy the bundle in the storage. Also you can specify if the bundle data files will be created in the main storage or not. If it's not in main storage, the storage bundle data files will be created in the bundle's parent folder in a separate 'data' folder.

Parameters:

location - the location of the file to install - and location string for the new bundle

dataFilesInMainStorage - it specifies where the bundle data files will be created.

Returns:

the created bundle object

Throws:

BundleException - if installation failed

installBundleFromFile

Bundle installBundleFromFile(java.lang.String location,
                             java.lang.String fileName)
                             throws BundleException

Install a bundle "from file", but with a location different from its file name.

Parameters:

location - the location of the bundle to install

fileName - the location of the source file

Returns:

the installed bundle

Throws:

BundleException - if installation failed

installBundleInSpecificStorage

Bundle installBundleInSpecificStorage(java.lang.String storageRoot,
                                      java.lang.String location,
                                      java.io.InputStream in,
                                      boolean setSymbolicNameAsLocation)
                                      throws BundleException

Install a bundle from input stream. Store the stream data in the specified storage root with the specified file name. If the parameter setSymbolicName has value true, then the bundle location will be the Bundle-SymbolicName and the parameter location must be a file name. This file name will be used to create a readable file name in the storage. If the parameter has value false, then the bundle location will be the parameter location and the file name of this location will be used in the storage. The only one parameter storageRoot can be null. If it's null, the bundle will be installed in the main storage.

Parameters:

storageRoot - the folder where the storage for this bundle will be placed

location - if the setSymbolicName is true, this must specify the bundle file name in the storage otherwise the bundle location

in - the input stream of the installing bundle

setSymbolicNameAsLocation - if it's true, the bundle.getLocation() will return the Bundle-SymbolicName otherwise it'll return the specified location.

Returns:

the installed bundle

Throws:

BundleException - if installation failed

See Also:

getStorageRoots(), getBundlesInRoot(String)

getStorageRoots

java.lang.String[] getStorageRoots()

Lists all storage roots created with installBundleInSpecificStorage . When a storage root is unmounted, its name will still be available through this method, until all bundles that were installed under this root are uninstalled.

Returns:

A String[] containing all storage roots, or null if no roots have been created.

See Also:

installBundleInSpecificStorage(String, String, InputStream, boolean), getBundlesInRoot(String)

getLastMountTime

long getLastMountTime(java.lang.String storageRoot)

This method returns the last time, when that storage was mounted (e.g. the card was inserted)

Parameters:

storageRoot - when the card was last inserted

Returns:

the last time the specified storage was mounted

Throws:

java.util.NoSuchElementException - if the storage is unknown.

See Also:

getStorageRoots()

getBundlesInRoot

Bundle[] getBundlesInRoot(java.lang.String storageRoot)

Returns all bundles that are installed under this storage root.

Parameters:

storageRoot - The root to search. It must be exactly the same String, as the one passed to installBundleInSpecificStorage

Returns:

A list with all bundles installed under this root, or null if no bundles were found.

See Also:

getStorageRoots(), installBundleInSpecificStorage(String, String, InputStream, boolean)

updateBundle

void updateBundle(Bundle b,
                  java.lang.String url,
                  boolean keep,
                  java.io.PrintStream stream)
                  throws BundleException

Updates the bundle with the specified ID without deleting its data files.

Parameters:

b - the bundle for updating.

url - the update URL, or null

keep - if true, the data files of the bundle will not be deleted

stream - the output stream for the command result.

Throws:

BundleException - if any bundle exception has occurred during the execution of the command.

storageDirStateChanged

void storageDirStateChanged(java.lang.String dirName,
                            boolean isPlugged)

Notify the framework that a flash card with an installed bundle is unplugged or plugged.

Parameters:

dirName - a folder (flash) which is unplugged or plugged.

isPlugged - indicate if the folder is unplugged or plugged

clearStorageGarbage

void clearStorageGarbage(java.io.PrintStream stream)

This method clears the garbage of the framework storage.

Parameters:

stream - the output stream for the command result.

getFileUrl

java.lang.String getFileUrl(java.net.URL resourceUrl)
                            throws java.io.IOException

Convert a storage URL to a file URL.

Parameters:

resourceUrl - the URL pointing to a storage resources

Returns:

direct file pointer to the the storage resource

Throws:

java.io.IOException

getFrameworkStateStamp

int getFrameworkStateStamp()

Get the framework's resolve info state stamp. The state is incremented after every resolve info change and is stored persistently.

Returns:

the resolve info state stamp.

storeFunctionalPermissionGroup

boolean storeFunctionalPermissionGroup(java.lang.String alias,
                                       PermissionInfo[] permissions,
                                       boolean store)

Write all information needed to create a functional permission group

Parameters:

alias - the alias for the permission group

permissions - an array containing PermissionInfo objects for permissions associated with this functional group

store - when set to false, the functional group data will be cached in memory, instead of being committed to persistent storage. When set to true, all cached functional groups will be committed to storage.

Returns:

true if the alias has been stored successfully, false otherwise

deleteFunctionalPermissionGroup

boolean deleteFunctionalPermissionGroup(java.lang.String alias)

Delete a functional permission group from the list of groups.

Parameters:

alias - the name of the group to delete

Returns:

true if the operations completed successfully, false otherwise

isLazyServiceReferenced

boolean isLazyServiceReferenced(ServiceReference ref)
                                throws BundleException

Checks if this service is lazy.

Parameters:

ref - Reference to the service to check.

Returns:

true if the service is registered and still is lazy.

Throws:

BundleException - if the framework is not started in lazy mode

getLazyState

int getLazyState(Bundle b)
                 throws BundleException

Returns the lazy state of the bundle. The following states are defined:

0 - The bundle has no lazy features. It either has no lazy manifest headers, or has been explicitly started/stopped.

1 - The bundle is either resolved lazy, or active lazy, but started automatically, so it keeps its lazy features.

2 - The bundle is in the process of automatic starting.

3 - The bundle is active, but started automatically, so it keeps its lazy features.

Parameters:

b - The bundle to check.

Returns:

the lazy state of the bundle

Throws:

BundleException - if the framework is not started in lazy mode

startLazy

void startLazy(Bundle b)
               throws BundleException

Tries to put the bundle in the active lazy state.

Parameters:

b - The bundle to activate lazy.

Throws:

BundleException - If some exception during the lazy activation occurs or if the framework is not started in the lazy mode.

getResource

java.io.InputStream getResource(Bundle bundle,
                                java.lang.String name)

Reads a resource from bundle

Parameters:

bundle - the bundle

name - the name of the resource, that belong to the bundle

Returns:

stream to resource or null

See Also:

Bundle.getResource(String)

getEntry

java.io.InputStream getEntry(Bundle bundle,
                             java.lang.String name,
                             java.lang.String cname)

Reads a resource from bundle

Parameters:

bundle - the bundle

name - the name of the resource, that belong to the bundle

cname - An optional class name, if the required resource is a class file. Used to optimize loading class files from jxe-s.

Returns:

stream to resource or null

See Also:

Bundle.getEntry(String)

getBundleContext

BundleContext getBundleContext(Bundle b)

Get the BundleContext of the supplied Bundle. The returned object is valid until the bundle is updated or uninstalled.

Parameters:

b - The bundle that the required context belongs to.

Returns:

The context of this bundle, or null if the bundle was uninstalled.

postFrameworkEvent

void postFrameworkEvent(int type,
                        Bundle b,
                        java.lang.Throwable t)

Publish a FrameworkEvent

Parameters:

type - The event type.

b - The event source.

t - The related exception. This argument may be null if there is no related exception.

getServiceReference

ServiceReference getServiceReference(java.lang.String name,
                                     Bundle b)

Get a service reference for this (fake) bundle

Parameters:

name - The object class of the required service

b - The (fake) bundle

Returns:

A reference to the service, or null if the service is not accessible

getServiceReferences

ServiceReference[] getServiceReferences(java.lang.String name,
                                        java.lang.String filter,
                                        Bundle b)
                                        throws InvalidSyntaxException

Get a all references for this (fake) bundle, that match the specified filter

Parameters:

name - The object class of the required service

filter - Additional filter, that the returned references must match

b - The (fake) bundle

Returns:

A reference to the service, or null if the service is not accessible

Throws:

InvalidSyntaxException - if the filter syntax is not correct

getService

java.lang.Object getService(ServiceReference reference,
                            Bundle b)

Get a service object for this (fake) bundle

Parameters:

reference - The reference to the service

b - The (fake) bundle

Returns:

The service instance, or null if the service is not accessible

ungetServices

void ungetServices(java.util.Vector serviceReferences,
                   Bundle b)

Unget all services for this (fake) bundle. This will not just decrease the usage counter for the (fake) bundle, but will completely remove the service dependency.

Parameters:

serviceReferences - A list containing all the ServiceReference

b -

ungetService

boolean ungetService(ServiceReference reference,
                     Bundle b)

Ungets the specified service from the specified bundle. The result is the same as if the bundle context of the specified bundle was used to unget the service.

Parameters:

reference -

b -

Returns:

false if the context bundle's use count for the service is zero or if the service has been unregistered; true otherwise.

getBundles

Bundle[] getBundles(java.lang.String key)

Returns a list with all installed bundles, which have key as a manifest header.

Parameters:

key - the header name, that the bundle should have in it's manifest

Returns:

a list of bundles containing the specified header

getBundle

Bundle getBundle(java.lang.String location)

Returns the bundle, which has the specified location. If there is no bundle, installed in the framework, with the specified location null is returned.

Parameters:

location -

Returns:

the bundle or null

hasHeader

boolean hasHeader(Bundle b,
                  java.lang.String header)

Checks if the specified bundle's manifest contains the specified header

Parameters:

b - the bundle

header - the header name

Returns:

true if the bundle has the specified header

debug

boolean debug(java.lang.String[] params,
              java.io.PrintStream stream)

Changes the debug state of the framework.

Parameters:

params - holds the new states of the debug levels.

stream - the output stream for the command result.

Returns:

false only if there is no debug otherwise true

setResolvable

void setResolvable(boolean flag,
                   Bundle b)
                   throws BundleException

Sets resolving flag of a bundle

Parameters:

flag -

b -

Throws:

BundleException - If the bundle is the System bundle, or a timeout occurs

flushDumps

void flushDumps()

Flushes file output stream to which System.out is redirected, so that all dumps are saved. It is applicable if and only if System.out is redirected to file.

log

void log(java.lang.String measurement,
         boolean display)

Logs a measurement. If framework is not started in measurements mode, the method does nothing.

Parameters:

measurement - specifies the measurement, which is to be logged

display - indicates whether the message should be displayed in native GUI

trigger

void trigger(java.lang.String module)

Forces measurements for process, heap and flash memory. If framework is not started in measurements mode, the method does nothing. If mbs.measurements.heapMemory is set to true then heap memory measurements are performed. If mbs.measurements.processMemory is set to true then process memory measurements are performed. If mbs.measurements.flashMemory is set to true then flash memory measurements (i.e. storage size) are performed.

Parameters:

module - specifies the module, which forced the measurement

getFrameworkLogger

com.prosyst.util.log.Logger getFrameworkLogger()

This method is used to retrieve the logger used by the framework, so for example the Log bundle can use the same logger to store it's entries.

Returns:

the framework logger.

getBundle

Bundle getBundle(java.lang.ClassLoader cl)

getBundleFilePath

java.lang.String getBundleFilePath(Bundle bundle)

This method return the name of the archive, where the framework stores the specified bundle.

Parameters:

bundle - the bundle object

Returns:

the file system location of the specified bundle archive