001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.geronimo.kernel;
018
019 import java.util.Date;
020 import java.util.Set;
021 import java.util.Collections;
022 import javax.management.ObjectName;
023
024 import org.apache.geronimo.gbean.GBeanData;
025 import org.apache.geronimo.gbean.GBeanInfo;
026 import org.apache.geronimo.gbean.AbstractNameQuery;
027 import org.apache.geronimo.gbean.AbstractName;
028 import org.apache.geronimo.kernel.lifecycle.LifecycleMonitor;
029 import org.apache.geronimo.kernel.proxy.ProxyManager;
030 import org.apache.geronimo.kernel.repository.Artifact;
031
032 /**
033 * @version $Rev:386515 $ $Date: 2008-10-21 14:44:05 +0000 (Tue, 21 Oct 2008) $
034 */
035 public interface Kernel {
036 /**
037 * The JMX name used by a Kernel to register itself when it boots.
038 */
039 ObjectName KERNEL = ObjectNameUtil.getObjectName(":role=Kernel");
040 AbstractName KERNEL_NAME = new AbstractName(new Artifact("geronimo", "boot", "none", "car"), Collections.singletonMap("role", "kernel"), KERNEL);
041
042 /**
043 * Get the name of this kernel
044 *
045 * @return the name of this kernel
046 */
047 String getKernelName();
048
049 /**
050 * Gets the naming system used by this kernel.
051 * @return the naming system used by this kernel
052 */
053 Naming getNaming();
054
055 /**
056 * Gets the dependency manager kernel service
057 * @return the dependency manager or null if the kernel is not running
058 */
059 DependencyManager getDependencyManager();
060
061 /**
062 * Gets the lifecycle monitor kernel service
063 * @return the lifecycle monitor or null if the kernel is not running
064 */
065 LifecycleMonitor getLifecycleMonitor();
066
067 /**
068 * Gets the proxy manager kernel service
069 * @return the proxy manager or null if the kernel is not running
070 */
071 ProxyManager getProxyManager();
072
073 /**
074 * Load a specific GBean into this kernel.
075 * This is intended for applications that are embedding the kernel.
076 *
077 * @param gbeanData the GBean to load
078 * @param classLoader the class loader to use to load the gbean
079 * @throws org.apache.geronimo.kernel.GBeanAlreadyExistsException if the name is already used
080 * @throws org.apache.geronimo.kernel.InternalKernelException if there is a problem during registration
081 */
082 void loadGBean(GBeanData gbeanData, ClassLoader classLoader) throws GBeanAlreadyExistsException, InternalKernelException;
083
084 /**
085 * Is there a GBean registered with the kernel under the specified name?
086 * @param name the name to check
087 * @return true if there is a gbean registered under the specified name; false otherwise
088 */
089 boolean isLoaded(AbstractName name);
090 boolean isLoaded(String shortName);
091 boolean isLoaded(Class type);
092 boolean isLoaded(String shortName, Class type);
093
094 /**
095 * Gets the specified GBean instance.
096 *
097 * @param name the GBean instance to get
098 * @throws org.apache.geronimo.kernel.GBeanNotFoundException if the GBean could not be found
099 * @throws InternalKernelException if there is a general error
100 * @throws IllegalStateException If the gbean is disabled
101 */
102 Object getGBean(AbstractName name) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
103 Object getGBean(String shortName) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
104 Object getGBean(Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
105 Object getGBean(String shortName, Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
106
107 /**
108 * Start a specific GBean.
109 *
110 * @param name the GBean to start
111 * @throws org.apache.geronimo.kernel.GBeanNotFoundException if the GBean could not be found
112 * @throws InternalKernelException if there GBean is not state manageable or if there is a general error
113 * @throws IllegalStateException If the gbean is disabled
114 */
115 void startGBean(AbstractName name) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
116 void startGBean(String shortName) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
117 void startGBean(Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
118 void startGBean(String shortName, Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
119
120 /**
121 * Start a specific GBean and its children.
122 *
123 * @param name the GBean to start
124 * @throws GBeanNotFoundException if the GBean could not be found
125 * @throws InternalKernelException if there GBean is not state manageable or if there is a general error
126 * @throws IllegalStateException If the gbean is disabled
127 */
128 void startRecursiveGBean(AbstractName name) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
129 void startRecursiveGBean(String shortName) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
130 void startRecursiveGBean(Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
131 void startRecursiveGBean(String shortName, Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
132
133 /**
134 * Is there a GBean registered with the kernel under the specified name and is it running?
135 * @param name the name to check
136 * @return true if there is a gbean registered under the specified name and is it running; false otherwise
137 */
138 boolean isRunning(AbstractName name);
139 boolean isRunning(String shortName);
140 boolean isRunning(Class type);
141 boolean isRunning(String shortName, Class type);
142
143 /**
144 * Stop a specific GBean.
145 *
146 * @param name the GBean to stop
147 * @throws GBeanNotFoundException if the GBean could not be found
148 * @throws InternalKernelException if there GBean is not state manageable or if there is a general error
149 * @throws IllegalStateException If the gbean is disabled
150 */
151 void stopGBean(AbstractName name) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
152 void stopGBean(String shortName) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
153 void stopGBean(Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
154 void stopGBean(String shortName, Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
155
156 /**
157 * Unload a specific GBean.
158 * This is intended for applications that are embedding the kernel.
159 *
160 * @param name the name of the GBean to unregister
161 * @throws GBeanNotFoundException if the GBean could not be found
162 * @throws InternalKernelException if there GBean is a problem while unloading the GBean
163 */
164 void unloadGBean(AbstractName name) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
165 void unloadGBean(String shortName) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
166 void unloadGBean(Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
167 void unloadGBean(String shortName, Class type) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
168
169 /**
170 * Gets the state of the specified GBean.
171 * @param name the name of the GBean
172 * @return the state of the GBean
173 * @throws GBeanNotFoundException if the GBean could not be found
174 */
175 int getGBeanState(AbstractName name) throws GBeanNotFoundException;
176 int getGBeanState(String shortName) throws GBeanNotFoundException;
177 int getGBeanState(Class type) throws GBeanNotFoundException;
178 int getGBeanState(String shortName, Class type) throws GBeanNotFoundException;
179
180 /**
181 * Gets the time the specified GBean was started
182 * @param name the name of the GBean
183 * @return the start time of the GBean or 0 if not running
184 * @throws GBeanNotFoundException if the GBean could not be found
185 */
186 long getGBeanStartTime(AbstractName name) throws GBeanNotFoundException;
187 long getGBeanStartTime(String shortName) throws GBeanNotFoundException;
188 long getGBeanStartTime(Class type) throws GBeanNotFoundException;
189 long getGBeanStartTime(String shortName, Class type) throws GBeanNotFoundException;
190
191 /**
192 * Gets the ClassLoader used to register the specified GBean
193 * @param name the name of the gbean from which the class loader should be extracted
194 * @return the class loader associated with the specified GBean
195 * @throws GBeanNotFoundException if the specified GBean is not registered with the kernel
196 */
197 ClassLoader getClassLoaderFor(AbstractName name) throws GBeanNotFoundException;
198 ClassLoader getClassLoaderFor(String shortName) throws GBeanNotFoundException;
199 ClassLoader getClassLoaderFor(Class type) throws GBeanNotFoundException;
200 ClassLoader getClassLoaderFor(String shortName, Class type) throws GBeanNotFoundException;
201
202 /**
203 * Return the GBeanInfo for a registered GBean instance.
204 * @param name the name of the GBean whose info should be returned
205 * @return the info for that instance
206 * @throws GBeanNotFoundException if there is no instance with the supplied name
207 */
208 GBeanInfo getGBeanInfo(AbstractName name) throws GBeanNotFoundException;
209 GBeanInfo getGBeanInfo(String shortName) throws GBeanNotFoundException;
210 GBeanInfo getGBeanInfo(Class type) throws GBeanNotFoundException;
211 GBeanInfo getGBeanInfo(String shortName, Class type) throws GBeanNotFoundException;
212
213 /**
214 * Return the GBeanData for a GBean instance.
215 * @param name the name of the GBean whose info should be returned
216 * @return the info for that instance
217 * @throws GBeanNotFoundException if there is no instance with the supplied name
218 */
219 GBeanData getGBeanData(AbstractName name) throws GBeanNotFoundException, InternalKernelException;
220 GBeanData getGBeanData(String shortName) throws GBeanNotFoundException, InternalKernelException;
221 GBeanData getGBeanData(Class type) throws GBeanNotFoundException, InternalKernelException;
222 GBeanData getGBeanData(String shortName, Class type) throws GBeanNotFoundException, InternalKernelException;
223
224 /**
225 * Gets the AbstractNames of all GBeans matching the abstractNameQuery.
226 * @param abstractNameQuery the query to execute
227 * @return the AbstractNames of all matching GBeans
228 */
229 Set listGBeans(AbstractNameQuery abstractNameQuery);
230
231 /**
232 * Returns a Set of all GBeans matching the set of object name pattern
233 * @param abstractNameQueries the queries to execute
234 * @return a List of AbstractNameName of matching GBeans registered with this kernel
235 */
236 Set listGBeans(Set abstractNameQueries);
237
238 /**
239 * Gets the value of an attribute on the specified gbean
240 * @param name the name of the gbean from which the attribute will be retrieved
241 * @param attributeName the name of the attribute to fetch
242 * @return the value of the attribute
243 * @throws GBeanNotFoundException if there is not a gbean under the specified name
244 * @throws NoSuchAttributeException if the gbean does not contain the specified attribute
245 * @throws Exception if the gbean throws an exception from the getter
246 */
247 Object getAttribute(AbstractName name, String attributeName) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
248 Object getAttribute(String shortName, String attributeName) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
249 Object getAttribute(Class type, String attributeName) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
250 Object getAttribute(String shortName, Class type, String attributeName) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
251
252 /**
253 * Sets the value of an attribute on the specified gbean
254 * @param name the name of the gbean from in which the new attribute value will be set
255 * @param attributeName the name of the attribute to set
256 * @param attributeValue the new value of the attribute
257 * @throws GBeanNotFoundException if there is not a gbean under the specified name
258 * @throws NoSuchAttributeException if the gbean does not contain the specified attribute
259 * @throws Exception if the gbean throws an exception from the setter
260 */
261 void setAttribute(AbstractName name, String attributeName, Object attributeValue) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
262 void setAttribute(String shortName, String attributeName, Object attributeValue) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
263 void setAttribute(Class type, String attributeName, Object attributeValue) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
264 void setAttribute(String shortName, Class type, String attributeName, Object attributeValue) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
265
266 /**
267 * Invokes a no-argument method on the specified GBean
268 * @param name the name of the gbean from in which the new attribute value will be set
269 * @param methodName the name of the method to invoke
270 * @return the return value of the method or null if the specified method does not return a value
271 * @throws GBeanNotFoundException if there is not a gbean under the specified name
272 * @throws NoSuchOperationException if the gbean does not have the specified operation
273 * @throws InternalKernelException if an error occurs within the kernel itself
274 * @throws Exception if the method throws an exception
275 */
276 Object invoke(AbstractName name, String methodName) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
277 Object invoke(String shortName, String methodName) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
278 Object invoke(Class type, String methodName) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
279 Object invoke(String shortName, Class type, String methodName) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
280
281 /**
282 * Invokes a method on the specified GBean with the specified arguments
283 * @param name the name of the gbean from in which the new attribute value will be set
284 * @param methodName the name of the method to invoke
285 * @param args the arguments to pass to the method
286 * @param types the types of the arguments; the types are used to determine the signature of the mehod that should be invoked
287 * @return the return value of the method or null if the specified method does not return a value
288 * @throws GBeanNotFoundException if there is not a gbean under the specified name
289 * @throws NoSuchOperationException if the gbean does not have the specified operation
290 * @throws InternalKernelException if an error occurs within the kernel itself
291 * @throws Exception if the method throws an exception
292 */
293 Object invoke(AbstractName name, String methodName, Object[] args, String[] types) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
294 Object invoke(String shortName, String methodName, Object[] args, String[] types) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
295 Object invoke(Class type, String methodName, Object[] args, String[] types) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
296 Object invoke(String shortName, Class type, String methodName, Object[] args, String[] types) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
297
298 /**
299 * Assuming the argument represents a service running in the kernel,
300 * returns an AbstractName for it. If the argument is not a service or the
301 * kernel cannot produce an AbstractName for it, returns null.
302 */
303 AbstractName getAbstractNameFor(Object service);
304
305 /**
306 * Assuming the argument represents a service running in the kernel,
307 * returns the short name of the service. If the argument is not a service, returns null.
308 */
309 String getShortNameFor(Object service);
310
311 /**
312 * Brings the kernel online
313 * @throws Exception if the kernel can not boot
314 */
315 void boot() throws Exception;
316
317 /**
318 * Returns the time this kernel was last booted.
319 * @return the time this kernel was last booted; null if the kernel has not been
320 */
321 Date getBootTime();
322
323 /**
324 * Registers a runnable to execute when the kernel is shutdown
325 * @param hook a runnable to execute when the kernel is shutdown
326 */
327 void registerShutdownHook(Runnable hook);
328
329 /**
330 * Unregisters a runnable from the list to execute when the kernel is shutdown
331 * @param hook the runnable that should be removed
332 */
333 void unregisterShutdownHook(Runnable hook);
334
335 /**
336 * Stops the kernel
337 */
338 void shutdown();
339
340 /**
341 * Has the kernel been booted
342 * @return true if the kernel has been booted; false otherwise
343 */
344 boolean isRunning();
345
346 /**
347 * @deprecated Use AbstractName version instead
348 */
349 Object getGBean(ObjectName name) throws GBeanNotFoundException, InternalKernelException, IllegalStateException;
350 /**
351 * @deprecated Use AbstractName version instead
352 */
353 int getGBeanState(ObjectName name) throws GBeanNotFoundException;
354 /**
355 * @deprecated Use AbstractName version instead
356 */
357 GBeanInfo getGBeanInfo(ObjectName name) throws GBeanNotFoundException;
358 /**
359 * Returns a Set with elements of type ObjectName
360 *
361 * @deprecated Use AbstractNameQuery version instead
362 */
363 Set listGBeans(ObjectName pattern);
364 /**
365 * @deprecated Use AbstractName version instead
366 */
367 Object getAttribute(ObjectName name, String attributeName) throws GBeanNotFoundException, NoSuchAttributeException, Exception;
368 /**
369 * @deprecated Use AbstractName version instead
370 */
371 Object invoke(ObjectName name, String methodName) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
372 /**
373 * @deprecated Use AbstractName version instead
374 */
375 Object invoke(ObjectName name, String methodName, Object[] args, String[] types) throws GBeanNotFoundException, NoSuchOperationException, InternalKernelException, Exception;
376
377 String getStateReason(AbstractName abstractName);
378 }