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.cougaar.core.component.Service;
030: import org.cougaar.core.mts.MessageAddress;
031: import org.cougaar.core.service.community.Community;
032:
033: public interface YPService extends Service {
034: /** Get a Proxy for YP Queries from a specific YPServer. Typically, you would
035: * invoke a method on the returned YPProxy, publish the resulting YPFuture to the
036: * blackboard, and wait until the future has been publishChanged to get the value.
037: * @param ypAgent The name of the agent running the YPServer - used to construct
038: * a MessageAddress.
039: * @note The YP resolver will NOT look beyond the specified agent.
040: * @deprecated
041: **/
042: YPProxy getYP(String ypAgent);
043:
044: /** Get a Proxy for YP Queries from a specific YPServer. Typically, you would
045: * invoke a method on the returned YPProxy, publish the resulting YPFuture to the
046: * blackboard, and wait until the future has been publishChanged to get the value.
047: * @param ypAgent MessageAddress of the agent running the YPServer.
048: * @note The YP resolver will NOT look beyond the specified agent.
049: **/
050: YPProxy getYP(MessageAddress ypAgent);
051:
052: /** Get a Proxy for YP Queries in a specific community context. Typically, you
053: * would invoke a method on the returned YPProxy, publish the resulting
054: * YPFuture to the blackboard, and wait until the future has been
055: * publishChanged to get the value.
056: * @param community Initial community for all YP interactions
057: * @note The YP resolver will use the community hierarchy to resolve queries
058: * which have no match in the initial commununity.
059: **/
060: YPProxy getYP(Community community);
061:
062: /** Get a Proxy for YP Queries in a specific community context. Typically, you
063: * would invoke a method on the returned YPProxy, publish the resulting
064: * YPFuture to the blackboard, and wait until the future has been
065: * publishChanged to get the value.
066: * @param community Initial community for all YP interactions
067: * @param searchMode Defines who/whether the YP resolver will use the
068: * community hierarchy to resolve queries which have no match in the
069: * initial commununity.
070: * @note searchMode should be one of values defined by YPProxy.SearchMode
071: **/
072: YPProxy getYP(Community community, int searchMode);
073:
074: /** Get a Proxy for YP Queries in the default community context - i.e.
075: * starting with the lowest level YPCommunity for which the agent is
076: * a member. Typically, you
077: * would invoke a method on the returned YPProxy, publish the resulting
078: * YPFuture to the blackboard, and wait until the future has been
079: * publishChanged to get the value.
080: * @note The YP resolver will use the community hierarchy to resolve queries
081: * which have no match in the initial commununity.
082: **/
083: YPProxy getYP();
084:
085: /** Get a Proxy for YP Queries in the default community context - i.e.
086: * starting with the lowest level YPCommunity for which the agent is
087: * a member. Typically, you
088: * would invoke a method on the returned YPProxy, publish the resulting
089: * YPFuture to the blackboard, and wait until the future has been
090: * publishChanged to get the value.
091: * @param searchMode Defines who/whether the YP resolver will use the
092: * community hierarchy to resolve queries which have no match in the
093: * local commununity.
094: * @note searchMode should be one of values defined by YPProxy.SearchMode
095: **/
096: YPProxy getYP(int searchMode);
097:
098: /** List #getYP(String), except submits the request before returning the
099: * YPFuture value. This is a convenient mechanism if you do not have access
100: * to a blackboard for blackboard-based publish/subscribe of YPFuture requests.
101: * Keep in mind that the YPFuture values returned are still <em>futures</em>, e.g. a call to get()
102: * will block until the answer has been received.
103: * @param ypAgent The name of the agent running the YPServer - used to construct
104: * a MessageAddress.
105: * @note The YP resolver will NOT look beyond the specified agent.
106: * @note Access to this method is likely to be more tightly constrained by security
107: * mechanisms, as it is easier to write broken code using this mechanism.
108: * @deprecated
109: */
110: YPProxy getAutoYP(String ypAgent);
111:
112: /** List #getYP(String), except submits the request before returning the
113: * YPFuture value. This is a convenient mechanism if you do not have access
114: * to a blackboard for blackboard-based publish/subscribe of YPFuture requests.
115: * Keep in mind that the YPFuture values returned are still <em>futures</em>, e.g. a call to get()
116: * will block until the answer has been recieved.
117: * @param ypAgent MessageAddress of the agent running the YPServer
118: * @note The YP resolver will NOT look beyond the specified agent.
119: * @note Access to this method is likely to be more tightly constrained by security
120: * mechanisms, as it is easier to write broken code using this mechanism.
121: */
122: YPProxy getAutoYP(MessageAddress ypAgent);
123:
124: /** List #getYP(String), except submits the request before returning the
125: * YPFuture value. This is a convenient mechanism if you do not have access
126: * to a blackboard for blackboard-based publish/subscribe of YPFuture requests.
127: * Keep in mind that the YPFuture values returned are still <em>futures</em>, e.g. a call to get()
128: * will block until the answer has been recieved.
129: * @param community Initial community for all YP interactions
130: * @note The YP resolver will use the community hierarchy to resolve queries
131: * which have no match in the initial commununity.
132:
133: * @note Access to this method is likely to be more tightly constrained by security
134: * mechanisms, as it is easier to write broken code using this mechanism.
135: */
136: YPProxy getAutoYP(Community community);
137:
138: /** Submit a YPFuture to be transmitted.
139: * @note This method is only for use by clients which can afford to block their thread -
140: * most clients with blackboard access should publish/subscribe the YPFuture instead.
141: * @return argument for convenience.
142: **/
143: YPFuture submit(YPFuture ypr);
144:
145: /** Find the YP server context for a given agent.
146: * @param AgentName name of the agent
147: * @param callback callback.invoke(Object) called with the YP server
148: * context for the specified agent.
149: * Next context will be null if there is YP server contex for the specified agent
150: * @note callback.invoke may be called from within nextYPServerContext
151: **/
152: public void getYPServerContext(final String AgentName,
153: final NextContextCallback callback);
154:
155: /** Find the next context to search.
156: * @param currentContext current YP context
157: * @param callback callback.invoke(Object) called with the next context.
158: * Next context will be null if there is no next context.
159: * @note callback.invoke may be called from within nextYPServerContext
160: **/
161: public void nextYPServerContext(final Object currentContext,
162: final NextContextCallback callback);
163:
164: /** Invoked when the next YP context has been resolved
165: **/
166: interface NextContextCallback {
167: void setNextContext(Object context);
168: }
169:
170: }
|