01: /*
02: * <copyright>
03: *
04: * Copyright 2000-2004 BBNT Solutions, LLC
05: * under sponsorship of the Defense Advanced Research Projects
06: * Agency (DARPA).
07: *
08: * You can redistribute this software and/or modify it under the
09: * terms of the Cougaar Open Source License as published on the
10: * Cougaar Open Source Website (www.cougaar.org).
11: *
12: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
13: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
14: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
15: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
16: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
17: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
18: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
19: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
20: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
22: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23: *
24: * </copyright>
25: */
26: package org.cougaar.core.component;
27:
28: import java.util.Iterator;
29:
30: /** Cougaar component Service Broker.
31: * Note that this was previously called Services in deference to
32: * the analogous BeanContextServices object.
33: *
34: * @see java.beans.beancontext.BeanContextServices
35: **/
36: public interface ServiceBroker {
37: /** Add a ServiceListener to this Services Context. **/
38: void addServiceListener(ServiceListener sl);
39:
40: /** Remove a services listener. **/
41: void removeServiceListener(ServiceListener sl);
42:
43: /** Add a Service to this Services Context.
44: * @return true IFF successful and not redundant.
45: **/
46: boolean addService(Class<?> serviceClass,
47: ServiceProvider serviceProvider);
48:
49: /** Remoke or remove an existing service **/
50: void revokeService(Class<?> serviceClass,
51: ServiceProvider serviceProvider);
52:
53: /** Is the service currently available? **/
54: boolean hasService(Class<?> serviceClass);
55:
56: /** Gets the currently available services for this context.
57: * All standard implementations return an Iterator over a copy of the set of ServiceClasses
58: * so that there is no risk of ComodificationException.
59: **/
60: Iterator<Class<?>> getCurrentServiceClasses();
61:
62: /** get an instance of the requested service from a service provider associated
63: * with this context.
64: * May return null (if no provider found) and various RuntimeExceptions may be
65: * thrown by the associated ServiceProvider. The ServiceBroker itself may
66: * throw ClassCastException if the ServiceProvider returns a non-null
67: * service object which is not an instance of the requested serviceClass.
68: * <p>
69: * Note that a successful call to getService almost always implies memory allocation,
70: * often not garbage-collectable, due to internal references.
71: * @note It is always a
72: * good idea to pair getService and releaseService calls.
73: **/
74: <T> T getService(Object requestor, Class<T> serviceClass,
75: ServiceRevokedListener srl);
76:
77: /** Release a service object previously requested by a call to getService.
78: * Service object instances usually require significant non-GCable memory, so
79: * must be released to reclaim the memory and/or the associated resources.
80: * @note It is always a
81: * good idea to pair getService and releaseService calls.
82: */
83: <T> void releaseService(Object requestor, Class<T> serviceClass,
84: T service);
85: }
|