001: /*
002: * <copyright>
003: *
004: * Copyright 2002-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:
027: package org.cougaar.yp;
028:
029: import org.uddi4j.UDDIException;
030: import org.w3c.dom.Element;
031:
032: // we could base the implementation on concurrent.FutureResult
033:
034: /** An outstanding YP response object, returned from all of the YPProxy
035: * methods.
036: * A consumer of the YP information would issue a query, then
037: * watch the returned YPFuture object until
038: * isReady returns true.
039: */
040:
041: public interface YPFuture {
042: /** Indicate when a response has been recieved (or a failure indicated).
043: * If true, then the get methods will return immediately.
044: **/
045: boolean isReady();
046:
047: /** gets the response value as an object, blocking if need be.
048: * @note implemented as get(0L);
049: **/
050: Object get() throws UDDIException;
051:
052: /** gets the response value as an object, blocking if need be for up to the
053: * specified millis.
054: * If still not ready at the end, will return null, e.g. if finished due to
055: * timeout or thread interruption.
056: * May also throw a runtimeException if the query returns an exception.
057: * The actual exception is the value of getCause of the RuntimeException thrown.
058: * If msecs is specified as 0 then it will wait forever.
059: **/
060: Object get(long msecs) throws UDDIException;
061:
062: // Consider casted getters, e.g. DispositionReport getDispositionReport()
063:
064: /** Clients may set a callback here to be invoked when
065: * the response is ready. Most clients will use the Blackboard
066: * interation pattern and look for publishChange events rather
067: * than registering for explicit callbacks.
068: * Only Callback and Callable instances are actually accepted.<p>
069: * Callers are <em>STRONGLY</em> encouraged to use OneShotMachine
070: * instead of direct callbacks if the callback requires significant
071: * processing or if there is a chance that the callback will block.
072: * @note If the response is already ready, then the callback
073: * will be invoked immediately in the thread of the caller.
074: * @note Only one Callback may be attached.
075: **/
076: void setCallback(YPComplete callable);
077:
078: /** Access the XML element describing the query **/
079: Element getElement();
080:
081: /** Is the message a query? **/
082: boolean isInquiry();
083:
084: /** In which context was this query issued
085: * @return Object is either a MessageAddress or a Community.
086: * @note If the context is a Community the YP resolver will use the community
087: * hierarchy to resolve queries which have no match in the initial context. No
088: * such search occurs if the initial context is a MessageAddress.
089: **/
090: Object getInitialContext();
091:
092: /** In which context was this query resolved
093: * @return Object is either a MessageAddress or a Community
094: **/
095: Object getFinalContext();
096:
097: /** Search mode to be used in resolving this query.
098: * @return int is one of the values defined by YPProxy.SearchMode
099: **/
100: int getSearchMode();
101:
102: /** The interface which must be implemented by the argument to #setCallback(Callback) **/
103: interface YPComplete {
104: }
105:
106: /** Event notification Callback, invoked when there is an answer in the YPFuture **/
107: interface Callback extends YPComplete {
108: /** The result posting mechanism will invoke this method as soon as #isReady() will return
109: * true.
110: **/
111: void ready(YPFuture response);
112: }
113:
114: /** Higher-level callback abstraction. Similar to Callback but passes in the results rather that
115: * just notification of interaction completeness events.
116: * @note The interface assumes that all important information is closed over by the instance.
117: **/
118: interface ResponseCallback extends YPComplete {
119: void invoke(Object result);
120:
121: void handle(Exception e);
122: }
123: }
|