ApplicationHandle
Date: 2016-06-25

org.osgi.service.application

## Class ApplicationHandle

- java.lang.Object
- - org.osgi.service.application.ApplicationHandle

-     public abstract class ApplicationHandle
      extends java.lang.Object

  ApplicationHandle is an OSGi service interface which represents an instance of an application. It provides the functionality to query and manipulate the lifecycle state of the represented application instance. It defines constants for the lifecycle states.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `APPLICATION_DESCRIPTOR` The property key for the pid of the corresponding application descriptor.
    `static java.lang.String` | `APPLICATION_PID` The property key for the unique identifier (PID) of the application instance.
    `static java.lang.String` | `APPLICATION_STATE` The property key for the state of this application instance.
    `static java.lang.String` | `APPLICATION_SUPPORTS_EXITVALUE` The property key for the supports exit value property of this application instance.
    `static java.lang.String` | `RUNNING` The application instance is running.
    `static java.lang.String` | `STOPPING` The application instance is being stopped.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ApplicationHandle(java.lang.String instanceId, ApplicationDescriptor descriptor)` Application instance identifier is specified by the container when the instance is created.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` The application instance's lifecycle state can be influenced by this method.
    `protected abstract void` | `destroySpecific()` Called by the destroy() method to perform application model specific steps to stop and destroy an application instance safely.
    `ApplicationDescriptor` | `getApplicationDescriptor()` Retrieves the `ApplicationDescriptor` to which this `ApplicationHandle` belongs.
    `java.lang.Object` | `getExitValue(long timeout)` Returns the exit value for the application instance.
    `java.lang.String` | `getInstanceId()` Returns the unique identifier of this instance.
    `abstract java.lang.String` | `getState()` Get the state of the application instance.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### APPLICATION_PID

          public static final java.lang.String APPLICATION_PID

      The property key for the unique identifier (PID) of the application instance.
      See Also:
        Constant Field Values

    - #### APPLICATION_DESCRIPTOR

          public static final java.lang.String APPLICATION_DESCRIPTOR

      The property key for the pid of the corresponding application descriptor.
      See Also:
        Constant Field Values

    - #### APPLICATION_STATE

          public static final java.lang.String APPLICATION_STATE

      The property key for the state of this application instance.
      See Also:
        Constant Field Values

    - #### APPLICATION_SUPPORTS_EXITVALUE

          public static final java.lang.String APPLICATION_SUPPORTS_EXITVALUE

      The property key for the supports exit value property of this application instance.
      Since:
        1.1
      See Also:
        Constant Field Values

    - #### RUNNING

          public static final java.lang.String RUNNING

      The application instance is running. This is the initial state of a newly created application instance.
      See Also:
        Constant Field Values

    - #### STOPPING

          public static final java.lang.String STOPPING

      The application instance is being stopped. This is the state of the application instance during the execution of the `destroy()` method.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ApplicationHandle

          protected ApplicationHandle(java.lang.String instanceId,
                           ApplicationDescriptor descriptor)

      Application instance identifier is specified by the container when the instance is created. The instance identifier must remain static for the lifetime of the instance, it must remain the same even across framework restarts for the same application instance. This value must be the same as the `service.pid` service property of this application handle.

      The instance identifier should follow the following scheme: <application descriptor PID>.<index> where <application descriptor PID> is the PID of the corresponding `ApplicationDescriptor` and <index> is a unique integer index assigned by the application container. Even after destroying the application index the same index value should not be reused in a reasonably long timeframe.

      Parameters:
        `instanceId` - the instance identifier of the represented application instance. It must not be null.
        `descriptor` - the `ApplicationDescriptor` of the represented application instance. It must not be null.
      Throws:
        `java.lang.NullPointerException` - if any of the arguments is null.

  - ### Method Detail

    - #### getApplicationDescriptor

          public final ApplicationDescriptor getApplicationDescriptor()

      Retrieves the `ApplicationDescriptor` to which this `ApplicationHandle` belongs.
      Returns:
        The corresponding `ApplicationDescriptor`

    - #### getState

          public abstract java.lang.String getState()

      Get the state of the application instance.
      Returns:
        the state of the application.
      Throws:
        `java.lang.IllegalStateException` - if the application handle is unregistered

    - #### getExitValue

          public java.lang.Object getExitValue(long timeout)
                                        throws ApplicationException,
                                               java.lang.InterruptedException

      Returns the exit value for the application instance. The timeout specifies how the method behaves when the application has not yet terminated. A negative, zero or positive value may be used.
      - negative - The method does not wait for termination. If the application has not terminated then an `ApplicationException` is thrown.
      - zero - The method waits until the application terminates.
      - positive - The method waits until the application terminates or the timeout expires. If the timeout expires and the application has not terminated then an `ApplicationException` is thrown.

      The default implementation throws an `UnsupportedOperationException`. The application model should override this method if exit values are supported.

      Parameters:
        `timeout` - The maximum time in milliseconds to wait for the application to timeout.
      Returns:
        The exit value for the application instance. The value is application specific.
      Throws:
        `java.lang.UnsupportedOperationException` - If the application model does not support exit values.
        `java.lang.InterruptedException` - If the thread is interrupted while waiting for the timeout.
        `ApplicationException` - If the application has not terminated. The error code will be `ApplicationException.APPLICATION_EXITVALUE_NOT_AVAILABLE`.
      Since:
        1.1

    - #### getInstanceId

          public final java.lang.String getInstanceId()

      Returns the unique identifier of this instance. This value is also available as a service property of this application handle's service.pid.
      Returns:
        the unique identifier of the instance

    - #### destroy

          public final void destroy()

      The application instance's lifecycle state can be influenced by this method. It lets the application instance perform operations to stop the application safely, e.g. saving its state to a permanent storage.

      The method must check if the lifecycle transition is valid; a STOPPING application cannot be stopped. If it is invalid then the method must exit. Otherwise the lifecycle state of the application instance must be set to STOPPING. Then the destroySpecific() method must be called to perform any application model specific steps for safe stopping of the represented application instance.

      At the end the `ApplicationHandle` must be unregistered. This method should free all the resources related to this `ApplicationHandle`.

      When this method is completed the application instance has already made its operations for safe stopping, the ApplicationHandle has been unregistered and its related resources has been freed. Further calls on this application should not be made because they may have unexpected results.

      Throws:
        `java.lang.SecurityException` - if the caller doesn't have "lifecycle" `ApplicationAdminPermission` for the corresponding application.
        `java.lang.IllegalStateException` - if the application handle is unregistered

    - #### destroySpecific

          protected abstract void destroySpecific()

      Called by the destroy() method to perform application model specific steps to stop and destroy an application instance safely.
      Throws:
        `java.lang.IllegalStateException` - if the application handle is unregistered