Interface ApplicationContext
ApplicationContext
is the access point for an OSGi-aware application
to the features of the OSGi Service Platform. Each application instance will
have its own ApplicationContext
instance, which will not be reused
after destroying the corresponding application instance.
Application instances can obtain their ApplicationContext
using the
Framework.getApplicationContext(Object)
method.
The lifecycle of an ApplicationContext
instance is bound to the
lifecycle of the corresponding application instance. The
ApplicationContext
becomes available when the application is started
and it is invalidated when the application instance is stopped (i.e. the
"stop" method of the application activator object returned). All method calls
(except getApplicationId()
and getInstanceId()
) to an
invalidated context object result an IllegalStateException
.
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addServiceListener
(ApplicationServiceListener listener, String referenceName) Adds the specifiedApplicationServiceListener
object to this context application instance's list of listeners.void
addServiceListener
(ApplicationServiceListener listener, String[] referenceNames) Adds the specifiedApplicationServiceListener
object to this context application instance's list of listeners.This method return the identifier of the corresponding application type.This method returns the identifier of the corresponding application instance.getServiceProperties
(Object serviceObject) Application can query the service properties of a service object it is bound to.Returns the startup parameters specified when calling theorg.osgi.service.application.ApplicationDescriptor#launch(Map)
method.locateService
(String referenceName) This method returns the service object for the specifiedreferenceName
.Object[]
locateServices
(String referenceName) This method returns the service objects for the specifiedreferenceName
.org.osgi.framework.ServiceRegistration
registerService
(String[] clazzes, Object service, Dictionary properties) Registers the specified service object with the specified properties under the specified class names into the Framework.org.osgi.framework.ServiceRegistration
registerService
(String clazz, Object service, Dictionary properties) Registers the specified service object with the specified properties under the specified class name with the Framework.void
Removes the specifiedApplicationServiceListener
object from this context application instance's list of listeners.
-
Method Details
-
addServiceListener
void addServiceListener(ApplicationServiceListener listener, String referenceName) throws IllegalArgumentException Adds the specifiedApplicationServiceListener
object to this context application instance's list of listeners. The specifiedreferenceName
is a reference name specified in the descriptor of the corresponding application. The registeredlistener
will only receive theApplicationServiceEvent
s related to the referred service.If the
listener
was already added, calling this method will overwrite the previous registration.- Parameters:
listener
- TheApplicationServiceListener
to be added. It must not benull
referenceName
- the reference name of a service from the descriptor of the corresponding application. It must not benull
.- Throws:
IllegalStateException
- If this context application instance has stopped.NullPointerException
- Iflistener
orreferenceName
isnull
IllegalArgumentException
- If there is no service in the application descriptor with the specifiedreferenceName
.
-
addServiceListener
void addServiceListener(ApplicationServiceListener listener, String[] referenceNames) throws IllegalArgumentException Adds the specifiedApplicationServiceListener
object to this context application instance's list of listeners. ThereferenceNames
parameter is an array of reference name specified in the descriptor of the corresponding application. The registeredlistener
will only receive theApplicationServiceEvent
s related to the referred services.If the
listener
was already added, calling this method will overwrite the previous registration.- Parameters:
listener
- TheApplicationServiceListener
to be added. It must not benull
referenceNames
- and array of service reference names from the descriptor of the corresponding application. It must not benull
and it must not be empty.- Throws:
IllegalStateException
- If this context application instance has stopped.NullPointerException
- Iflistener
orreferenceNames
isnull
IllegalArgumentException
- IfreferenceNames
array is empty or it contains unknown references
-
removeServiceListener
Removes the specifiedApplicationServiceListener
object from this context application instance's list of listeners.If
listener
is not contained in this context application instance's list of listeners, this method does nothing.- Parameters:
listener
- TheApplicationServiceListener
object to be removed.- Throws:
IllegalStateException
- If this context application instance has stopped.
-
getInstanceId
String getInstanceId()This method returns the identifier of the corresponding application instance. This identifier is guaranteed to be unique within the scope of the device. Note: this method can safely be called on an invalidApplicationContext
as well.- Returns:
- the unique identifier of the corresponding application instance
- See Also:
-
getApplicationId
String getApplicationId()This method return the identifier of the corresponding application type. This identifier is the same for the different instances of the same application but it is different for different application type.Note: this method can safely be called on an invalid
ApplicationContext
as well.- Returns:
- the identifier of the application type.
- See Also:
-
locateService
This method returns the service object for the specifiedreferenceName
. If the cardinality of the reference is 0..n or 1..n and multiple services are bound to the reference, the service with the highest ranking (as specified in itsConstants.SERVICE_RANKING
property) is returned. If there is a tie in ranking, the service with the lowest service ID (as specified in itsConstants.SERVICE_ID
property); that is, the service that was registered first is returned.- Parameters:
referenceName
- The name of a reference as specified in a reference element in this context application's description. It must not benull
- Returns:
- A service object for the referenced service or
null
if the reference cardinality is 0..1 or 0..n and no bound service is available. - Throws:
NullPointerException
- IfreferenceName
isnull
.IllegalArgumentException
- If there is no service in the application descriptor with the specifiedreferenceName
.IllegalStateException
- If this context application instance has stopped.
-
locateServices
This method returns the service objects for the specifiedreferenceName
.- Parameters:
referenceName
- The name of a reference as specified in a reference element in this context application's description. It must not benull
.- Returns:
- An array of service object for the referenced service or
null
if the reference cardinality is 0..1 or 0..n and no bound service is available. - Throws:
NullPointerException
- IfreferenceName
isnull
.IllegalArgumentException
- If there is no service in the application descriptor with the specifiedreferenceName
.IllegalStateException
- If this context application instance has stopped.
-
getStartupParameters
Map getStartupParameters()Returns the startup parameters specified when calling theorg.osgi.service.application.ApplicationDescriptor#launch(Map)
method.Startup arguments can be specified as name, value pairs. The name must be of type
String
, which must not benull
or emptyString
(""
), the value can be any object includingnull
.- Returns:
- a
Map
containing the startup arguments. It can benull
. - Throws:
IllegalStateException
- If this context application instance has stopped.
-
getServiceProperties
Application can query the service properties of a service object it is bound to. Application gets bound to a service object when it first obtains a reference to the service by callinglocateService
orlocateServices
methods.- Parameters:
serviceObject
- A service object the application is bound to. It must not be null.- Returns:
- The service properties associated with the specified service object.
- Throws:
NullPointerException
- if the specifiedserviceObject
isnull
IllegalArgumentException
- if the application is not bound to the specified service object or it is not a service object at all.IllegalStateException
- If this context application instance has stopped.
-
registerService
org.osgi.framework.ServiceRegistration registerService(String[] clazzes, Object service, Dictionary properties) Registers the specified service object with the specified properties under the specified class names into the Framework. AServiceRegistration
object is returned. TheServiceRegistration
object is for the private use of the application registering the service and should not be shared with other applications. The registering application is defined to be the context application. Bundles can locate the service by using either theBundleContext.getServiceReferences(String, String)
orBundleContext.getServiceReference(String)
method. Other applications can locate this service by usinglocateService(String)
orlocateServices(String)
method, if they declared their dependence on the registered service.An application can register a service object that implements the
ServiceFactory
interface to have more flexibility in providing service objects to other applications or bundles.The following steps are required to register a service:
- If
service
is not aServiceFactory
, anIllegalArgumentException
is thrown ifservice
is not aninstanceof
all the classes named. - The Framework adds these service properties to the specified
Dictionary
(which may benull
): a property namedConstants.SERVICE_ID
identifying the registration number of the service and a property namedConstants.OBJECTCLASS
containing all the specified classes. If any of these properties have already been specified by the registering bundle, their values will be overwritten by the Framework. - The service is added to the Framework service registry and may now be used by others.
- A service event of type
ServiceEvent.REGISTERED
is fired. This event triggers the correspondingApplicationServiceEvent
to be delivered to the applications that registered the appropriate listener. - A
ServiceRegistration
object for this registration is returned.
- Parameters:
clazzes
- The class names under which the service can be located. The class names in this array will be stored in the service's properties under the keyConstants.OBJECTCLASS
. This parameter must not benull
.service
- The service object or aServiceFactory
object.properties
- The properties for this service. The keys in the properties object must all beString
objects. SeeConstants
for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties theServiceRegistration.setProperties(Dictionary)
method must be called. The set of properties may benull
if the service has no properties.- Returns:
- A
ServiceRegistration
object for use by the application registering the service to update the service's properties or to unregister the service. - Throws:
IllegalArgumentException
- If one of the following is true:service
isnull
.service
is not aServiceFactory
object and is not an instance of all the named classes inclazzes
.properties
contains case variants of the same key name.
NullPointerException
- ifclazzes
isnull
SecurityException
- If the caller does not have theServicePermission
to register the service for all the named classes and the Java Runtime Environment supports permissions.IllegalStateException
- If this ApplicationContext is no longer valid.- See Also:
- If
-
registerService
org.osgi.framework.ServiceRegistration registerService(String clazz, Object service, Dictionary properties) Registers the specified service object with the specified properties under the specified class name with the Framework.This method is otherwise identical to
registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
and is provided as a convenience whenservice
will only be registered under a single class name. Note that even in this case the value of the service'sConstants.OBJECTCLASS
property will be an array of strings, rather than just a single string.- Parameters:
clazz
- The class name under which the service can be located. It must not benull
service
- The service object or aServiceFactory
object.properties
- The properties for this service.- Returns:
- A
ServiceRegistration
object for use by the application registering the service to update the service's properties or to unregister the service. - Throws:
IllegalArgumentException
- If one of the following is true:service
isnull
.service
is not aServiceFactory
object and is not an instance of the named class inclazz
.properties
contains case variants of the same key name.
NullPointerException
- ifclazz
isnull
SecurityException
- If the caller does not have theServicePermission
to register the service the named class and the Java Runtime Environment supports permissions.IllegalStateException
- If this ApplicationContext is no longer valid.- See Also:
-