Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (c) OSGi Alliance (2005, 2013). All Rights Reserved.
   * 
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.osgi.application;
 
 import java.util.Map;
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(java.lang.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(s):
$Id: 51dddaaacd80155f9c1b38fefd6211a466447d4a $
See also:
Framework
 
 public interface ApplicationContext {

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.
 
 	public void addServiceListener(ApplicationServiceListener listenerString referenceNamethrows 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
 
 	public void addServiceListener(ApplicationServiceListener listenerString[] referenceNamesthrows java.lang.IllegalArgumentException;

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.
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:
org.osgi.service.application.ApplicationHandle.getInstanceId()
	public String getInstanceId();

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:
org.osgi.service.application.ApplicationDescriptor.getApplicationId()
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 org.osgi.framework.Constants.SERVICE_RANKING property) is returned. If there is a tie in ranking, the service with the lowest service ID (as specified in its org.osgi.framework.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.
	public Object locateService(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.
	public Object[] locateServices(String referenceName);

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 java.lang.String, which must not be null or empty java.lang.String (""), the value can be any object including null.

Returns:
a java.util.Map containing the startup arguments. It can be null.
Throws:
java.lang.IllegalStateException If this context application instance has stopped.
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.
	public Map getServiceProperties(Object serviceObject);

Registers the specified service object with the specified properties under the specified class names into the Framework. A org.osgi.framework.ServiceRegistration object is returned. The org.osgi.framework.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 org.osgi.framework.BundleContext.getServiceReferences(java.lang.String,java.lang.String) or org.osgi.framework.BundleContext.getServiceReference(java.lang.String) method. Other applications can locate this service by using locateService(java.lang.String) or locateServices(java.lang.String) method, if they declared their dependence on the registered service.

An application can register a service object that implements the org.osgi.framework.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 org.osgi.framework.Constants.SERVICE_ID identifying the registration number of the service and a property named org.osgi.framework.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 org.osgi.framework.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 org.osgi.framework.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 org.osgi.framework.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 org.osgi.framework.ServiceRegistration.setProperties(java.util.Dictionary) method must be called. The set of properties may be null if the service has no properties.
Returns:
A org.osgi.framework.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:
org.osgi.framework.BundleContext.registerService(java.lang.String[],java.lang.Object,java.util.Dictionary)
org.osgi.framework.ServiceRegistration
org.osgi.framework.ServiceFactory
	public ServiceRegistration registerService(String[] clazzesObject serviceDictionary 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 org.osgi.framework.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)
	public ServiceRegistration registerService(String clazzObject serviceDictionary properties);
New to GrepCode? Check out our FAQ X