ApplicationContext
Date: 2016-06-25

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

  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`.
    `org.osgi.framework.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.
    `org.osgi.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 instance'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 `ApplicationServiceEvent`s 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 `ApplicationServiceEvent`s 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 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` - 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 application'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 application'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

          org.osgi.framework.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

          org.osgi.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.

      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)`