org.osgi.application

Interface ApplicationContext

public 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.

Author:

$Id: 51dddaaacd80155f9c1b38fefd6211a466447d4a $

See Also:

Framework

Method Summary

Methods

Modifier and Type	Method and Description
void	addServiceListener(ApplicationServiceListener listener, java.lang.String referenceName) Adds the specified ApplicationServiceListener object to this context application instance's list of listeners.
void	addServiceListener(ApplicationServiceListener listener, java.lang.String[] referenceNames) Adds the specified ApplicationServiceListener object to this context application instance's list of listeners.
java.lang.String	getApplicationId() This method return the identifier of the corresponding application type.
java.lang.String	getInstanceId() This method returns the identifier of the corresponding application instance.
java.util.Map	getServiceProperties(java.lang.Object serviceObject) Application can query the service properties of a service object it is bound to.
java.util.Map	getStartupParameters() Returns the startup parameters specified when calling the org.osgi.service.application.ApplicationDescriptor#launch(Map) method.
java.lang.Object	locateService(java.lang.String referenceName) This method returns the service object for the specified referenceName.
java.lang.Object[]	locateServices(java.lang.String referenceName) This method returns the service objects for the specified referenceName.
ServiceRegistration	registerService(java.lang.String[] clazzes, java.lang.Object service, java.util.Dictionary properties) Registers the specified service object with the specified properties under the specified class names into the Framework.
ServiceRegistration	registerService(java.lang.String clazz, java.lang.Object service, java.util.Dictionary properties) Registers the specified service object with the specified properties under the specified class name with the Framework.
void	removeServiceListener(ApplicationServiceListener listener) Removes the specified ApplicationServiceListener object from this context application instances's list of listeners.

Method Detail

addServiceListener

void addServiceListener(ApplicationServiceListener listener,
                      java.lang.String referenceName)
                        throws java.lang.IllegalArgumentException

Adds the specified ApplicationServiceListener object to this context application instance's list of listeners. The specified referenceName is a reference name specified in the descriptor of the corresponding application. The registered listener will only receive the ApplicationServiceEvents related to the referred service.

If the listener was already added, calling this method will overwrite the previous registration.

Parameters:

listener - The ApplicationServiceListener to be added. It must not be null

referenceName - the reference name of a service from the descriptor of the corresponding application. It must not be null.

Throws:

java.lang.IllegalStateException - If this context application instance has stopped.

java.lang.NullPointerException - If listener or referenceName is null

java.lang.IllegalArgumentException - If there is no service in the application descriptor with the specified referenceName.

addServiceListener

void addServiceListener(ApplicationServiceListener listener,
                      java.lang.String[] referenceNames)
                        throws java.lang.IllegalArgumentException

Adds the specified ApplicationServiceListener object to this context application instance's list of listeners. The referenceNames parameter is an array of reference name specified in the descriptor of the corresponding application. The registered listener will only receive the ApplicationServiceEvents related to the referred services.

If the listener was already added, calling this method will overwrite the previous registration.

Parameters:

listener - The ApplicationServiceListener to be added. It must not be null

referenceNames - and array of service reference names from the descriptor of the corresponding application. It must not be null and it must not be empty.

Throws:

java.lang.IllegalStateException - If this context application instance has stopped.

java.lang.NullPointerException - If listener or referenceNames is null

java.lang.IllegalArgumentException - If referenceNames array is empty or it contains unknown references

removeServiceListener

void removeServiceListener(ApplicationServiceListener listener)

Removes the specified ApplicationServiceListener object from this context application instances's list of listeners.

If listener is not contained in this context application instance's list of listeners, this method does nothing.

Parameters:

listener - The ApplicationServiceListener object to be removed.

Throws:

java.lang.IllegalStateException - If this context application instance has stopped.

getInstanceId

java.lang.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 invalid ApplicationContext as well.

Returns:

the unique identifier of the corresponding application instance

See Also:

ApplicationHandle.getInstanceId()

getApplicationId

java.lang.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:

ApplicationDescriptor.getApplicationId()

locateService

java.lang.Object locateService(java.lang.String referenceName)

This method returns the service object for the specified referenceName. 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 its Constants.SERVICE_RANKING property) is returned. If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants.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 applications's description. It must not be null

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:

java.lang.NullPointerException - If referenceName is null.

java.lang.IllegalArgumentException - If there is no service in the application descriptor with the specified referenceName.

java.lang.IllegalStateException - If this context application instance has stopped.

locateServices

java.lang.Object[] locateServices(java.lang.String referenceName)

This method returns the service objects for the specified referenceName.

Parameters:

referenceName - The name of a reference as specified in a reference element in this context applications's description. It must not be null.

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:

java.lang.NullPointerException - If referenceName is null.

java.lang.IllegalArgumentException - If there is no service in the application descriptor with the specified referenceName.

java.lang.IllegalStateException - If this context application instance has stopped.

getStartupParameters

java.util.Map getStartupParameters()

Returns the startup parameters specified when calling the org.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 be null or empty String (""), the value can be any object including null.

Returns:

a Map containing the startup arguments. It can be null.

Throws:

java.lang.IllegalStateException - If this context application instance has stopped.

getServiceProperties

java.util.Map getServiceProperties(java.lang.Object serviceObject)

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 calling locateService or locateServices 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:

java.lang.NullPointerException - if the specified serviceObject is null

java.lang.IllegalArgumentException - if the application is not bound to the specified service object or it is not a service object at all.

java.lang.IllegalStateException - If this context application instance has stopped.

registerService

ServiceRegistration registerService(java.lang.String[] clazzes,
                                  java.lang.Object service,
                                  java.util.Dictionary properties)

Registers the specified service object with the specified properties under the specified class names into the Framework. A ServiceRegistration object is returned. The ServiceRegistration 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 the BundleContext.getServiceReferences(String, String) or BundleContext.getServiceReference(String) method. Other applications can locate this service by using locateService(String) or locateServices(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:

1. If service is not a ServiceFactory, an IllegalArgumentException is thrown if service is not an instanceof all the classes named.
2. The Framework adds these service properties to the specified Dictionary (which may be null): a property named Constants.SERVICE_ID identifying the registration number of the service and a property named Constants.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.
3. The service is added to the Framework service registry and may now be used by others.
4. A service event of type ServiceEvent.REGISTERED is fired. This event triggers the corresponding ApplicationServiceEvent to be delivered to the applications that registered the appropriate listener.
5. 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 key Constants.OBJECTCLASS. This parameter must not be null.

service - The service object or a ServiceFactory object.

properties - The properties for this service. The keys in the properties object must all be String objects. See Constants 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 the ServiceRegistration.setProperties(Dictionary) method must be called. The set of properties may be null 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:

java.lang.IllegalArgumentException - If one of the following is true:

• service is null.
• service is not a ServiceFactory object and is not an instance of all the named classes in clazzes.
• properties contains case variants of the same key name.

java.lang.NullPointerException - if clazzes is null

java.lang.SecurityException - If the caller does not have the ServicePermission to register the service for all the named classes and the Java Runtime Environment supports permissions.

java.lang.IllegalStateException - If this ApplicationContext is no longer valid.

See Also:

BundleContext.registerService(java.lang.String[], java.lang.Object, java.util.Dictionary), ServiceRegistration, ServiceFactory

registerService

ServiceRegistration registerService(java.lang.String clazz,
                                  java.lang.Object service,
                                  java.util.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 when service will only be registered under a single class name. Note that even in this case the value of the service's Constants.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 be null

service - The service object or a ServiceFactory 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:

java.lang.IllegalArgumentException - If one of the following is true:

• service is null.
• service is not a ServiceFactory object and is not an instance of the named class in clazz.
• properties contains case variants of the same key name.

java.lang.NullPointerException - if clazz is null

java.lang.SecurityException - If the caller does not have the ServicePermission to register the service the named class and the Java Runtime Environment supports permissions.

java.lang.IllegalStateException - If this ApplicationContext is no longer valid.

See Also:

registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)