ScheduledApplication


1   /*
2    * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ScheduledApplication.java,v 1.20 2006/07/06 14:59:29 sboshev Exp $
3    * 
4    * Copyright (c) OSGi Alliance (2004, 2006). All Rights Reserved.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.osgi.service.application;
20  
21  import java.util.Map  ;
22  
23  /**
24   * It is allowed to schedule an application based on a specific event.
25   * ScheduledApplication service keeps the schedule information. When the
26   * specified event is fired a new instance must be launched. Note that launching
27   * operation may fail because e.g. the application is locked.
28   * <p>
29   * Each <code>ScheduledApplication</code> instance has an identifier which is
30   * unique within the scope of the application being scheduled.
31   * <p>
32   * <code>ScheduledApplication</code> instances are registered as services.
33   * The {@link #APPLICATION_PID} service property contains the PID of the
34   * application being scheduled, the {@link #SCHEDULE_ID} service property
35   * contains the schedule identifier.
36   */
37  public interface ScheduledApplication {
38      
39      /**
40       * The property key for the identifier of the application being scheduled.
41       */
42      public static final String   APPLICATION_PID = ApplicationDescriptor.APPLICATION_PID;
43      
44      /**
45       * The property key for the schedule identifier. The identifier is unique
46       * within the scope of the application being scheduled.
47       */
48      public static final String   SCHEDULE_ID = "schedule.id";
49      
50      /**
51       * The key for the startup argument used to pass the event object that 
52       * triggered the schedule to launch the application instance.
53       * The event is passed in a {@link java.security.GuardedObject}
54       * protected by the corresponding 
55       * {@link org.osgi.service.event.TopicPermission}.
56       */
57      public static final String   TRIGGERING_EVENT = "org.osgi.triggeringevent";
58      
59      /**
60       * The topic name for the virtual timer topic. Time based schedules
61       * should be created using this topic.
62       */
63      public static final String   TIMER_TOPIC = "org/osgi/application/timer";
64      
65      /**
66       * The name of the <i>year</i> attribute of a virtual timer event. The value is
67       * defined by {@link java.util.Calendar#YEAR}.
68       */
69      public static final String   YEAR = "year";
70      
71      /**
72       * The name of the <i>month</i> attribute of a virtual timer event. The value is
73       * defined by {@link java.util.Calendar#MONTH}.
74       */
75      public static final String   MONTH = "month";
76      
77      /**
78       * The name of the <i>day of month</i> attribute of a virtual timer event. The value is
79       * defined by {@link java.util.Calendar#DAY_OF_MONTH}.
80       */
81      public static final String   DAY_OF_MONTH = "day_of_month";
82      
83      /**
84       * The name of the <i>day of week</i> attribute of a virtual timer event. The value is
85       * defined by {@link java.util.Calendar#DAY_OF_WEEK}.
86       */
87      public static final String   DAY_OF_WEEK = "day_of_week";
88      
89      /**
90       * The name of the <i>hour of day</i> attribute of a virtual timer event. The value is
91       * defined by {@link java.util.Calendar#HOUR_OF_DAY}.
92       */
93      public static final String   HOUR_OF_DAY = "hour_of_day";
94      
95      /**
96       * The name of the <i>minute</i> attribute of a virtual timer event. The value is
97       * defined by {@link java.util.Calendar#MINUTE}.
98       */
99      public static final String   MINUTE = "minute";
100     
101     
102     /**
103      * Returns the identifier of this schedule. The identifier is unique within
104      * the scope of the application that the schedule is related to. 
105      * @return the identifier of this schedule
106      * 
107      */
108     public String   getScheduleId();
109 
110     /**
111      * Queries the topic of the triggering event. The topic may contain a
112      * trailing asterisk as wildcard.
113      * 
114      * @return the topic of the triggering event
115      * 
116      * @throws IllegalStateException
117      *             if the scheduled application service is unregistered
118      */
119     public String   getTopic();
120 
121     /**
122      * Queries the event filter for the triggering event.
123      * 
124      * @return the event filter for triggering event
125      * 
126      * @throws IllegalStateException
127      *             if the scheduled application service is unregistered
128      */
129     public String   getEventFilter();
130 
131     /**
132      * Queries if the schedule is recurring.
133      * 
134      * @return true if the schedule is recurring, otherwise returns false
135      * 
136      * @throws IllegalStateException
137      *             if the scheduled application service is unregistered
138      */
139     public boolean isRecurring();
140 
141     /**
142      * Retrieves the ApplicationDescriptor which represents the application and
143      * necessary for launching.
144      * 
145      * @return the application descriptor that
146      *         represents the scheduled application
147      * 
148      * @throws IllegalStateException
149      *             if the scheduled application service is unregistered
150      */
151     public ApplicationDescriptor getApplicationDescriptor();
152 
153     /**
154      * Queries the startup arguments specified when the application was
155      * scheduled. The method returns a copy of the arguments, it is not possible
156      * to modify the arguments after scheduling.
157      * 
158      * @return the startup arguments of the scheduled application. It may be
159      *         null if null argument was specified.
160      * 
161      * @throws IllegalStateException
162      *             if the scheduled application service is unregistered
163      */
164     public Map   getArguments();
165 
166     /**
167      * Cancels this schedule of the application.
168      * 
169      * @throws SecurityException
170      *             if the caller doesn't have "schedule"
171      *             ApplicationAdminPermission for the scheduled application.
172      * @throws IllegalStateException
173      *             if the scheduled application service is unregistered
174      */
175     public void remove();
176 }
177
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags