KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > application > ApplicationHandle


1 /*
2  * $Header: /cvsroot/eclipse/org.eclipse.equinox.app/src/org/osgi/service/application/ApplicationHandle.java,v 1.4 2006/09/15 14:46:00 twatson 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 org.osgi.framework.Constants;
22
23 /**
24  * ApplicationHandle is an OSGi service interface which represents an instance
25  * of an application. It provides the functionality to query and manipulate the
26  * lifecycle state of the represented application instance. It defines constants
27  * for the lifecycle states.
28  */
29 public abstract class ApplicationHandle {
30     /*
31      * NOTE: An implementor may also choose to replace this class in
32      * their distribution with a class that directly interfaces with the
33      * org.osgi.service.application implementation. This replacement class MUST NOT alter the
34      * public/protected signature of this class.
35      */
36
37     /**
38      * The property key for the unique identifier (PID) of the application
39      * instance.
40      */
41     public static final String JavaDoc APPLICATION_PID = Constants.SERVICE_PID;
42     
43     /**
44      * The property key for the pid of the corresponding application descriptor.
45      */
46     public final static String JavaDoc APPLICATION_DESCRIPTOR = "application.descriptor";
47     
48     /**
49      * The property key for the state of this appliction instance.
50      */
51     public final static String JavaDoc APPLICATION_STATE = "application.state";
52
53     /**
54      * The application instance is running. This is the initial state of a newly
55      * created application instance.
56      */
57     public final static String JavaDoc RUNNING = "RUNNING";
58     
59   /**
60    * The application instance is being stopped. This is the state of the
61    * application instance during the execution of the <code>destroy()</code>
62    * method.
63    */
64     public final static String JavaDoc STOPPING = "STOPPING";
65
66     private final String JavaDoc instanceId;
67     
68     private final ApplicationDescriptor descriptor;
69
70     /**
71      * Application instance identifier is specified by the container when the
72      * instance is created. The instance identifier must remain static for the
73      * lifetime of the instance, it must remain the same even across framework
74      * restarts for the same application instance. This value must be the same
75      * as the <code>service.pid</code> service property of this application
76      * handle.
77      * <p>
78      * The instance identifier should follow the following scheme:
79      * &lt;<i>application descriptor PID</i>&gt;.&lt;<i>index</i>&gt;
80      * where &lt;<i>application descriptor PID</i>&gt; is the PID of the
81      * corresponding <code>ApplicationDescriptor</code> and &lt;<i>index</i>&gt;
82      * is a unique integer index assigned by the application container.
83      * Even after destroying the application index the same index value should not
84      * be reused in a reasonably long timeframe.
85      *
86      * @param instanceId the instance identifier of the represented application
87      * instance. It must not be null.
88      *
89      * @param descriptor the <code>ApplicationDescriptor</code> of the represented
90      * application instance. It must not be null.
91      *
92      * @throws NullPointerException if any of the arguments is null.
93      */
94     protected ApplicationHandle(String JavaDoc instanceId, ApplicationDescriptor descriptor ) {
95         if( (null == instanceId) || (null == descriptor) ) {
96             throw new NullPointerException JavaDoc("Parameters must not be null!");
97         }
98         
99         this.instanceId = instanceId;
100         this.descriptor = descriptor;
101     }
102
103     /**
104      * Retrieves the <code>ApplicationDescriptor</code> to which this
105      * <code>ApplicationHandle</code> belongs.
106      *
107      * @return The corresponding <code>ApplicationDescriptor</code>
108      */
109     public final ApplicationDescriptor getApplicationDescriptor() {
110         return descriptor;
111     }
112
113     /**
114      * Get the state of the application instance.
115      *
116      * @return the state of the application.
117      *
118      * @throws IllegalStateException
119      * if the application handle is unregistered
120      */
121     public abstract String JavaDoc getState();
122
123     /**
124      * Returns the unique identifier of this instance. This value is also
125      * available as a service property of this application handle's service.pid.
126      *
127      * @return the unique identifier of the instance
128      */
129     public final String JavaDoc getInstanceId() {
130         return instanceId;
131     }
132
133     /**
134      * The application instance's lifecycle state can be influenced by this
135      * method. It lets the application instance perform operations to stop
136      * the application safely, e.g. saving its state to a permanent storage.
137      * <p>
138      * The method must check if the lifecycle transition is valid; a STOPPING
139      * application cannot be stopped. If it is invalid then the method must
140      * exit. Otherwise the lifecycle state of the application instance must be
141      * set to STOPPING. Then the destroySpecific() method must be called to
142      * perform any application model specific steps for safe stopping of the
143      * represented application instance.
144      * <p>
145      * At the end the <code>ApplicationHandle</code> must be unregistered.
146      * This method should free all the resources related to this
147      * <code>ApplicationHandle</code>.
148      * <p>
149      * When this method is completed the application instance has already made
150      * its operations for safe stopping, the ApplicationHandle has been
151      * unregistered and its related resources has been freed. Further calls on
152      * this application should not be made because they may have unexpected
153      * results.
154      *
155      * @throws SecurityException
156      * if the caller doesn't have "lifecycle"
157      * <code>ApplicationAdminPermission</code> for the corresponding application.
158      *
159      * @throws IllegalStateException
160      * if the application handle is unregistered
161      */
162     public final void destroy() {
163         if (STOPPING.equals(getState()))
164             return;
165         SecurityManager JavaDoc sm = System.getSecurityManager();
166         if (sm != null)
167             sm.checkPermission(new ApplicationAdminPermission(getApplicationDescriptor(), ApplicationAdminPermission.LIFECYCLE_ACTION));
168         destroySpecific();
169     }
170
171     /**
172      * Called by the destroy() method to perform application model specific
173      * steps to stop and destroy an application instance safely.
174      *
175      * @throws IllegalStateException
176      * if the application handle is unregistered
177      */
178     protected abstract void destroySpecific();
179     
180
181 }
182
Popular Tags