Class Felix
- All Implemented Interfaces:
Comparable<Bundle>
,Bundle
,BundleReference
,Framework
,BundleRevisions
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
Simple class that is used in refreshPackages() to embody the refresh logic in order to keep the code clean.private static class
(package private) class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
private static final int
(package private) List
private int
private final String[]
private final boolean[]
private final Object[]
private final URLStreamHandler
private BundleCache
private final Map
private final Map
private final BundleRevisionDependencies
private final EventDispatcher
private final ExtensionManager
private final FrameworkStartLevelImpl
private final FrameworkWiringImpl
private int
private Thread
private final List
private Map[]
private final Object[]
private final Map
private final Logger
private long
private final Object
private final ServiceRegistry
private final StatefulResolver
(package private) static final SecureAction
private boolean
private SecurityManager
private SecurityProvider
private ThreadGate
private final SortedSet
<Felix.StartLevelTuple> private int
private List
<BundleImpl> private URLHandlersActivator
Fields inherited from interface org.osgi.framework.Bundle
ACTIVE, INSTALLED, RESOLVED, SIGNERS_ALL, SIGNERS_TRUSTED, START_ACTIVATION_POLICY, START_TRANSIENT, STARTING, STOP_TRANSIENT, STOPPING, UNINSTALLED
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) String
(package private) void
acquireBundleLock
(BundleImpl bundle, int desiredStates) This method acquires the lock for the specified bundle as long as the bundle is in one of the specified states.(package private) boolean
Attempts to acquire the global lock.(package private) void
acquireInstallLock
(String location) (package private) void
activateBundle
(BundleImpl bundle, boolean fireEvent) <A> A
Adapt this bundle to the specified type.(package private) void
addBundleListener
(BundleImpl bundle, BundleListener l) (package private) void
addFrameworkListener
(BundleImpl bundle, FrameworkListener l) (package private) void
addServiceListener
(BundleImpl bundle, ServiceListener l, String f) Implementation for BundleContext.addServiceListener().(package private) void
(package private) boolean
bundleHasPermission
(BundleImpl bundle, Object obj) private static String
The main purpose of this method is to turn a.b.c-SNAPSHOT into a.b.c.SNAPSHOT it can also deal with a.b-SNAPSHOT and turns it into a.b.0.SNAPSHOT and will leave the dash in a.b.c.something-else, as it's valid in that last example.(package private) void
close()
private BundleActivator
createBundleActivator
(Bundle impl) private Map
createUnmodifiableMap
(Map mutableMap) (package private) Enumeration
findBundleEntries
(BundleImpl bundle, String path, String filePattern, boolean recurse) Implementation for Bundle.findEntries().(package private) Enumeration
findBundleEntries
(BundleRevision revision, String path, String filePattern, boolean recurse) Implementation for BundleWiring.findEntries().(package private) Collection
<BundleCapability> findProviders
(Requirement requirement) (package private) void
fireBundleEvent
(int type, Bundle bundle) Fires bundle events.(package private) void
fireBundleEvent
(int type, Bundle bundle, Bundle origin) (package private) void
fireFrameworkEvent
(int type, Bundle bundle, Throwable throwable) Fires bundle events.private void
fireServiceEvent
(ServiceEvent event, Dictionary oldProps) Fires service events.private void
forgetUninstalledBundle
(BundleImpl bundle) (package private) int
Returns the active start level of the framework; this method implements functionality for the Start Level service.(package private) ServiceReference[]
getAllowedServiceReferences
(BundleImpl bundle, String className, String expr, boolean checkAssignable) Retrieves Array ofServiceReference
objects based on calling bundle, service class name, optional filter expression, and optionally filters further on the version.(package private) String[]
(package private) boolean[]
(package private) Bundle
getBundle
(long id) Retrieves a bundle by its identifier and avoids bundles hooks.(package private) Bundle
This method returns the bundle associated with the specified class if the class was loaded from a bundle from this framework instance.(package private) Bundle
Retrieves a bundle from its location.(package private) Bundle
getBundle
(BundleContext bc, long id) Implementation for BundleContext.getBundle().(package private) URL
getBundleEntry
(BundleImpl bundle, String name) Implementation for Bundle.getEntry().(package private) Enumeration
getBundleEntryPaths
(BundleImpl bundle, String path) Implementation for Bundle.getEntryPaths().(package private) Dictionary
getBundleHeaders
(BundleImpl bundle, String locale) Get bundle headers and resolve any localized strings from resource bundles.long
Returns this bundle's unique identifier.(package private) ServiceReference[]
(package private) URL
getBundleResource
(BundleImpl bundle, String name) Implementation for Bundle.getResource().(package private) Enumeration
getBundleResources
(BundleImpl bundle, String name) Implementation for Bundle.getResources().(package private) Bundle[]
Retrieves all installed bundles and avoids bundles hooks.(package private) Bundle[]
Implementation for BundleContext.getBundles().(package private) ServiceReference[]
getBundleServicesInUse
(Bundle bundle) (package private) int
getBundleStartLevel
(Bundle bundle) Returns the start level for the specified bundle; this method implements functionality for the Start Level service.(package private) URLStreamHandler
(package private) Map
(package private) Object
getContentHandlerService
(String mimeType) (package private) File
getDataFile
(BundleImpl bundle, String s) (package private) BundleRevisionDependencies
(package private) Collection
<Bundle> getDependencyClosure
(Collection<Bundle> targets) (package private) ExportedPackage[]
getExportedPackages
(String pkgName) Returns the exported packages associated with the specified package name.(package private) ExportedPackage[]
Returns an array of all actively exported packages from the specified bundle or if the specified bundle is null an array containing all actively exported packages by all bundles.private void
getExportedPackages
(Bundle bundle, List list) Adds any current active exported packages from the specified bundle to the passed in list.(package private) Felix
private static String
Read the framework version from the property file.<S> Set
<ServiceReference<S>> getImportingBundles
(BundleImpl exporter, BundleCapability cap) (package private) int
Returns the start level into which newly installed bundles will be placed by default; this method implements functionality for the Start Level service.long
Returns the time when this bundle was last modified.(package private) Logger
private long
int
(package private) String
getProperty
(String key) Implementation for BundleContext.getProperty().(package private) Collection
<Bundle> getRequiringBundles
(BundleImpl bundle) (package private) StatefulResolver
(package private) SecurityProvider
(package private) <S> S
getService
(Bundle bundle, ServiceReference<S> ref, boolean isPrototype) (package private) ServiceReference[]
getServiceReferences
(BundleImpl bundle, String className, String expr, boolean checkAssignable) Retrieves an array ofServiceReference
objects based on calling bundle, service class name, and filter expression.(package private) Object
getSignerMatcher
(BundleImpl bundle, int signersType) (package private) int
getStartLevel
(int defaultLevel) Overrides standard BundleImpl.getStartLevel() behavior to always return zero for the system bundle.(package private) Object
getStreamHandlerService
(String protocol) boolean
hasPermission
(Object obj) Determines if this bundle has the specified permissions.(package private) boolean
impliesBundlePermission
(BundleProtectionDomain bundleProtectionDomain, Permission permission, boolean direct) void
init()
Initialize this Framework.void
init
(FrameworkListener... listeners) Initialize this Framework.private void
(package private) Bundle
installBundle
(Bundle origin, String location, InputStream is) (package private) boolean
isBundleActivationPolicyUsed
(Bundle bundle) Returns whether the bundle is using its declared activation policy; this is an method implementation for the Start Level service.(package private) boolean
isBundlePersistentlyStarted
(Bundle bundle) Returns whether a bundle is persistently started; this is an method implementation for the Start Level service.(package private) boolean
(package private) Class
loadBundleClass
(BundleImpl bundle, String name) Implementation for Bundle.loadClass().private void
loadFromDefaultIfNotDefined
(Properties defaultProperties, String propertyName) private long
Generated the next valid bundle identifier.private void
loadPrefixFromDefaultIfNotDefined
(Map configMap, Properties defaultProperties, String prefix) private void
populateDependentGraph
(BundleImpl exporter, Set<Bundle> set) private void
refreshBundle
(BundleImpl bundle) (package private) void
refreshPackages
(Collection<Bundle> targets, FrameworkListener[] listeners) (package private) ServiceRegistration
registerService
(BundleContextImpl context, String[] classNames, Object svcObj, Dictionary dict) Implementation for BundleContext.registerService().(package private) void
releaseBundleLock
(BundleImpl bundle) Releases the bundle's lock.(package private) void
Releases the global lock.(package private) void
releaseInstallLock
(String location) private Bundle
private void
rememberUninstalledBundle
(BundleImpl bundle) (package private) void
removeBundleListener
(BundleImpl bundle, BundleListener l) (package private) void
removeFrameworkListener
(BundleImpl bundle, FrameworkListener l) (package private) void
removeServiceListener
(BundleImpl bundle, ServiceListener l) Implementation for BundleContext.removeServiceListener().private void
resolveBundleRevision
(BundleRevision revision) (package private) boolean
resolveBundles
(Collection<Bundle> targets) (package private) void
setActiveStartLevel
(int requestedLevel, FrameworkListener[] listeners) Implements the functionality of the setStartLevel() method for the StartLevel service, but does not do the security or parameter check.(package private) void
setBundleProtectionDomain
(BundleImpl bundleImpl, BundleRevisionImpl revisionImpl) (package private) void
setBundleStartLevel
(Bundle bundle, int startLevel) Sets the start level of the specified bundle; this method implements functionality for the Start Level service.(package private) void
setBundleStateAndNotify
(BundleImpl bundle, int state) (package private) void
setInitialBundleStartLevel
(int startLevel) Sets the default start level into which newly installed bundles will be placed; this method implements functionality for the Start Level service.(package private) void
setLastModified
(long l) void
void
void
(package private) void
setSecurityProvider
(SecurityProvider securityProvider) (package private) void
setStartLevel
(int level) Overrides standard BundleImpl.setStartLevel() behavior to always throw an exception since the system bundle's start level cannot be changed.(package private) void
setURLHandlersActivator
(URLHandlersActivator urlHandlersActivator) void
start()
This method starts the framework instance, which will transition the framework from start level 0 to its active start level as specified in its configuration properties (1 by default).void
start
(int options) Starts this bundle.(package private) void
startBundle
(BundleImpl bundle, int options) Implementation for Bundle.start().void
stop()
This method asynchronously shuts down the framework, it must be called at the end of a session in order to shutdown all active bundles.void
stop
(int options) Stops this bundle.(package private) void
stopBundle
(BundleImpl bundle, boolean record) toString()
(package private) boolean
ungetService
(Bundle bundle, ServiceReference ref, Object srvObj) void
Uninstalls this bundle.(package private) void
uninstallBundle
(BundleImpl bundle) void
update()
Updates this bundle.void
update
(InputStream is) Updates this bundle from anInputStream
.(package private) void
updateBundle
(BundleImpl bundle, InputStream is) waitForStop
(long timeout) This method will cause the calling thread to block until the framework shuts down.Methods inherited from class org.apache.felix.framework.BundleImpl
__setState, _getBundleContext, addRevision, checkAdapt, closeAndDelete, compareTo, findEntries, getActivator, getArchive, getBundle, getBundleContext, getCurrentLocalizedHeader, getDataFile, getEntry, getEntryPaths, getHeaders, getHeaders, getLocation, getLockingThread, getProtectionDomain, getRegisteredServices, getResource, getResources, getRevisions, getServicesInUse, getSignerCertificates, getState, getSymbolicName, getVersion, hasRevision, isDeclaredActivationPolicyUsed, isExtension, isLockable, isRemovalPending, isStale, loadClass, lock, refresh, revise, rollbackRevise, setActivator, setBundleContext, setDeclaredActivationPolicyUsed, setPersistentStateStarting, unlock
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.osgi.framework.Bundle
getBundleContext, getDataFile, getHeaders, getHeaders, getRegisteredServices, getResource, getResources, getServicesInUse, getSignerCertificates, getState, getVersion, loadClass
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface org.osgi.framework.launch.Framework
findEntries, getEntry, getEntryPaths, getLocation, getSymbolicName
-
Field Details
-
m_secureAction
-
m_extensionManager
-
m_fwkWiring
-
m_fwkStartLevel
-
m_logger
-
m_configMap
-
m_configMutableMap
-
m_resolver
-
m_bundleLock
-
m_globalLockWaitersList
-
m_globalLockThread
-
m_globalLockCount
private int m_globalLockCount -
m_installRequestMap
-
m_installRequestLock_Priority1
-
m_installedBundles
-
LOCATION_MAP_IDX
private static final int LOCATION_MAP_IDX- See Also:
-
IDENTIFIER_MAP_IDX
private static final int IDENTIFIER_MAP_IDX- See Also:
-
m_uninstalledBundles
-
m_dependencies
-
m_activeStartLevel
private volatile int m_activeStartLevel -
m_targetStartLevel
private volatile int m_targetStartLevel -
m_startLevelBundles
-
m_cache
-
m_activatorList
List m_activatorList -
m_nextId
private long m_nextId -
m_nextIdLock
-
m_registry
-
m_dispatcher
-
m_bundleStreamHandler
-
m_bootPkgs
-
m_bootPkgWildcards
private final boolean[] m_bootPkgWildcards -
m_shutdownGate
-
m_securityManager
-
m_securityDefaultPolicy
private volatile boolean m_securityDefaultPolicy -
m_systemBundleClassCache
-
m_securityProvider
-
m_urlHandlersActivator
-
-
Constructor Details
-
Felix
This constructor creates a framework instance with a specified Map of configuration properties. Configuration properties are used internally by the framework to alter its default behavior. The configuration properties should have a String key and an Object value. The passed in Map is copied by the framework and all keys are converted to Strings.
Configuration properties are generally the sole means to configure the framework's default behavior; the framework does not typically refer to any system properties for configuration information. If a Map is supplied to this method for configuration properties, then the framework will consult the Map instance for any and all configuration properties. It is possible to specify a null for the configuration property map, in which case the framework will use its default behavior in all cases.
The following configuration properties can be specified (properties starting with "felix" are specific to Felix, while those starting with "org.osgi" are standard OSGi properties):
- org.osgi.framework.storage - Sets the directory to use as the bundle cache; by default bundle cache directory is felix-cache in the current working directory. The value should be a valid directory name. The directory name can be either absolute or relative. Relative directory names are relative to the current working directory. The specified directory will be created if it does not exist.
- org.osgi.framework.storage.clean - Determines whether the bundle cache is flushed. The value can either be "none" or "onFirstInit", where "none" does not flush the bundle cache and "onFirstInit" flushes the bundle cache when the framework instance is first initialized. The default value is "none".
- felix.cache.rootdir - Sets the root directory to use to calculate the bundle cache directory for relative directory names. If org.osgi.framework.storage is set to a relative name, by default it is relative to the current working directory. If this property is set, then it will be calculated as being relative to the specified root directory.
- felix.cache.filelimit - The integer value of this string sets an upper limit on how many files the cache will open. The default value is zero, which means there is no limit.
- felix.cache.locking - Enables or disables bundle cache locking, which is used to prevent concurrent access to the bundle cache. This is enabled by default, but on older/smaller JVMs file channel locking is not available; set this property to false to disable it.
- felix.cache.bufsize - Sets the buffer size to be used by the cache; the default value is 4096. The integer value of this string provides control over the size of the internal buffer of the disk cache for performance reasons.
- org.osgi.framework.system.packages - Specifies a comma-delimited list of packages that should be exported via the System Bundle from the parent class loader. The framework will set this to a reasonable default. If the value is specified, it replaces any default value.
- org.osgi.framework.system.packages.extra - Specifies a comma-delimited list of packages that should be exported via the System Bundle from the parent class loader in addition to the packages in org.osgi.framework.system.packages. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in org.osgi.framework.system.packages.
- org.osgi.framework.bootdelegation - Specifies a comma-delimited list of packages that should be made implicitly available to all bundles from the parent class loader. It is recommended not to use this property since it breaks modularity. The default value is empty.
- felix.systembundle.activators - A List of BundleActivator instances that are started/stopped when the System Bundle is started/stopped. The specified instances will receive the System Bundle's BundleContext when invoked.
- felix.log.logger - An instance of Logger that the framework uses as its default logger.
- felix.log.level - An integer value indicating the degree of logging reported by the framework; the higher the value the more logging is reported. If zero ('0') is specified, then logging is turned off completely. The log levels match those specified in the OSGi Log Service (i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug). The default value is 1.
- org.osgi.framework.startlevel.beginning - The initial start level of the framework once it starts execution; the default value is 1.
- felix.startlevel.bundle - The default start level for newly installed bundles; the default value is 1.
- felix.service.urlhandlers - Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is "true". Activating the URL Handlers service will result in the URL.setURLStreamHandlerFactory() and URLConnection.setContentHandlerFactory() being called.
- felix.fragment.validation - Determines if installing unsupported fragment bundles throws an exception or logs a warning. Possible values are "exception" or "warning". The default value is "exception".
- felix.security.defaultpolicy - Flag to indicate whether to consult the default java securtiy policy if no security extension is present. The default value is "false".
The Main class implements some functionality for default property file handling, which makes it possible to specify configuration properties and framework properties in files that are automatically loaded when starting the framework. If you plan to create your own framework instance, you may be able to take advantage of the features it provides; refer to its class documentation for more information.
The framework is not actually started until the start() method is called.
- Parameters:
configMap
- A map for obtaining configuration properties, may be null.
-
-
Method Details
-
getLogger
Logger getLogger() -
getConfig
Map getConfig() -
getResolver
StatefulResolver getResolver() -
getDependencies
BundleRevisionDependencies getDependencies() -
getBundleStreamHandler
URLStreamHandler getBundleStreamHandler() -
getBootPackages
String[] getBootPackages() -
getBootPackageWildcards
boolean[] getBootPackageWildcards() -
createUnmodifiableMap
-
close
void close()- Overrides:
close
in classBundleImpl
-
getFramework
Felix getFramework()- Overrides:
getFramework
in classBundleImpl
-
adapt
Description copied from interface:Bundle
Adapt this bundle to the specified type.Adapting this bundle to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this bundle cannot be adapted and
null
is returned.- Specified by:
adapt
in interfaceBundle
- Specified by:
adapt
in interfaceFramework
- Overrides:
adapt
in classBundleImpl
- Type Parameters:
A
- The type to which this bundle is to be adapted.- Parameters:
type
- Class object for the type to which this bundle is to be adapted.- Returns:
- The object, of the specified type, to which this bundle has been
adapted or
null
if this bundle cannot be adapted to the specified type.
-
getBundleId
public long getBundleId()Description copied from interface:Bundle
Returns this bundle's unique identifier. This bundle is assigned a unique identifier by the Framework when it was installed in the OSGi environment.A bundle's unique identifier has the following attributes:
- Is unique and persistent.
- Is a
long
. - Its value is not reused for another bundle, even after a bundle is uninstalled.
- Does not change while a bundle remains installed.
- Does not change when a bundle is updated.
This method must continue to return this bundle's unique identifier while this bundle is in the
UNINSTALLED
state.- Specified by:
getBundleId
in interfaceBundle
- Specified by:
getBundleId
in interfaceFramework
- Overrides:
getBundleId
in classBundleImpl
- Returns:
- The unique identifier of this bundle.
- See Also:
-
getLastModified
public long getLastModified()Description copied from interface:Bundle
Returns the time when this bundle was last modified. A bundle is considered to be modified when it is installed, updated or uninstalled.The time value is the number of milliseconds since January 1, 1970, 00:00:00 UTC.
- Specified by:
getLastModified
in interfaceBundle
- Specified by:
getLastModified
in interfaceFramework
- Overrides:
getLastModified
in classBundleImpl
- Returns:
- The time when this bundle was last modified.
-
setLastModified
void setLastModified(long l) - Overrides:
setLastModified
in classBundleImpl
-
_getLocation
String _getLocation()- Overrides:
_getLocation
in classBundleImpl
-
getPersistentState
public int getPersistentState()- Overrides:
getPersistentState
in classBundleImpl
-
setPersistentStateInactive
public void setPersistentStateInactive()- Overrides:
setPersistentStateInactive
in classBundleImpl
-
setPersistentStateActive
public void setPersistentStateActive()- Overrides:
setPersistentStateActive
in classBundleImpl
-
setPersistentStateUninstalled
public void setPersistentStateUninstalled()- Overrides:
setPersistentStateUninstalled
in classBundleImpl
-
getStartLevel
int getStartLevel(int defaultLevel) Overrides standard BundleImpl.getStartLevel() behavior to always return zero for the system bundle.- Overrides:
getStartLevel
in classBundleImpl
- Parameters:
defaultLevel
- This parameter is ignored by the system bundle.- Returns:
- Always returns zero.
-
setStartLevel
void setStartLevel(int level) Overrides standard BundleImpl.setStartLevel() behavior to always throw an exception since the system bundle's start level cannot be changed.- Overrides:
setStartLevel
in classBundleImpl
- Parameters:
level
- This parameter is ignored by the system bundle.- Throws:
IllegalArgumentException
- Always throws exception since system bundle's start level cannot be changed.
-
hasPermission
Description copied from interface:Bundle
Determines if this bundle has the specified permissions.If the Java Runtime Environment does not support permissions, this method always returns
true
.permission
is of typeObject
to avoid referencing thejava.security.Permission
class directly. This is to allow the Framework to be implemented in Java environments which do not support permissions.If the Java Runtime Environment does support permissions, this bundle and all its resources including embedded JAR files, belong to the same
java.security.ProtectionDomain
; that is, they must share the same set of permissions.- Specified by:
hasPermission
in interfaceBundle
- Overrides:
hasPermission
in classBundleImpl
- Parameters:
obj
- The permission to verify.- Returns:
true
if this bundle has the specified permission or the permissions possessed by this bundle imply the specified permission;false
if this bundle does not have the specified permission orpermission
is not aninstanceof
java.security.Permission
.
-
init
Description copied from interface:Framework
Initialize this Framework.This method performs the same function as calling
Framework.init(FrameworkListener...)
with no framework listeners.- Specified by:
init
in interfaceFramework
- Throws:
BundleException
- If this Framework could not be initialized.- See Also:
-
init
Description copied from interface:Framework
Initialize this Framework. After calling this method, this Framework must:- Have generated a new
framework UUID
. - Be in the
Bundle.STARTING
state. - Have a valid Bundle Context.
- Be at start level 0.
- Have event handling enabled.
- Have reified Bundle objects for all installed bundles.
- Have registered any framework services. For example,
ConditionalPermissionAdmin
. - Be
adaptable
to the OSGi defined types to which a system bundle can be adapted. - Have called the
start
method of the extension bundle activator for all resolved extension bundles.
This Framework will not actually be started until
start
is called.This method does nothing if called when this Framework is in the
Bundle.STARTING
,Bundle.ACTIVE
orBundle.STOPPING
states.All framework events fired by this method method are also delivered to the specified FrameworkListeners in the order they are specified before returning from this method. After returning from this method the specified listeners are no longer notified of framework events.
- Specified by:
init
in interfaceFramework
- Parameters:
listeners
- Zero or more listeners to be notified when framework events occur while initializing the framework. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is registered with the framework, it will be notified twice for each framework event.- Throws:
BundleException
- If this Framework could not be initialized.- See Also:
- Have generated a new
-
setBundleProtectionDomain
void setBundleProtectionDomain(BundleImpl bundleImpl, BundleRevisionImpl revisionImpl) throws Exception - Throws:
Exception
-
start
This method starts the framework instance, which will transition the framework from start level 0 to its active start level as specified in its configuration properties (1 by default). If the init() was not explicitly invoked before calling this method, then it will be implicitly invoked before starting the framework.- Specified by:
start
in interfaceBundle
- Specified by:
start
in interfaceFramework
- Overrides:
start
in classBundleImpl
- Throws:
BundleException
- if any error occurs.- See Also:
-
start
Description copied from interface:Bundle
Starts this bundle.If this bundle's state is
UNINSTALLED
then anIllegalStateException
is thrown.If the current start level is less than this bundle's start level:
- If the
Bundle.START_TRANSIENT
option is set, then aBundleException
is thrown indicating this bundle cannot be started due to the Framework's current start level. - Otherwise, the Framework must set this bundle's persistent autostart
setting to Started with declared activation if the
Bundle.START_ACTIVATION_POLICY
option is set or Started with eager activation if not set.
When the Framework's current start level becomes equal to or more than this bundle's start level, this bundle will be started.
Otherwise, the following steps are required to start this bundle:
- If this bundle is in the process of being activated or deactivated
then this method must wait for activation or deactivation to complete
before continuing. If this does not occur in a reasonable time, a
BundleException
is thrown to indicate this bundle was unable to be started. - If the
Bundle.START_TRANSIENT
option is not set then set this bundle's autostart setting to Started with declared activation if theBundle.START_ACTIVATION_POLICY
option is set or Started with eager activation if not set. When the Framework is restarted and this bundle's autostart setting is not Stopped, this bundle must be automatically started. - If this bundle's state is
ACTIVE
then this method returns immediately. - If this bundle's state is not
RESOLVED
, an attempt is made to resolve this bundle. If the Framework cannot resolve this bundle, aBundleException
is thrown. - If the
Bundle.START_ACTIVATION_POLICY
option is set and this bundle's declared activation policy islazy
then:- If this bundle's state is
STARTING
then this method returns immediately. - This bundle's state is set to
STARTING
. - A bundle event of type
BundleEvent.LAZY_ACTIVATION
is fired. - This method returns immediately and the remaining steps will be followed when this bundle's activation is later triggered.
- If this bundle's state is
- This bundle's state is set to
STARTING
. - A bundle event of type
BundleEvent.STARTING
is fired. - The
BundleActivator.start(BundleContext)
method of this bundle'sBundleActivator
, if one is specified, is called. If theBundleActivator
is invalid or throws an exception then:- This bundle's state is set to
STOPPING
. - A bundle event of type
BundleEvent.STOPPING
is fired. - Any services registered by this bundle must be unregistered.
- Any services used by this bundle must be released.
- Any listeners registered by this bundle must be removed.
- This bundle's state is set to
RESOLVED
. - A bundle event of type
BundleEvent.STOPPED
is fired. - A
BundleException
is then thrown.
- This bundle's state is set to
- This bundle's state is set to
ACTIVE
. - A bundle event of type
BundleEvent.STARTED
is fired.
getState()
in {INSTALLED
,RESOLVED
} or {INSTALLED
,RESOLVED
,STARTING
} if this bundle has a lazy activation policy.
- Bundle autostart setting is modified unless the
Bundle.START_TRANSIENT
option was set. getState()
in {ACTIVE
} unless the lazy activation policy was used.BundleActivator.start()
has been called and did not throw an exception unless the lazy activation policy was used.
- Depending on when the exception occurred, bundle autostart setting is
modified unless the
Bundle.START_TRANSIENT
option was set. getState()
not in {STARTING
,ACTIVE
}.
- Specified by:
start
in interfaceBundle
- Specified by:
start
in interfaceFramework
- Overrides:
start
in classBundleImpl
- Parameters:
options
- The options for starting this bundle. SeeBundle.START_TRANSIENT
andBundle.START_ACTIVATION_POLICY
. The Framework must ignore unrecognized options.- Throws:
BundleException
- If this bundle could not be started. BundleException types thrown by this method include:BundleException.START_TRANSIENT_ERROR
,BundleException.NATIVECODE_ERROR
,BundleException.RESOLVE_ERROR
,BundleException.STATECHANGE_ERROR
, andBundleException.ACTIVATOR_ERROR
.- See Also:
- If the
-
stop
This method asynchronously shuts down the framework, it must be called at the end of a session in order to shutdown all active bundles.- Specified by:
stop
in interfaceBundle
- Specified by:
stop
in interfaceFramework
- Overrides:
stop
in classBundleImpl
- Throws:
BundleException
- BundleException types thrown by this method include:BundleException.STATECHANGE_ERROR
andBundleException.ACTIVATOR_ERROR
.- See Also:
-
stop
Description copied from interface:Bundle
Stops this bundle.The following steps are required to stop a bundle:
- If this bundle's state is
UNINSTALLED
then anIllegalStateException
is thrown. - If this bundle is in the process of being activated or deactivated
then this method must wait for activation or deactivation to complete
before continuing. If this does not occur in a reasonable time, a
BundleException
is thrown to indicate this bundle was unable to be stopped. - If the
Bundle.STOP_TRANSIENT
option is not set then then set this bundle's persistent autostart setting to to Stopped. When the Framework is restarted and this bundle's autostart setting is Stopped, this bundle must not be automatically started. - If this bundle's state is not
STARTING
orACTIVE
then this method returns immediately. - This bundle's state is set to
STOPPING
. - A bundle event of type
BundleEvent.STOPPING
is fired. - If this bundle's state was
ACTIVE
prior to setting the state toSTOPPING
, theBundleActivator.stop(BundleContext)
method of this bundle'sBundleActivator
, if one is specified, is called. If that method throws an exception, this method must continue to stop this bundle and aBundleException
must be thrown after completion of the remaining steps. - Any services registered by this bundle must be unregistered.
- Any services used by this bundle must be released.
- Any listeners registered by this bundle must be removed.
- If this bundle's state is
UNINSTALLED
, because this bundle was uninstalled while theBundleActivator.stop
method was running, aBundleException
must be thrown. - This bundle's state is set to
RESOLVED
. - A bundle event of type
BundleEvent.STOPPED
is fired.
getState()
in {ACTIVE
}.
- Bundle autostart setting is modified unless the
Bundle.STOP_TRANSIENT
option was set. getState()
not in {ACTIVE
,STOPPING
}.BundleActivator.stop
has been called and did not throw an exception.
- Bundle autostart setting is modified unless the
Bundle.STOP_TRANSIENT
option was set.
- Specified by:
stop
in interfaceBundle
- Specified by:
stop
in interfaceFramework
- Overrides:
stop
in classBundleImpl
- Parameters:
options
- The options for stopping this bundle. SeeBundle.STOP_TRANSIENT
. The Framework must ignore unrecognized options.- Throws:
BundleException
- BundleException types thrown by this method include:BundleException.STATECHANGE_ERROR
andBundleException.ACTIVATOR_ERROR
.- See Also:
- If this bundle's state is
-
waitForStop
This method will cause the calling thread to block until the framework shuts down.- Specified by:
waitForStop
in interfaceFramework
- Parameters:
timeout
- A timeout value.- Returns:
- A Framework Event indicating the reason this method returned. The
following
FrameworkEvent
types may be returned by this method.STOPPED
- This Framework has been stopped.STOPPED_UPDATE
- This Framework has been updated which has shutdown and will now restart.-
STOPPED_BOOTCLASSPATH_MODIFIED
- This Framework has been stopped and a bootclasspath extension bundle has been installed or updated. The VM must be restarted in order for the changed boot class path to take effect. ERROR
- The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.-
WAIT_TIMEDOUT
- This method has timed out and returned before this Framework has stopped.
- Throws:
InterruptedException
- If the thread was interrupted.
-
uninstall
Description copied from interface:Bundle
Uninstalls this bundle.This method causes the Framework to notify other bundles that this bundle is being uninstalled, and then puts this bundle into the
UNINSTALLED
state. The Framework must remove any resources related to this bundle that it is able to remove.If this bundle has exported any packages, the Framework must continue to make these packages available to their importing bundles until the
FrameworkWiring.refreshBundles
method has been called or the Framework is relaunched.The following steps are required to uninstall a bundle:
- If this bundle's state is
UNINSTALLED
then anIllegalStateException
is thrown. - If this bundle's state is
ACTIVE
,STARTING
orSTOPPING
, this bundle is stopped as described in theBundle.stop
method. IfBundle.stop
throws an exception, a Framework event of typeFrameworkEvent.ERROR
is fired containing the exception. - This bundle's state is set to
UNINSTALLED
. - A bundle event of type
BundleEvent.UNINSTALLED
is fired. - This bundle and any persistent storage area provided for this bundle by the Framework are removed.
getState()
not in {UNINSTALLED
}.
getState()
in {UNINSTALLED
}.- This bundle has been uninstalled.
getState()
not in {UNINSTALLED
}.- This Bundle has not been uninstalled.
- Specified by:
uninstall
in interfaceBundle
- Specified by:
uninstall
in interfaceFramework
- Overrides:
uninstall
in classBundleImpl
- Throws:
BundleException
- If the uninstall failed. This can occur if another thread is attempting to change this bundle's state and does not complete in a timely manner. BundleException types thrown by this method include:BundleException.STATECHANGE_ERROR
- See Also:
- If this bundle's state is
-
update
Description copied from interface:Bundle
Updates this bundle.This method performs the same function as calling
Bundle.update(InputStream)
with anull
InputStream.- Specified by:
update
in interfaceBundle
- Specified by:
update
in interfaceFramework
- Overrides:
update
in classBundleImpl
- Throws:
BundleException
- If this bundle could not be updated. BundleException types thrown by this method include:BundleException.READ_ERROR
,BundleException.DUPLICATE_BUNDLE_ERROR
,BundleException.MANIFEST_ERROR
,BundleException.NATIVECODE_ERROR
,BundleException.RESOLVE_ERROR
,BundleException.STATECHANGE_ERROR
, andBundleException.ACTIVATOR_ERROR
.- See Also:
-
update
Description copied from interface:Bundle
Updates this bundle from anInputStream
.If the specified
InputStream
isnull
, the Framework must create theInputStream
from which to read the updated bundle by interpreting, in an implementation dependent manner, this bundle'sBundle-UpdateLocation
Manifest header, if present, or this bundle's original location.If this bundle's state is
ACTIVE
, it must be stopped before the update and started after the update successfully completes.If this bundle has exported any packages that are imported by another bundle, these packages must remain exported until the
FrameworkWiring.refreshBundles
method has been has been called or the Framework is relaunched.The following steps are required to update a bundle:
- If this bundle's state is
UNINSTALLED
then anIllegalStateException
is thrown. - If this bundle's state is
ACTIVE
,STARTING
orSTOPPING
, this bundle is stopped as described in theBundle.stop
method. IfBundle.stop
throws an exception, the exception is rethrown terminating the update. - The updated version of this bundle is read from the input stream and
installed. If the Framework is unable to install the updated version of
this bundle, the original version of this bundle must be restored and a
BundleException
must be thrown after completion of the remaining steps. - This bundle's state is set to
INSTALLED
. - If the updated version of this bundle was successfully installed, a
bundle event of type
BundleEvent.UPDATED
is fired. - If this bundle's state was originally
ACTIVE
, the updated bundle is started as described in theBundle.start
method. IfBundle.start
throws an exception, a Framework event of typeFrameworkEvent.ERROR
is fired containing the exception.
getState()
not in {UNINSTALLED
}.
getState()
in {INSTALLED
,RESOLVED
,ACTIVE
}.- This bundle has been updated.
getState()
in {INSTALLED
,RESOLVED
,ACTIVE
}.- Original bundle is still used; no update occurred.
- Specified by:
update
in interfaceBundle
- Specified by:
update
in interfaceFramework
- Overrides:
update
in classBundleImpl
- Parameters:
is
- TheInputStream
from which to read the new bundle ornull
to indicate the Framework must create the input stream from this bundle'sBundle-UpdateLocation
Manifest header, if present, or this bundle's original location. The input stream must always be closed when this method completes, even if an exception is thrown.- Throws:
BundleException
- If this bundle could not be updated. BundleException types thrown by this method include:BundleException.READ_ERROR
,BundleException.DUPLICATE_BUNDLE_ERROR
,BundleException.MANIFEST_ERROR
,BundleException.NATIVECODE_ERROR
,BundleException.RESOLVE_ERROR
,BundleException.STATECHANGE_ERROR
, andBundleException.ACTIVATOR_ERROR
.- See Also:
- If this bundle's state is
-
toString
- Overrides:
toString
in classBundleImpl
-
getActiveStartLevel
int getActiveStartLevel()Returns the active start level of the framework; this method implements functionality for the Start Level service.- Returns:
- The active start level of the framework.
-
setActiveStartLevel
Implements the functionality of the setStartLevel() method for the StartLevel service, but does not do the security or parameter check. The security and parameter check are done in the StartLevel service implementation because this method is called on a separate thread and the caller's thread would already be gone if we did the checks in this method. This method should not be called directly.- Parameters:
requestedLevel
- The new start level of the framework.
-
getInitialBundleStartLevel
int getInitialBundleStartLevel()Returns the start level into which newly installed bundles will be placed by default; this method implements functionality for the Start Level service.- Returns:
- The default start level for newly installed bundles.
-
setInitialBundleStartLevel
void setInitialBundleStartLevel(int startLevel) Sets the default start level into which newly installed bundles will be placed; this method implements functionality for the Start Level service.- Parameters:
startLevel
- The new default start level for newly installed bundles.
-
getBundleStartLevel
Returns the start level for the specified bundle; this method implements functionality for the Start Level service.- Parameters:
bundle
- The bundle to examine.- Returns:
- The start level of the specified bundle.
- Throws:
IllegalArgumentException
- If the specified bundle has been uninstalled.
-
setBundleStartLevel
Sets the start level of the specified bundle; this method implements functionality for the Start Level service.- Parameters:
bundle
- The bundle whose start level is to be modified.startLevel
- The new start level of the specified bundle.
-
isBundlePersistentlyStarted
Returns whether a bundle is persistently started; this is an method implementation for the Start Level service.- Parameters:
bundle
- The bundle to examine.- Returns:
- true if the bundle is marked as persistently started, false otherwise.
- Throws:
IllegalArgumentException
- If the specified bundle has been uninstalled.
-
isBundleActivationPolicyUsed
Returns whether the bundle is using its declared activation policy; this is an method implementation for the Start Level service.- Parameters:
bundle
- The bundle to examine.- Returns:
- true if the bundle is using its declared activation policy, false otherwise.
- Throws:
IllegalArgumentException
- If the specified bundle has been uninstalled.
-
getBundleHeaders
Get bundle headers and resolve any localized strings from resource bundles.- Parameters:
bundle
-locale
-- Returns:
- localized bundle headers dictionary.
-
getBundleResource
Implementation for Bundle.getResource(). -
getBundleResources
Implementation for Bundle.getResources(). -
getBundleEntry
Implementation for Bundle.getEntry(). -
getBundleEntryPaths
Implementation for Bundle.getEntryPaths(). -
findBundleEntries
Implementation for Bundle.findEntries(). -
findBundleEntries
Enumeration findBundleEntries(BundleRevision revision, String path, String filePattern, boolean recurse) Implementation for BundleWiring.findEntries(). -
getBundleRegisteredServices
-
getBundleServicesInUse
-
bundleHasPermission
-
loadBundleClass
Implementation for Bundle.loadClass().- Throws:
ClassNotFoundException
-
startBundle
Implementation for Bundle.start().- Throws:
BundleException
-
activateBundle
- Throws:
BundleException
-
updateBundle
- Throws:
BundleException
-
stopBundle
- Throws:
BundleException
-
uninstallBundle
- Throws:
BundleException
-
getProperty
Implementation for BundleContext.getProperty(). Returns environment property associated with the framework.- Parameters:
key
- The name of the property to retrieve.- Returns:
- The value of the specified property or null.
-
reloadBundle
- Throws:
BundleException
-
installBundle
- Throws:
BundleException
-
getBundle
Retrieves a bundle from its location.- Parameters:
location
- The location of the bundle to retrieve.- Returns:
- The bundle associated with the location or null if there is no bundle associated with the location.
-
getBundle
Implementation for BundleContext.getBundle(). Retrieves a bundle from its identifier.- Parameters:
id
- The identifier of the bundle to retrieve.- Returns:
- The bundle associated with the identifier or null if there is no bundle associated with the identifier.
-
getBundle
Retrieves a bundle by its identifier and avoids bundles hooks.- Returns:
- The bundle associated with the identifier or null.
-
getBundles
Implementation for BundleContext.getBundles(). Retrieves all installed bundles.- Returns:
- An array containing all installed bundles or null if there are no installed bundles.
-
getBundles
Bundle[] getBundles()Retrieves all installed bundles and avoids bundles hooks.- Returns:
- An array containing all installed bundles or null if there are no installed bundles.
-
addBundleListener
-
removeBundleListener
-
addServiceListener
void addServiceListener(BundleImpl bundle, ServiceListener l, String f) throws InvalidSyntaxException Implementation for BundleContext.addServiceListener(). Adds service listener to the listener list so that is can listen forServiceEvent
s.- Parameters:
bundle
- The bundle that registered the listener.l
- The service listener to add to the listener list.f
- The filter for the listener; may be null.- Throws:
InvalidSyntaxException
-
removeServiceListener
Implementation for BundleContext.removeServiceListener(). Removes service listeners from the listener list.- Parameters:
bundle
- The context bundle of the listenerl
- The service listener to remove from the listener list.
-
addFrameworkListener
-
removeFrameworkListener
-
registerService
ServiceRegistration registerService(BundleContextImpl context, String[] classNames, Object svcObj, Dictionary dict) Implementation for BundleContext.registerService(). Registers a service for the specified bundle bundle.- Parameters:
classNames
- A string array containing the names of the classes under which the new service is available.svcObj
- The service object orServiceFactory
.dict
- A dictionary of properties that further describe the service or null.- Returns:
- A
ServiceRegistration
object or null.
-
getServiceReferences
ServiceReference[] getServiceReferences(BundleImpl bundle, String className, String expr, boolean checkAssignable) throws InvalidSyntaxException Retrieves an array ofServiceReference
objects based on calling bundle, service class name, and filter expression. Optionally checks for isAssignable to make sure that the service can be cast to the- Parameters:
bundle
- Calling BundleclassName
- Service Classname ornull
for allexpr
- Filter Criteria ornull
- Returns:
- Array of ServiceReference objects that meet the criteria
- Throws:
InvalidSyntaxException
-
getAllowedServiceReferences
ServiceReference[] getAllowedServiceReferences(BundleImpl bundle, String className, String expr, boolean checkAssignable) throws InvalidSyntaxException Retrieves Array ofServiceReference
objects based on calling bundle, service class name, optional filter expression, and optionally filters further on the version. If running under aSecurityManager
, checks that the calling bundle has permissions to see the service references and removes references that aren't.- Parameters:
bundle
- Calling BundleclassName
- Service Classname ornull
for allexpr
- Filter Criteria ornull
checkAssignable
-true
to check for isAssignable,false
to return all versions- Returns:
- Array of ServiceReference objects that meet the criteria
- Throws:
InvalidSyntaxException
-
getService
-
ungetService
-
getDataFile
-
isHookBlackListed
-
blackListHook
-
getHooks
-
getBundle
This method returns the bundle associated with the specified class if the class was loaded from a bundle from this framework instance. If the class was not loaded from a bundle or was loaded by a bundle in another framework instance, then null is returned.- Parameters:
clazz
- the class for which to find its associated bundle.- Returns:
- the bundle associated with the specified class or null if the class was not loaded by a bundle or its associated bundle belongs to a different framework instance.
-
getExportedPackages
Returns the exported packages associated with the specified package name. This is used by the PackageAdmin service implementation.- Parameters:
pkgName
- The name of the exported package to find.- Returns:
- The exported package or null if no matching package was found.
-
getExportedPackages
Returns an array of all actively exported packages from the specified bundle or if the specified bundle is null an array containing all actively exported packages by all bundles.- Parameters:
b
- The bundle whose exported packages are to be retrieved or null if the exported packages of all bundles are to be retrieved.- Returns:
- An array of exported packages.
-
getExportedPackages
Adds any current active exported packages from the specified bundle to the passed in list.- Parameters:
bundle
- The bundle from which to retrieve exported packages.list
- The list to which the exported packages are added
-
getImportingBundles
-
getRequiringBundles
-
resolveBundles
-
resolveBundleRevision
- Throws:
BundleException
-
refreshPackages
-
getDependencyClosure
-
populateDependentGraph
-
getRemovalPendingBundles
Collection<Bundle> getRemovalPendingBundles() -
getSecurityProvider
SecurityProvider getSecurityProvider() -
setSecurityProvider
-
getSignerMatcher
-
impliesBundlePermission
boolean impliesBundlePermission(BundleProtectionDomain bundleProtectionDomain, Permission permission, boolean direct) -
createBundleActivator
- Throws:
Exception
-
refreshBundle
- Throws:
Exception
-
fireFrameworkEvent
Fires bundle events. -
fireBundleEvent
Fires bundle events.- Parameters:
type
- The type of bundle event to fire.bundle
- The bundle associated with the event.
-
fireBundleEvent
-
fireServiceEvent
Fires service events.- Parameters:
event
- The service event to fire.reg
- The service registration associated with the service object.
-
initializeFrameworkProperties
private void initializeFrameworkProperties() -
loadFromDefaultIfNotDefined
-
loadPrefixFromDefaultIfNotDefined
private void loadPrefixFromDefaultIfNotDefined(Map configMap, Properties defaultProperties, String prefix) -
getFrameworkVersion
Read the framework version from the property file.- Returns:
- the framework version as a string.
-
cleanMavenVersion
The main purpose of this method is to turn a.b.c-SNAPSHOT into a.b.c.SNAPSHOT it can also deal with a.b-SNAPSHOT and turns it into a.b.0.SNAPSHOT and will leave the dash in a.b.c.something-else, as it's valid in that last example. In short this method attempts to map a Maven version to an OSGi version as well as possible.- Parameters:
sb
- The version to be cleaned- Returns:
- The cleaned version
-
loadNextId
private long loadNextId()Generated the next valid bundle identifier. -
getNextId
private long getNextId() -
rememberUninstalledBundle
-
forgetUninstalledBundle
-
acquireInstallLock
- Throws:
BundleException
-
releaseInstallLock
-
setBundleStateAndNotify
-
acquireBundleLock
This method acquires the lock for the specified bundle as long as the bundle is in one of the specified states. If it is not, an exception is thrown. Bundle state changes will be monitored to avoid deadlocks.- Parameters:
bundle
- The bundle to lock.desiredStates
- Logically OR'ed desired bundle states.- Throws:
IllegalStateException
- If the bundle is not in one of the specified desired states.
-
releaseBundleLock
Releases the bundle's lock.- Parameters:
bundle
- The bundle whose lock is to be released.- Throws:
IllegalStateException
- If the calling thread does not own the bundle lock.
-
acquireGlobalLock
boolean acquireGlobalLock()Attempts to acquire the global lock. Will also promote a bundle lock to the global lock, if the calling thread already holds a bundle lock. Since it is possible to deadlock when trying to acquire the global lock while holding a bundle lock, this method may fail if a potential deadlock is detected. If the calling thread does not hold a bundle lock, then it will wait indefinitely to acquire the global.- Returns:
- true if the global lock was successfully acquired, false otherwise.
-
releaseGlobalLock
void releaseGlobalLock()Releases the global lock.- Throws:
IllegalStateException
- If the calling thread does not own the global lock.
-
setURLHandlersActivator
-
getStreamHandlerService
-
getContentHandlerService
-
findProviders
-