001: /*
002: * <copyright>
003: *
004: * Copyright 2000-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026: package org.cougaar.core.component;
027:
028: /**
029: * A {@link ServiceBroker} with extended methods to support the
030: * {@link ViewService}.
031: * <p>
032: * <b>Note:</b> This is an infrastructure mechanism to support the
033: * {@link ViewService}. Components should <u>not</u> expect their
034: * ServiceBroker to implement this interface, or attempt to cast to
035: * this interface! In future versions of the component model this
036: * API will likely be refactored away and/or blocked from the
037: * components.
038: * <p>
039: * This API extends the ServiceBroker "getService" to support:
040: * <ul>
041: * <li>Hide services obtained by child components from their
042: * container's view of obtained services, which would otherwise
043: * happen due to propagating service brokers. This is accomplished
044: * by setting the "recordInView" to false.</li>
045: * <li>Return not just the service result, but also the provider's
046: * unique identifier and {@link ComponentDescription}. This
047: * allows the client's {@link ViewService} monitor to record
048: * which component advertised the obtained service instance.</li>
049: * <li>Pass the requestor's ComponentDescription to future
050: * ServiceProviders, for both logging and better control than
051: * relying on the client-provided "requestor" object.</li>
052: * </ul>
053: */
054: public interface ExtendedServiceBroker extends ServiceBroker {
055:
056: boolean addService(Class serviceClass,
057: ServiceProvider serviceProvider, int providerId,
058: ComponentDescription providerDesc);
059:
060: void revokeService(Class serviceClass,
061: ServiceProvider serviceProvider, int providerId,
062: ComponentDescription providerDesc);
063:
064: ServiceResult getService(int requestorId,
065: ComponentDescription requestorDesc, Object requestor,
066: Class serviceClass, ServiceRevokedListener srl,
067: boolean recordInView);
068:
069: void releaseService(int requestorId,
070: ComponentDescription requestorDesc, Object requestor,
071: Class serviceClass, Object service, boolean recordInView);
072:
073: final class ServiceResult {
074: private final int providerId;
075: private final ComponentDescription providerDesc;
076: private final Object service;
077:
078: public ServiceResult(int providerId,
079: ComponentDescription providerDesc, Object service) {
080: this .providerId = providerId;
081: this .providerDesc = providerDesc;
082: this .service = service;
083: }
084:
085: public int getProviderId() {
086: return providerId;
087: }
088:
089: public ComponentDescription getProviderComponentDescription() {
090: return providerDesc;
091: }
092:
093: public Object getService() {
094: return service;
095: }
096:
097: public String toString() {
098: return "(service-result id=" + providerId + " desc="
099: + providerDesc + " service=" + service + ")";
100: }
101: }
102: }
|