ScheduledApplication
Date: 2016-06-25

org.osgi.service.application

## Interface ScheduledApplication

-     public interface ScheduledApplication

  It is allowed to schedule an application based on a specific event. ScheduledApplication service keeps the schedule information. When the specified event is fired a new instance must be launched. Note that launching operation may fail because e.g. the application is locked.

  Each `ScheduledApplication` instance has an identifier which is unique within the scope of the application being scheduled.

  `ScheduledApplication` instances are registered as services. The `APPLICATION_PID` service property contains the PID of the application being scheduled, the `SCHEDULE_ID` service property contains the schedule identifier.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `APPLICATION_PID` The property key for the identifier of the application being scheduled.
    `static java.lang.String` | `DAY_OF_MONTH` The name of the day of month attribute of a virtual timer event.
    `static java.lang.String` | `DAY_OF_WEEK` The name of the day of week attribute of a virtual timer event.
    `static java.lang.String` | `HOUR_OF_DAY` The name of the hour of day attribute of a virtual timer event.
    `static java.lang.String` | `MINUTE` The name of the minute attribute of a virtual timer event.
    `static java.lang.String` | `MONTH` The name of the month attribute of a virtual timer event.
    `static java.lang.String` | `SCHEDULE_ID` The property key for the schedule identifier.
    `static java.lang.String` | `TIMER_TOPIC` The topic name for the virtual timer topic.
    `static java.lang.String` | `TRIGGERING_EVENT` The key for the startup argument used to pass the event object that triggered the schedule to launch the application instance.
    `static java.lang.String` | `YEAR` The name of the year attribute of a virtual timer event.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ApplicationDescriptor` | `getApplicationDescriptor()` Retrieves the ApplicationDescriptor which represents the application and necessary for launching.
    `java.util.Map` | `getArguments()` Queries the startup arguments specified when the application was scheduled.
    `java.lang.String` | `getEventFilter()` Queries the event filter for the triggering event.
    `java.lang.String` | `getScheduleId()` Returns the identifier of this schedule.
    `java.lang.String` | `getTopic()` Queries the topic of the triggering event.
    `boolean` | `isRecurring()` Queries if the schedule is recurring.
    `void` | `remove()` Cancels this schedule of the application.

- - ### Field Detail

    - #### APPLICATION_PID

          static final java.lang.String APPLICATION_PID

      The property key for the identifier of the application being scheduled.
      See Also:
        Constant Field Values

    - #### SCHEDULE_ID

          static final java.lang.String SCHEDULE_ID

      The property key for the schedule identifier. The identifier is unique within the scope of the application being scheduled.
      See Also:
        Constant Field Values

    - #### TRIGGERING_EVENT

          static final java.lang.String TRIGGERING_EVENT

      The key for the startup argument used to pass the event object that triggered the schedule to launch the application instance. The event is passed in a `GuardedObject` protected by the corresponding `TopicPermission`.
      See Also:
        Constant Field Values

    - #### TIMER_TOPIC

          static final java.lang.String TIMER_TOPIC

      The topic name for the virtual timer topic. Time based schedules should be created using this topic.
      See Also:
        Constant Field Values

    - #### YEAR

          static final java.lang.String YEAR

      The name of the year attribute of a virtual timer event. The value is defined by `Calendar.YEAR`.
      See Also:
        Constant Field Values

    - #### MONTH

          static final java.lang.String MONTH

      The name of the month attribute of a virtual timer event. The value is defined by `Calendar.MONTH`.
      See Also:
        Constant Field Values

    - #### DAY_OF_MONTH

          static final java.lang.String DAY_OF_MONTH

      The name of the day of month attribute of a virtual timer event. The value is defined by `Calendar.DAY_OF_MONTH`.
      See Also:
        Constant Field Values

    - #### DAY_OF_WEEK

          static final java.lang.String DAY_OF_WEEK

      The name of the day of week attribute of a virtual timer event. The value is defined by `Calendar.DAY_OF_WEEK`.
      See Also:
        Constant Field Values

    - #### HOUR_OF_DAY

          static final java.lang.String HOUR_OF_DAY

      The name of the hour of day attribute of a virtual timer event. The value is defined by `Calendar.HOUR_OF_DAY`.
      See Also:
        Constant Field Values

    - #### MINUTE

          static final java.lang.String MINUTE

      The name of the minute attribute of a virtual timer event. The value is defined by `Calendar.MINUTE`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getScheduleId

          java.lang.String getScheduleId()

      Returns the identifier of this schedule. The identifier is unique within the scope of the application that the schedule is related to.
      Returns:
        the identifier of this schedule

    - #### getTopic

          java.lang.String getTopic()

      Queries the topic of the triggering event. The topic may contain a trailing asterisk as wildcard.
      Returns:
        the topic of the triggering event
      Throws:
        `java.lang.IllegalStateException` - if the scheduled application service is unregistered

    - #### getEventFilter

          java.lang.String getEventFilter()

      Queries the event filter for the triggering event.
      Returns:
        the event filter for triggering event
      Throws:
        `java.lang.IllegalStateException` - if the scheduled application service is unregistered

    - #### isRecurring

          boolean isRecurring()

      Queries if the schedule is recurring.
      Returns:
        true if the schedule is recurring, otherwise returns false
      Throws:
        `java.lang.IllegalStateException` - if the scheduled application service is unregistered

    - #### getApplicationDescriptor

          ApplicationDescriptor getApplicationDescriptor()

      Retrieves the ApplicationDescriptor which represents the application and necessary for launching.
      Returns:
        the application descriptor that represents the scheduled application
      Throws:
        `java.lang.IllegalStateException` - if the scheduled application service is unregistered

    - #### getArguments

          java.util.Map getArguments()

      Queries the startup arguments specified when the application was scheduled. The method returns a copy of the arguments, it is not possible to modify the arguments after scheduling.
      Returns:
        the startup arguments of the scheduled application. It may be null if null argument was specified.
      Throws:
        `java.lang.IllegalStateException` - if the scheduled application service is unregistered

    - #### remove

          void remove()

      Cancels this schedule of the application.
      Throws:
        `java.lang.SecurityException` - if the caller doesn't have "schedule" ApplicationAdminPermission for the scheduled application.
        `java.lang.IllegalStateException` - if the scheduled application service is unregistered