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: */package org.apache.geronimo.kernel;
017:
018: import java.util.Date;
019: import java.util.Set;
020: import java.util.Collections;
021: import javax.management.ObjectName;
022:
023: import org.apache.geronimo.gbean.GBeanData;
024: import org.apache.geronimo.gbean.GBeanInfo;
025: import org.apache.geronimo.gbean.AbstractNameQuery;
026: import org.apache.geronimo.gbean.AbstractName;
027: import org.apache.geronimo.kernel.lifecycle.LifecycleMonitor;
028: import org.apache.geronimo.kernel.proxy.ProxyManager;
029: import org.apache.geronimo.kernel.repository.Artifact;
030:
031: /**
032: * @version $Rev:386515 $ $Date: 2007-02-10 18:00:20 -0800 (Sat, 10 Feb 2007) $
033: */
034: public interface Kernel {
035: /**
036: * The JMX name used by a Kernel to register itself when it boots.
037: */
038: ObjectName KERNEL = ObjectNameUtil.getObjectName(":role=Kernel");
039: AbstractName KERNEL_NAME = new AbstractName(new Artifact(
040: "geronimo", "boot", "none", "car"), Collections
041: .singletonMap("role", "kernel"), KERNEL);
042:
043: /**
044: * Get the name of this kernel
045: *
046: * @return the name of this kernel
047: */
048: String getKernelName();
049:
050: /**
051: * Gets the naming system used by this kernel.
052: * @return the naming system used by this kernel
053: */
054: Naming getNaming();
055:
056: /**
057: * Gets the dependency manager kernel service
058: * @return the dependency manager or null if the kernel is not running
059: */
060: DependencyManager getDependencyManager();
061:
062: /**
063: * Gets the lifecycle monitor kernel service
064: * @return the lifecycle monitor or null if the kernel is not running
065: */
066: LifecycleMonitor getLifecycleMonitor();
067:
068: /**
069: * Gets the proxy manager kernel service
070: * @return the proxy manager or null if the kernel is not running
071: */
072: ProxyManager getProxyManager();
073:
074: /**
075: * Load a specific GBean into this kernel.
076: * This is intended for applications that are embedding the kernel.
077: *
078: * @param gbeanData the GBean to load
079: * @param classLoader the class loader to use to load the gbean
080: * @throws org.apache.geronimo.kernel.GBeanAlreadyExistsException if the name is already used
081: * @throws org.apache.geronimo.kernel.InternalKernelException if there is a problem during registration
082: */
083: void loadGBean(GBeanData gbeanData, ClassLoader classLoader)
084: throws GBeanAlreadyExistsException, InternalKernelException;
085:
086: /**
087: * Is there a GBean registered with the kernel under the specified name?
088: * @param name the name to check
089: * @return true if there is a gbean registered under the specified name; false otherwise
090: */
091: boolean isLoaded(AbstractName name);
092:
093: boolean isLoaded(String shortName);
094:
095: boolean isLoaded(Class type);
096:
097: boolean isLoaded(String shortName, Class type);
098:
099: /**
100: * Gets the specified GBean instance.
101: *
102: * @param name the GBean instance to get
103: * @throws org.apache.geronimo.kernel.GBeanNotFoundException if the GBean could not be found
104: * @throws InternalKernelException if there is a general error
105: * @throws IllegalStateException If the gbean is disabled
106: */
107: Object getGBean(AbstractName name) throws GBeanNotFoundException,
108: InternalKernelException, IllegalStateException;
109:
110: Object getGBean(String shortName) throws GBeanNotFoundException,
111: InternalKernelException, IllegalStateException;
112:
113: Object getGBean(Class type) throws GBeanNotFoundException,
114: InternalKernelException, IllegalStateException;
115:
116: Object getGBean(String shortName, Class type)
117: throws GBeanNotFoundException, InternalKernelException,
118: IllegalStateException;
119:
120: /**
121: * Start a specific GBean.
122: *
123: * @param name the GBean to start
124: * @throws org.apache.geronimo.kernel.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 startGBean(AbstractName name) throws GBeanNotFoundException,
129: InternalKernelException, IllegalStateException;
130:
131: void startGBean(String shortName) throws GBeanNotFoundException,
132: InternalKernelException, IllegalStateException;
133:
134: void startGBean(Class type) throws GBeanNotFoundException,
135: InternalKernelException, IllegalStateException;
136:
137: void startGBean(String shortName, Class type)
138: throws GBeanNotFoundException, InternalKernelException,
139: IllegalStateException;
140:
141: /**
142: * Start a specific GBean and its children.
143: *
144: * @param name the GBean to start
145: * @throws GBeanNotFoundException if the GBean could not be found
146: * @throws InternalKernelException if there GBean is not state manageable or if there is a general error
147: * @throws IllegalStateException If the gbean is disabled
148: */
149: void startRecursiveGBean(AbstractName name)
150: throws GBeanNotFoundException, InternalKernelException,
151: IllegalStateException;
152:
153: void startRecursiveGBean(String shortName)
154: throws GBeanNotFoundException, InternalKernelException,
155: IllegalStateException;
156:
157: void startRecursiveGBean(Class type) throws GBeanNotFoundException,
158: InternalKernelException, IllegalStateException;
159:
160: void startRecursiveGBean(String shortName, Class type)
161: throws GBeanNotFoundException, InternalKernelException,
162: IllegalStateException;
163:
164: /**
165: * Is there a GBean registered with the kernel under the specified name and is it running?
166: * @param name the name to check
167: * @return true if there is a gbean registered under the specified name and is it running; false otherwise
168: */
169: boolean isRunning(AbstractName name);
170:
171: boolean isRunning(String shortName);
172:
173: boolean isRunning(Class type);
174:
175: boolean isRunning(String shortName, Class type);
176:
177: /**
178: * Stop a specific GBean.
179: *
180: * @param name the GBean to stop
181: * @throws GBeanNotFoundException if the GBean could not be found
182: * @throws InternalKernelException if there GBean is not state manageable or if there is a general error
183: * @throws IllegalStateException If the gbean is disabled
184: */
185: void stopGBean(AbstractName name) throws GBeanNotFoundException,
186: InternalKernelException, IllegalStateException;
187:
188: void stopGBean(String shortName) throws GBeanNotFoundException,
189: InternalKernelException, IllegalStateException;
190:
191: void stopGBean(Class type) throws GBeanNotFoundException,
192: InternalKernelException, IllegalStateException;
193:
194: void stopGBean(String shortName, Class type)
195: throws GBeanNotFoundException, InternalKernelException,
196: IllegalStateException;
197:
198: /**
199: * Unload a specific GBean.
200: * This is intended for applications that are embedding the kernel.
201: *
202: * @param name the name of the GBean to unregister
203: * @throws GBeanNotFoundException if the GBean could not be found
204: * @throws InternalKernelException if there GBean is a problem while unloading the GBean
205: */
206: void unloadGBean(AbstractName name) throws GBeanNotFoundException,
207: InternalKernelException, IllegalStateException;
208:
209: void unloadGBean(String shortName) throws GBeanNotFoundException,
210: InternalKernelException, IllegalStateException;
211:
212: void unloadGBean(Class type) throws GBeanNotFoundException,
213: InternalKernelException, IllegalStateException;
214:
215: void unloadGBean(String shortName, Class type)
216: throws GBeanNotFoundException, InternalKernelException,
217: IllegalStateException;
218:
219: /**
220: * Gets the state of the specified GBean.
221: * @param name the name of the GBean
222: * @return the state of the GBean
223: * @throws GBeanNotFoundException if the GBean could not be found
224: */
225: int getGBeanState(AbstractName name) throws GBeanNotFoundException;
226:
227: int getGBeanState(String shortName) throws GBeanNotFoundException;
228:
229: int getGBeanState(Class type) throws GBeanNotFoundException;
230:
231: int getGBeanState(String shortName, Class type)
232: throws GBeanNotFoundException;
233:
234: /**
235: * Gets the time the specified GBean was started
236: * @param name the name of the GBean
237: * @return the start time of the GBean or 0 if not running
238: * @throws GBeanNotFoundException if the GBean could not be found
239: */
240: long getGBeanStartTime(AbstractName name)
241: throws GBeanNotFoundException;
242:
243: long getGBeanStartTime(String shortName)
244: throws GBeanNotFoundException;
245:
246: long getGBeanStartTime(Class type) throws GBeanNotFoundException;
247:
248: long getGBeanStartTime(String shortName, Class type)
249: throws GBeanNotFoundException;
250:
251: /**
252: * Gets the ClassLoader used to register the specified GBean
253: * @param name the name of the gbean from which the class loader should be extracted
254: * @return the class loader associated with the specified GBean
255: * @throws GBeanNotFoundException if the specified GBean is not registered with the kernel
256: */
257: ClassLoader getClassLoaderFor(AbstractName name)
258: throws GBeanNotFoundException;
259:
260: ClassLoader getClassLoaderFor(String shortName)
261: throws GBeanNotFoundException;
262:
263: ClassLoader getClassLoaderFor(Class type)
264: throws GBeanNotFoundException;
265:
266: ClassLoader getClassLoaderFor(String shortName, Class type)
267: throws GBeanNotFoundException;
268:
269: /**
270: * Return the GBeanInfo for a registered GBean instance.
271: * @param name the name of the GBean whose info should be returned
272: * @return the info for that instance
273: * @throws GBeanNotFoundException if there is no instance with the supplied name
274: */
275: GBeanInfo getGBeanInfo(AbstractName name)
276: throws GBeanNotFoundException;
277:
278: GBeanInfo getGBeanInfo(String shortName)
279: throws GBeanNotFoundException;
280:
281: GBeanInfo getGBeanInfo(Class type) throws GBeanNotFoundException;
282:
283: GBeanInfo getGBeanInfo(String shortName, Class type)
284: throws GBeanNotFoundException;
285:
286: /**
287: * Return the GBeanData for a GBean instance.
288: * @param name the name of the GBean whose info should be returned
289: * @return the info for that instance
290: * @throws GBeanNotFoundException if there is no instance with the supplied name
291: */
292: GBeanData getGBeanData(AbstractName name)
293: throws GBeanNotFoundException, InternalKernelException;
294:
295: GBeanData getGBeanData(String shortName)
296: throws GBeanNotFoundException, InternalKernelException;
297:
298: GBeanData getGBeanData(Class type) throws GBeanNotFoundException,
299: InternalKernelException;
300:
301: GBeanData getGBeanData(String shortName, Class type)
302: throws GBeanNotFoundException, InternalKernelException;
303:
304: /**
305: * Gets the AbstractNames of all GBeans matching the abstractNameQuery.
306: * @param abstractNameQuery the query to execute
307: * @return the AbstractNames of all matching GBeans
308: */
309: Set listGBeans(AbstractNameQuery abstractNameQuery);
310:
311: /**
312: * Returns a Set of all GBeans matching the set of object name pattern
313: * @param abstractNameQueries the queries to execute
314: * @return a List of AbstractNameName of matching GBeans registered with this kernel
315: */
316: Set listGBeans(Set abstractNameQueries);
317:
318: /**
319: * Gets the value of an attribute on the specified gbean
320: * @param name the name of the gbean from which the attribute will be retrieved
321: * @param attributeName the name of the attribute to fetch
322: * @return the value of the attribute
323: * @throws GBeanNotFoundException if there is not a gbean under the specified name
324: * @throws NoSuchAttributeException if the gbean does not contain the specified attribute
325: * @throws Exception if the gbean throws an exception from the getter
326: */
327: Object getAttribute(AbstractName name, String attributeName)
328: throws GBeanNotFoundException, NoSuchAttributeException,
329: Exception;
330:
331: Object getAttribute(String shortName, String attributeName)
332: throws GBeanNotFoundException, NoSuchAttributeException,
333: Exception;
334:
335: Object getAttribute(Class type, String attributeName)
336: throws GBeanNotFoundException, NoSuchAttributeException,
337: Exception;
338:
339: Object getAttribute(String shortName, Class type,
340: String attributeName) throws GBeanNotFoundException,
341: NoSuchAttributeException, Exception;
342:
343: /**
344: * Sets the value of an attribute on the specified gbean
345: * @param name the name of the gbean from in which the new attribute value will be set
346: * @param attributeName the name of the attribute to set
347: * @param attributeValue the new value of the attribute
348: * @throws GBeanNotFoundException if there is not a gbean under the specified name
349: * @throws NoSuchAttributeException if the gbean does not contain the specified attribute
350: * @throws Exception if the gbean throws an exception from the setter
351: */
352: void setAttribute(AbstractName name, String attributeName,
353: Object attributeValue) throws GBeanNotFoundException,
354: NoSuchAttributeException, Exception;
355:
356: void setAttribute(String shortName, String attributeName,
357: Object attributeValue) throws GBeanNotFoundException,
358: NoSuchAttributeException, Exception;
359:
360: void setAttribute(Class type, String attributeName,
361: Object attributeValue) throws GBeanNotFoundException,
362: NoSuchAttributeException, Exception;
363:
364: void setAttribute(String shortName, Class type,
365: String attributeName, Object attributeValue)
366: throws GBeanNotFoundException, NoSuchAttributeException,
367: Exception;
368:
369: /**
370: * Invokes a no-argument method on the specified GBean
371: * @param name the name of the gbean from in which the new attribute value will be set
372: * @param methodName the name of the method to invoke
373: * @return the return value of the method or null if the specified method does not return a value
374: * @throws GBeanNotFoundException if there is not a gbean under the specified name
375: * @throws NoSuchOperationException if the gbean does not have the specified operation
376: * @throws InternalKernelException if an error occurs within the kernel itself
377: * @throws Exception if the method throws an exception
378: */
379: Object invoke(AbstractName name, String methodName)
380: throws GBeanNotFoundException, NoSuchOperationException,
381: InternalKernelException, Exception;
382:
383: Object invoke(String shortName, String methodName)
384: throws GBeanNotFoundException, NoSuchOperationException,
385: InternalKernelException, Exception;
386:
387: Object invoke(Class type, String methodName)
388: throws GBeanNotFoundException, NoSuchOperationException,
389: InternalKernelException, Exception;
390:
391: Object invoke(String shortName, Class type, String methodName)
392: throws GBeanNotFoundException, NoSuchOperationException,
393: InternalKernelException, Exception;
394:
395: /**
396: * Invokes a method on the specified GBean with the specified arguments
397: * @param name the name of the gbean from in which the new attribute value will be set
398: * @param methodName the name of the method to invoke
399: * @param args the arguments to pass to the method
400: * @param types the types of the arguments; the types are used to determine the signature of the mehod that should be invoked
401: * @return the return value of the method or null if the specified method does not return a value
402: * @throws GBeanNotFoundException if there is not a gbean under the specified name
403: * @throws NoSuchOperationException if the gbean does not have the specified operation
404: * @throws InternalKernelException if an error occurs within the kernel itself
405: * @throws Exception if the method throws an exception
406: */
407: Object invoke(AbstractName name, String methodName, Object[] args,
408: String[] types) throws GBeanNotFoundException,
409: NoSuchOperationException, InternalKernelException,
410: Exception;
411:
412: Object invoke(String shortName, String methodName, Object[] args,
413: String[] types) throws GBeanNotFoundException,
414: NoSuchOperationException, InternalKernelException,
415: Exception;
416:
417: Object invoke(Class type, String methodName, Object[] args,
418: String[] types) throws GBeanNotFoundException,
419: NoSuchOperationException, InternalKernelException,
420: Exception;
421:
422: Object invoke(String shortName, Class type, String methodName,
423: Object[] args, String[] types)
424: throws GBeanNotFoundException, NoSuchOperationException,
425: InternalKernelException, Exception;
426:
427: /**
428: * Assuming the argument represents a service running in the kernel,
429: * returns an AbstractName for it. If the argument is not a service or the
430: * kernel cannot produce an AbstractName for it, returns null.
431: */
432: AbstractName getAbstractNameFor(Object service);
433:
434: /**
435: * Assuming the argument represents a service running in the kernel,
436: * returns the short name of the service. If the argument is not a service, returns null.
437: */
438: String getShortNameFor(Object service);
439:
440: /**
441: * Brings the kernel online
442: * @throws Exception if the kernel can not boot
443: */
444: void boot() throws Exception;
445:
446: /**
447: * Returns the time this kernel was last booted.
448: * @return the time this kernel was last booted; null if the kernel has not been
449: */
450: Date getBootTime();
451:
452: /**
453: * Registers a runnable to execute when the kernel is shutdown
454: * @param hook a runnable to execute when the kernel is shutdown
455: */
456: void registerShutdownHook(Runnable hook);
457:
458: /**
459: * Unregisters a runnable from the list to execute when the kernel is shutdown
460: * @param hook the runnable that should be removed
461: */
462: void unregisterShutdownHook(Runnable hook);
463:
464: /**
465: * Stops the kernel
466: */
467: void shutdown();
468:
469: /**
470: * Has the kernel been booted
471: * @return true if the kernel has been booted; false otherwise
472: */
473: boolean isRunning();
474:
475: /**
476: * @deprecated Use AbstractName version instead
477: */
478: Object getGBean(ObjectName name) throws GBeanNotFoundException,
479: InternalKernelException, IllegalStateException;
480:
481: /**
482: * @deprecated Use AbstractName version instead
483: */
484: int getGBeanState(ObjectName name) throws GBeanNotFoundException;
485:
486: /**
487: * @deprecated Use AbstractName version instead
488: */
489: GBeanInfo getGBeanInfo(ObjectName name)
490: throws GBeanNotFoundException;
491:
492: /**
493: * Returns a Set with elements of type ObjectName
494: *
495: * @deprecated Use AbstractNameQuery version instead
496: */
497: Set listGBeans(ObjectName pattern);
498:
499: /**
500: * @deprecated Use AbstractName version instead
501: */
502: Object getAttribute(ObjectName name, String attributeName)
503: throws GBeanNotFoundException, NoSuchAttributeException,
504: Exception;
505:
506: /**
507: * @deprecated Use AbstractName version instead
508: */
509: Object invoke(ObjectName name, String methodName)
510: throws GBeanNotFoundException, NoSuchOperationException,
511: InternalKernelException, Exception;
512:
513: /**
514: * @deprecated Use AbstractName version instead
515: */
516: Object invoke(ObjectName name, String methodName, Object[] args,
517: String[] types) throws GBeanNotFoundException,
518: NoSuchOperationException, InternalKernelException,
519: Exception;
520:
521: String getStateReason(AbstractName abstractName);
522: }
|