The Service Layer provides a dynamic, concise and consistent programming model for Java developers, simplifying the development and deployment of services by de-coupling the service's specification (Java interface) from its implementations. This model allows developers to bind to services only using their interface specifications. The selection of a specific implementation, optimized for a specific need or from a specific vendor, can thus be deferred to runtime.
In order to use this powerful tool, developers are required to build on top of the Life Cycle and Module Layer of the OSGi Framework. Anything built on top of the Service Layer must follow the rules of the Life Cycle and Module Layers as well as the Service Layer. The Module Layer has rules for sharing Java packages between bundles or hiding packages from other bundles. The Life Cycle Layer provides an API to manage bundles in the Module Layer.
The Module and Life Cycle Layers assume the Framework is in control of the actual deployment unit (bundle) which is deployed as a Java archive (JAR) file. The Module Layer then provides the access for reading content and meta-data from the bundle and loading classes from the bundle. This can make it difficult to use classes or services that are already present in the running environment, for example, from the class path or anything else whose class space is managed outside of the framework. Without the Connect specification, content that lives outside the control of the Framework cannot easily benefit from the rich Service Layer because there is no way to represent the outside content as bundles inside the Framework.
This specification defines a Connect Framework Factory to create and launch an OSGi Framework instance that can connect bundles in the Framework with content managed outside of the Framework itself. For example, to provide things like resource loading, class loading, bundle entry content and bundle manifest headers. Among other things, this allows for bundles to exist and be installed into the Framework from the flat class path, the module path (Java Platform Module System), a jlink image, or a native image. Such bundles may have some limitations with respect to class loading and isolation because they may not follow the rules of the OSGi Module Layer.
-
OSGi Service Registry - It must be possible to use the OSGi Service Registry in environments that do not have the full OSGi Module Layer.
-
OSGi Dependency Model - It must be possible to use the requirements and capabilities model OSGi provides in environments that do not have the full OSGi Module Layer.
-
OSGi Extender Pattern - It must be possible to support the OSGi Extender Pattern in environments that do not have the full OSGi Module Layer. For example, Declarative Services.
-
OSGi Technologies - It must be possible to support other OSGi technologies and specifications such as Configuration Admin, Metatype Service, Log Service etc. in environments that do not have the full OSGi Module Layer.
-
Connect Content - Provides a Framework access to content from outside the Framework that can be used to represent an installed bundle in the Framework. A connect content provides things like a class loader for the bundle, access to entries in a bundle, and the bundle manifest headers.
-
Connect Module - Provides the current connect content available for a bundle installed in the Framework. If the connect content for a bundle is constant then the connect module may return the same connect content for the lifetime of the Framework.
-
Module Connector - Hooks into the initialization of the Framework and connects bundles installed in the Framework with connect module instances.
-
Connect Framework Factory - A factory, similar to the FrameworkFactory, that is used to create Framework instances that use a module connector.
-
Connect Bundle - A bundle installed in the Framework that is connected to a connect module and has its content provided by a connect content.
A launcher is in control of discovering and loading the connect framework factory implementation and the module connector implementation. The launcher is then able to use the connect framework factory to create a Framework instance that uses the module connector instance. When a connect bundle is installed it will be connected to a single connect module. Each bundle revision for the connect bundle is furthermore connected with a single connect content.
This section outlines how a launcher can launch a Framework implementation with an implementation of a ModuleConnector, regardless of the implementation type of the framework. This allows a launcher to embed an OSGi framework without having to provide code that differs between different implementations.
A Framework implementation that supports the Connect specification must provide a factory class. A factory class is an indirection to create a framework implementation object. The implementation factory class must implement the ConnectFrameworkFactory interface. The launcher can use the following ways to get this class name:
-
Service Provider Configuration model, see Java Service Provider Configuration Support for Connect,
-
Get it from some configuration and use
Class.forName, or -
Hardcode the name.
The ConnectFrameworkFactory interface has a single method: newFramework(Map,ModuleConnector). The map provides the sole configuration properties for the framework object. The ModuleConnector implementation provides the OSGi Framework with the support to connect bundles with ConnectModule instances. The result of this method is a framework object, this object implements the Framework interface. See Frameworks for details on the Framework interface.
The following code shows how a Framework can be launched with a module connector.
Framework launch(ModuleConnector moduleConnector)
throws Exception {
Map<String, String> p = new HashMap();
p.put( "org.osgi.framework.storage",
System.getProperty("user.home")
+ File.separator+"osgi");
ServiceLoader<ConnectFrameworkFactory> sl =
ServiceLoader.load(ConnectFrameworkFactory.class);
ConnectFrameworkFactory factory = sl.iterator().next();
Framework osgiFramework = factory.newFramework(p, moduleConnector);
osgiFramework.init();
osgiFramework.start();
return osgiFramework;
}Before a module connector can be used by a Framework instance, the
ModuleConnector must
be initialized.
Initialization is caused by the Framework calling the
initialize(File,Map)
method on the module connector. The module connector initialize method must only be called
once for the lifetime of the Framework instance. If the Framework is stopped
as defined by Stopping a Framework and initialized again as defined by
Initializing the Framework the module connector initialize method must
not be called again.
If the framework supports persistence then the framework determines the path used for the storage
area according to the launch property FRAMEWORK_STORAGE.
Once the framework instance has determined the storage area the ModuleConnector method
initialize(File,Map) must be called.
The file is the storage area used by the Framework and may be null
if persistence is not supported. This file may be used by the module connector for persistent storage.
The map is the unmodifiable map of the Framework configuration properties
that were used to create the new Framework instance with the method newFramework(Map,ModuleConnector)
A module connector may hook into the Framework life cycle by providing
a BundleActivator
instance. The BundleActivator interface defines methods that the
Framework invokes when the Framework is initialized and shutdown.
When the Framework is initialized the system bundle enters the STARTING state.
At this point a valid BundleContext
exists for the Framework. Before invoking extension bundle activators as defined by
Start Extension Activators the Framework must call
the ModuleConnector method newBundleActivator().
If the module connector provides a bundle activator then the start(BundleContext) method must be
called before returning from the Framework init() method and before
any extension bundle activator start methods are called. Any exception thrown by a
module connector activator start method must be wrapped in a BundleException
and broadcast as an ERROR.
The bundle activator allows for the module connector to hook into the life cycle of the Framework itself. For example, this allows the module connector to register services, add listeners and install other bundles before anything else installed in the Framework can, including extension bundles. With the supplied system bundle context a module connector is able to influence the behavior of the Framework by registering various Framework hooks like the ResolverHook. A resolver hook is useful for cases where the wiring of a connect bundle must not be allowed to wire to capabilities provided by other bundles installed in the Framework.
When the Framework is stopped it will reach start level zero and the Framework checks if there are any
framework extensions activators to call the stop method on as defined by
Stop Extension Activators. After calling the stop method
on the framework extension activators, the framework must call stop(BundleContext)
on the bundle activator provided by the module connector. Any exception thrown by a
module connector activator stop method must be wrapped in a BundleException and broadcast as an
ERROR.
The Framework must guarantee that if the start method has executed successfully for
module connector activator, that same BundleActivator object must be called on its
stop method when the Framework is shutdown. After calling the stop method, that
particular BundleActivator object must never be used again. A module connector activator that
threw an exception during start must not be called on shutdown.
Similar to how a framework factory is obtained in Java Service Provider Configuration Support the connect framework factory implementation name is
obtained by reading the content of the configuration resource with the path
META-INF/services/org.osgi.framework.connect.ConnectFrameworkFactory
For example, if the com.acme.osgi framework has a
connect factory class com.acme.osgi.connect.Factory, then it should have
the following resource:
META-INF/services/org.osgi.framework.connect.ConnectFrameworkFactoryAnd the contents should be:
# ACME Impl. for OSGi connect framework factory
com.acme.osgi.connect.FactoryA connect bundle is a Bundle installed in the framework that is connected to a ConnectModule by a ModuleConnector.
When a bundle is installed, as defined by Installing Bundles, a bundle location and an optional input stream
to the content is provided with the BundleContext method installBundle(String,InputStream).
If a content input stream is provided to the call to installBundle then the Framework
must use that input stream to read the content of the bundle being installed.
In this case the Framework assumes that the management agent is not installing a
connect bundle and wants the content from the provided input stream to be
installed into the Framework.
When no input stream is provided to the installBundle method the Framework
must call the ModuleConnector method connect(String). The connect method is given the bundle location
specified in the call to installBundle(String,InputStream). The connect method must do one of the following:
-
Throw a
BundleExceptionif the installation of the bundle is to be prevented. In this case theBundleExceptionmust be thrown from theinstallBundlemethod. Any other exception thrown by theconnectmethod must propagate to the caller of theinstallBundlemethod. -
Return an empty
Optionalindicating that the Framework must create the input stream from which to read the bundle by interpreting, in an implementation dependent manner, the specified location. -
Return a present
Optionalindicating that the ConnectModule present must be connected to the bundle and used to access content of the bundle.
If a ConnectModule is found for the specified
bundle location, then the Framework must call the ConnectModule method
getContent() to access the
current ConnectContent
for the bundle. The ConnectContent must be used by the Framework to access content for the bundle's current
BundleRevision. Any exception thrown by the
getContent method must be wrapped in a BundleException and result in the
BundleException being thrown by the installBundle method.
When a bundle is updated, as defined by Updating Bundles, an optional input
stream to the content is provided with the Bundle method
update(InputStream).
If the content input stream is provided to the call to update then the Framework
must use that input stream to read the content of the bundle being updated. In this case
the Framework assumes the management agent is not updating the bundle to a connect bundle and wants the
content from the provided input stream to be used to update the bundle. This allows a
management agent to update a connect bundle to a non-connect bundle.
When no input stream is provided to the update method the Framework must call
the ModuleConnector method connect(String). The connect method is given the location of the
bundle being updated. The connect method must do one of the following:
-
Throw a
BundleExceptionif the update of the bundle is to be prevented. In this case theBundleExceptionmust be thrown from theupdatemethod. Any other exception thrown by theconnectmethod must propagate to the caller of theupdatemethod. -
Return an empty
Optionalindicating that the Framework must create the input stream from which to read the updated bundle by interpreting, in an implementation dependent manner, this bundle'sBundle-UpdateLocationManifest header, if present, or this bundle's original location. -
Return a present
Optionalindicating that the ConnectModule present must be connected to the bundle and used to access content of the updated bundle.
If a ConnectModule is found for the specified
bundle location, then the Framework must call the ConnectModule method
getContent() to access the
current ConnectContent
for the updated bundle. The ConnectContent must be used by the Framework to access content for the bundle's current
BundleRevision. Any exception thrown by the
getContent method must be wrapped in a BundleException and result in the
BundleException being thrown by the update method.
When no input stream is provided to the call to update it is possible to update
a non-connect bundle to a connect bundle. Depending on the dynamic nature of the module
connector, updating a connect bundle may result in the exact same
ConnectContent being used for
each updated revision for the bundle. This implies that the same class loader and content entries
could be used for each updated revision.
The ConnectContent provides the Framework with all the information and resources necessary to represent a BundleRevision for the connect bundle installed the Framework.
Before accessing the ConnectContent
a Framework must first open the ConnectContent with the method
open().
A Framework may open and close the content many times while the content is being used by the Framework.
For example, to limit the number of resources kept open concurrently by the Framework. The Framework
must always ensure that the content is open before calling other methods on the
ConnectContent. If any exception is thrown by the open
method as a result of installing or updating a connect bundle then the exception
must be wrapped in a BundleException and result in the BundleException
being thrown by the bundle install or update method.
As defined by Bundle Manifest Headers the bundle manifest headers can carry descriptive
information about the bundle. A connect content may provide the bundle manifest headers
to be used by the current revision of a bundle. When the framework needs to access a
connect bundle's headers it must call the ConnectContent method
getHeaders().
If an empty Optional is returned then the Framework must lookup the content entry
named META-INF/MANIFEST.MF and parse the bundle manifest itself as defined by
Bundle Manifest Headers.
If the Optional returned has a map present then the map must be used to provide
the raw, unlocalized, headers for the bundle. The headers must be used the same way the raw header
values would have been used from a parsed META-INF/MANIFEST.MF entry. That is the header
keys and values that have semantic meaning must be used by the framework for the bundle and the
key/value pairs must be used for the Dictionary returned by the bundle
getHeaders() methods.
The BundleRevision associated with the
connect content must also have its capabilities and requirements defined by the contents of the Map.
Connect content is typically managed and loaded by an entity outside of the Framework itself. This may also influence the way classes are defined and loaded for content outside of the Framework's control. For bundle revisions that are connected to a ConnectContent the framework must call the connect content method getClassLoader() before creating a Framework managed class loader for the connected bundle.
If an empty Optional is returned by the connect content getClassLoader method then the
Framework must create a class loader for the current bundle revision. The class loader created
by the Framework must follow all the delegation rules defined by Class Loading Architecture for a bundle
class loader and it must implement the BundleReference
interface. All resources found and classes defined by this class loader must have their content read using the
connect content entries. This is similar to how a bundle class loader works when the Framework is responsible
for accessing and reading the bundle content JAR files directly. This framework implementation class loader
must be returned by the the BundleWiring method getClassLoader().
If the Optional returned by the connect content getClassLoader method has a
class loader present then that ClassLoader must be used for the class loader of the
BundleWiring
that is connected to the connect content. The ClassLoader provided is not required to implement
the BundleReference interface and is not required
to follow the delegation rules defined by Class Loading Architecture. If the ClassLoader does
not implement BundleReference then the Framework must wrap the ClassLoader with
another ClassLoader that does implement BundleReference. The
getBundle() must return the bundle
associated with the BundleWiring. This wrapper loader simply delegates all loading to the
ClassLoader provided connect content. A Framework is free to always return a wrapper loader
for the BundleWiring method getClassLoader() even when the connect content loader does implement the BundleReference interface.
A module connector is not required to provide a unique class loader for each ConnectContent instance.
That is the same class loader can be used as the class loader for multiple ConnectContent instances and therefore
get used by multiple bundles installed in the framework. If the connect bundle exports packages then the
ConnectContent class loader will be delegated to by other class loaders managed by the framework.
In other words, a bundle installed that is not connected with a
ConnectModule may import packages exported by
connect bundles and the OSGi Module Layer will do the correct delegation of class loads to the connect class loader
as defined
Class Loading Architecture for exported packages.
When a module connector implementation provides class loader implementations that are not the framework managed class loader there are limitations with respect to the behavior defined by the sections Weaving Hook Service Specification and Lazy Activation Policy. Weaving hooks as defined by Weaving Hook Service Specification will not be notified of the classes defined by the module connect class loaders. This implies that the WeavingHook and WovenClassListener implementations will not be called for and will not be able to weave these classes. The activation policy as defined by Lazy Activation Policy also cannot be supported because The Framework will not have the necessary hooks into the module connector class loader implementation to cause bundle activation on class load.
A ConnectContent instance provides access to content entries for a revision of a connect bundle. The connect content entries are used by the Framework for the following:
-
To provide content for the introspective methods on Bundle and BundleWiring. For example, the getEntry(String), getEntryPaths(String) and findEntries(String,String,int) method.
-
To provide content for loading classes and resources from the framework managed class loader. This is used when the
ConnectContentmethod getClassLoader() returns an emptyOptional.
To introspect all entry path names provided by a ConnectContent instance the method
getEntries()
is used by the Framework. The result of the getEntries method is used by the Framework
to provide results from the Bundle
getEntryPaths(String)
method and the BundleWiring
findEntries(String,String,int)
method.
To introspect a connect content entry the interface
ConnectContent.ConnectEntry
is used. A ConnectEntry can be looked up by its path name using the
ConnectContent method
getEntry(String).
If the entry does not exist then an empty Optional is returned. A present
ConnectContent.ConnectEntry
can be used by the Framework to provide URL objects that use a Framework specific
protocol for bundle entries. For example, for the URL instances returned by
Bundle method
getEntry(String)
and the BundleWiring method
findEntries(String,String,int).
The Framework must ensure that the path value used for calls to ConnectContent
method getEntry(String)
do not start with slash ('/'). That is any paths used for calls to Bundle method
getEntry(String)
or BundleWiring method
findEntries(String,String,int)
must have the beginning slash ('/') removed before calling the ConnectContent method
getEntry(String).
When a BundleRevision
connected to a ConnectContent
no longer isInUse()
then the Framework must call the ConnectContent method
close() in order
to close the connect content. The Framework is free to close the ConnectContent
at any other time during the life time of the Framework, but the Framework must always ensure
ConnectContent is opened before calling other methods on the ConnectContent.
A bundle installed in the framework can be identified as a connect bundle by introspection of
the tags attribute on
the osgi.identity
capability for the current bundle revision. All connect bundle revisions must have a tags
attribute value that contains the string value osgi.connect.
For example, the following method determines if a BundleRevision is for a connect bundle:
boolean isConnect(BundleRevision revision) {
return revision.getCapabilities("osgi.identity").stream().findFirst().map(c->{
List<String> tags = (List<String>) c.getAttributes().get("tags");
if (tags == null) {
return false;
}
return tags.contains("osgi.connect");
}).orElse(false);
}For resources with the osgi.identity
capability and the attribute type value
of osgi.bundle, the tags attribute must
be the same for the osgi.wiring.bundle
and the osgi.wiring.host
capabilities. The Framework must include the osgi.connect value in the tags attribute for all three capabilities.
The Framework must make a record of which bundles are connected to a
ConnectModule.
When the Framework is stopped it must persist the state of all the installed bundles,
including the ones connected to a ConnectModule. When a new Framework instance
is created using the persistent storage which recorded the connection to a
ConnectModule, the Framework must verify that a
ModuleConnector is
available that can connect the bundle location.
If there is no ConnectModule present then the bundle installed must
be discarded by the Framework as if it is not installed and a warning FrameworkEvent
should be published or a warning should be logged.
Extension bundles as defined by the section Extension Bundles can
deliver parts, or fragments, of the Framework implementation. A Framework that supports
extension bundles will modify its own class loader to append the content of the framework
extension as defined by Class Path Treatment.
If an extension bundle is also a connect bundle then the framework must not attempt to
perform the class path modifications of the Framework itself with the extension bundle.
It is assumed that the ModuleConnector is managing that outside of the Framework.
The FrameworkUtil class
contains utility methods which may be useful to bundles. For module connector implementations
the FrameworkUtil method getBundle(Class)
needs additional help from the module connector to figure out the Bundle for a
specified Class.
A module connector implementation can hook into the FrameworkUtil class
by providing an implementation of the FrameworkUtilHelper interface.
Implementations of the FrameworkUtilHelper interface provide alternative
implementations of the methods contained in the FrameworkUtil class.
The FrameworkUtil method getBundle(Class)
method will fall back to calling the available FrameworkUtilHelper
getBundle(Class) methods
if the default implementation of the FrameworkUtil
getBundle(Class) method
cannot figure out the Bundle for the specified Class. This allows a module
connector implementation to return the Bundle object for classes that a module connector
class loader defines.
Similar to how a connect framework factory is obtained in Java Service Provider Configuration Support for Connect the FrameworkUtil class discovers helper names
by reading the content of the configuration resources with the path
META-INF/services/org.osgi.framework.connect.FrameworkUtilHelper
For example, if the module connector implementation com.acme.osgi.connect.classpath has a
helper class com.acme.osgi.connect.classpath.AcmeFrameworkUtilHelpler, then it should have
the following resource:
META-INF/services/org.osgi.framework.connect.FrameworkUtilHelperAnd the contents should be:
# ACME Impl. for FrameworkUtilHelper
com.acme.osgi.connect.classpath.AcmeFrameworkUtilHelplerWhen the FrameworkUtil class
is initialized it will discover the available FrameworkUtilHelper
implementations as described in [13] Java Service Provider Configuration to obtain
an immutable list of
FrameworkUtilHelper
implementations. The list of helpers cannot change during the lifetime of the
FrameworkUtil class.
To illustrate how the Connect specification can be used the following is an example connector that discovers the JAR files contained on the Java class path and represents them as connect content. This example assumes the module connector implementation exists on the class path along with other bundle JARs that it can discover. This example does not show how the JAR files are discovered on the running Java class path.
public class ClassPathConnector implements ModuleConnector {
@Override
public Optional<ConnectModule> connect(String location)
throws BundleException {
return getJarFile(location).map((j) -> () -> new ClassPathContent(j));
}
private Optional<JarFile> getJarFile(String location) {
// find a jar file for the specified location from the running class path
return ...
}
static class ClassPathContent implements ConnectContent {
private final JarFile jar;
public ClassPathContent(JarFile jar) {
this.jar = jar;
}
@Override
public Optional<ClassLoader> getClassLoader() {
// assume this classes class loader can be used by all JARs found
// on the class path
return Optional.of(getClass().getClassLoader());
}
@Override
public Iterable<String> getEntries() throws IOException {
return jar.stream().map((e) -> e.getName()).
collect(Collectors.toList());
}
@Override
public Optional<ConnectEntry> getEntry(String path) {
return Optional.ofNullable(getConnectEntry(path));
}
ConnectEntry getConnectEntry(final String path) {
final ZipEntry entry = jar.getEntry(path);
return entry == null ? null : new ConnectEntry() {
@Override
public String getName() {
return path;
}
@Override
public long getContentLength() {
return entry.getSize();
}
@Override
public long getLastModified() {
return entry.getTime();
}
@Override
public InputStream getInputStream() throws IOException {
return jar.getInputStream(entry);
}
};
}
@Override
public Optional<Map<String, String>> getHeaders() {
return Optional.empty();
}
@Override
public void open() throws IOException {}
@Override
public void close() throws IOException {}
}
@Override
public void initialize(File storage, Map<String, String> configuration) {}
@Override
public Optional<BundleActivator> newBundleActivator() {
return Optional.empty();
}
}
A ModuleConnector implementation
should be considered part of the Framework implementation when it is used to launch a new Framework. Just
like Framework implementations can assume to have AllPermission granted, a module
connector should have AllPermission granted. A module connector will have
access to the bundle locations. A bundle location can be considered sensitive data that should
be protected. Module connector implementations should not expose the bundle location strings they obtain
without a necessary permission check, see
getLocation().
Framework Connect Package Version 1.0.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest.
Example import for consumers using the API in this package:
Import-Package: org.osgi.framework.connect; version="[1.0,2.0)"
-
ConnectContent- AConnectContentprovides a Framework instance access to the content of a ConnectModule. -
ConnectContent.ConnectEntry- Represents the entry of aConnectContent. -
ConnectFrameworkFactory- A factory for creating Framework instances. -
ConnectModule- AConnectModuleis used by a Framework instance to access the content of the connected bundle. -
FrameworkUtilHelper- A helper for the FrameworkUtil class. -
ModuleConnector- AModuleConnectorprovides connections to instances of ConnectModule that are used by a Framework instance to connect installed bundles locations with content provided by theModuleConnector.
A ConnectContent provides a Framework instance access to the
content of a ConnectModule.
A framework may open and close the content
for a ConnectModule multiple times while the ConnectContent
is in use by the framework. The framework must close the
ConnectContent once the ConnectContent is no longer used as
the content of a current bundle revision or an in use bundle revision.
An entry in a ConnectContent is identified by a path name that is a
solidus ('/' /) separated path. A ConnectContent
may treat directories as entries. A directory entry path name will end with a
solidus. A directory entry may be located using a path name that omits the
trailing solidus.
Thread-safe
The osgi.identity
tags attribute value
used by the framework to tag connect bundle revisions.
Closes this ConnectContent.
IOException– If an error occurred closing this
ConnectContent.
Returns a class loader for this ConnectContent.
This method is called by the framework for resolved bundles only and will be called at most once while a bundle is
resolved. If a bundle associated with a ConnectModule is
refreshed and resolved again, the framework will ask the
ConnectContent for the class loader again. This allows for a
ConnectContent to reuse or create a new class loader each time
the bundle revision is resolved.
An Optional containing the class loader for this
ConnectContent, or an empty Optional if framework
should handle creating a class loader for the bundle revision
associated with this ConnectContent.
IllegalStateException– If this ConnectContent has been
closed.
Returns the entry names available in this ConnectContent.
An Iterable which can supply the available entry names.
IOException– If an error occurs reading this
ConnectContent.
IllegalStateException– If this ConnectContent has been
closed.
The path name of the entry.
Returns the ConnectEntry for the specified path name in this content.
The empty value is returned if an entry with the specified path name does not exist. The path must not start with a "/" and is relative to the root of this content. A connect entry for a directory will have a path name that ends with a slash ('/').
An Optional containing the ConnectEntry for the
specified path, or an empty Optional if no entry for
specified path can be found.
IllegalStateException– If this ConnectContent has been
closed.
Returns the Manifest headers and values of this ConnectContent.
An Optional containing the Manifest headers and values
for this ConnectContent, or an empty Optional if
the framework should handle parsing the Manifest of the content
itself.
IllegalStateException– If this ConnectContent has been
closed.
Opens this ConnectContent.
The framework will open the content when it needs to access the content
for a bundle revision associated with this ConnectContent. The
framework may defer calling this method until requests to access the
bundle revision content are made.
IOException– If an error occurred opening this
ConnectContent.
Represents the entry of a ConnectContent.
Returns the content of this entry.
The content of this entry.
IOException– If an error occurs reading the content.
Returns the content length of this entry.
The content length of the entry, or -1 if the content
length is not known.
Returns an input stream for the content of this entry.
An input stream for the content of this entry.
IOException– If an error occurs reading the content.
Returns the last modification time of this entry.
The last modification time of this entry measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
A factory for creating Framework instances.
If a framework supports ModuleConnector, then the implementation jar must contain the following resource:
/META-INF/services/org.osgi.framework.connect.ConnectFrameworkFactory
This UTF-8 encoded resource must contain the name of the framework
implementation's ConnectFrameworkFactory implementation class. Space and tab
characters, including blank lines, in the resource must be ignored. The
number sign ('#' \u0023) and all characters following it on each
line are a comment and must be ignored.
Launchers can find the name of the ConnectFrameworkFactory implementation
class in the resource and then load and construct a ConnectFrameworkFactory
object for the framework implementation. The ConnectFrameworkFactory
implementation class must have a public, no-argument constructor. Java™
SE 6 introduced the ServiceLoader class which can create a
ConnectFrameworkFactory instance from the resource.
Thread-safe
Consumers of this API must not implement this type
The framework properties to configure the new
framework instance. If framework properties are not provided
by the configuration argument, the created framework instance
must use some reasonable default configuration appropriate for
the current VM. For example, the system packages for the
current execution environment should be properly exported. The
specified configuration argument may be null. The
created framework instance must copy any information needed
from the specified configuration argument since the
configuration argument can be changed after the framework
instance has been created.
The module connector that the new framework
instance will use. The specified module connector argument may
be null.
Create a new Framework instance using the specified module connector.
A new, configured Framework instance. The framework instance must be in the Bundle.INSTALLED state.
SecurityException– If the caller does not have
AllPermission, and the Java Runtime Environment
supports permissions.
A ConnectModule is used by a Framework instance to access the
content of the connected bundle.
Thread-safe
Returns the current content of this connect module.
The framework must call this method when it needs to access the content
for the current bundle revision of this
ConnectModule. The framework may defer opening the returned
ConnectContent until requests to access the bundle revision
content are made.
The current ConnectContent of this ConnectModule.
IOException– If an error occurred getting the content.
A helper for the FrameworkUtil class.
This helper provides alternative implementations for methods on FrameworkUtil.
A class associated with a bundle.
Returns the Bundle associated with the specified class.
This helper method is called by FrameworkUtil.getBundle(Class) if the standard implementation of FrameworkUtil is unable to find the bundle.
An Optional containing the Bundle for the
specified class, or an empty Optional if the specified
class is not from a bundle.
A ModuleConnector provides connections to instances of
ConnectModule that are used by a Framework instance to
connect installed bundles locations with content provided by the
ModuleConnector.
This allows a ModuleConnector to provide content and classes for a
connected bundle installed in the Framework. A
ModuleConnector is provided when
creating a
framework instance. Because a ModuleConnector instance can
participate in the initialization of the Framework and the life cycle
of a Framework instance the ModuleConnector instance should
only be used with a single Framework instance at a time.
Thread-safe
The bundle location used to install a bundle.
Connects a bundle location with a ConnectModule.
When the result is empty, then the framework must handle reading the content of the bundle itself. Otherwise, the returned ConnectModule must be used by the framework to access the content of the bundle.
An Optional containing the ConnectModule for the
specified bundle location, or an empty Optional if the
framework must handle reading the content of the bundle itself.
BundleException– If the location cannot be handled.
The persistent storage area used by the Framework
or null if the platform does not have file system
support.
An unmodifiable map of framework configuration properties that were used to configure the new framework instance.
Initializes this ModuleConnector with the
framework persistent storage file and
framework properties configured for a Framework instance.
This method is called once by a Framework instance and is called before any other methods on this module connector are called.
Creates a new activator for this ModuleConnector.
This method is called by the framework during framework
initialization. Returning an
activator allows this ModuleConnector to participate in the
framework life cycle. If an activator is returned:
An Optional containing a new BundleActivator for
this ModuleConnector, or an empty Optional if no
BundleActivator is necessary.