001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 Mobile Intelligence Corp
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.core.service.community;
028:
029: import java.util.Collection;
030:
031: import javax.naming.directory.Attributes;
032: import javax.naming.directory.ModificationItem;
033:
034: import org.cougaar.core.component.Service;
035:
036: /**
037: * This service provides access to community capabilities.
038: * <p>
039: * Most operations are performed asynchronously in which case a
040: * callback is used to return status and results. In addition to
041: * the asynchronous callback, the getCommunity and searchCommunity
042: * methods may also return results immediately if the operation
043: * can be completed using locally cached data. In these cases the
044: * callback is not invoked. When required, callbacks are always
045: * invoked from within a blackboard transaction.
046: */
047: public interface CommunityService extends Service {
048:
049: // Entity types
050: public static final int AGENT = 0;
051: public static final int COMMUNITY = 1;
052:
053: /**
054: * Request to create a community. If the specified community does not
055: * exist it will be created and the caller will become the community
056: * manager. It the community already exists a descriptor is obtained
057: * from its community manager and returned in the response.
058: * @param communityName Name of community to create
059: * @param attrs Attributes to associate with new community
060: * @param crl Listener to receive response
061: * @deprecated Use joinCommunity method with createIfNotFound argument
062: * set to true
063: */
064: void createCommunity(String communityName, Attributes attrs,
065: CommunityResponseListener crl);
066:
067: /**
068: * Request to join a named community. If the specified community does not
069: * exist it may be created in which case the caller becomes the community
070: * manager. It the community doesn't exist and the caller has set the
071: * "createIfNotFound flag to false the join request will be queued until the
072: * community is found.
073: * @param communityName Community to join
074: * @param entityName New member name
075: * @param entityType Type of member entity to create (AGENT or COMMUNITY)
076: * @param entityAttrs Attributes for new member
077: * @param createIfNotFound Create community if it doesn't exist
078: * @param newCommunityAttrs Attributes for created community (used if
079: * createIfNotFound set to true, otherwise ignored)
080: * @param crl Listener to receive response
081: */
082: void joinCommunity(String communityName, String entityName,
083: int entityType, Attributes entityAttrs,
084: boolean createIfNotFound, Attributes newCommunityAttrs,
085: CommunityResponseListener crl);
086:
087: /**
088: * Request to leave named community.
089: * @param communityName Community to leave
090: * @param entityName Entity to remove from community
091: * @param crl Listener to receive response
092: */
093: void leaveCommunity(String communityName, String entityName,
094: CommunityResponseListener crl);
095:
096: /**
097: * Request to get a Community object. If community is found in local cache
098: * a reference is returned by method call. If the community
099: * is not found in the cache a null value is returned and the Community
100: * object is requested from community's manager. After the Community
101: * object has been obtained from the community manager the supplied
102: * CommunityResponseListener callback is invoked to notify the requester.
103: * Note that the supplied callback is not invoked if a non-null value is
104: * returned.
105: * @param communityName Community of interest
106: * @param crl Listener to receive response after remote fetch
107: * @return Community instance if found in cache or null if not
108: * found
109: */
110: Community getCommunity(String communityName,
111: CommunityResponseListener crl);
112:
113: /**
114: * Request to modify an Entity's attributes.
115: * @param communityName Name of community
116: * @param entityName Name of affected Entity or null if modifying
117: * community attributes
118: * @param mods Attribute modifications
119: * @param crl Listener to receive response
120: */
121: void modifyAttributes(String communityName, String entityName,
122: ModificationItem[] mods, CommunityResponseListener crl);
123:
124: /**
125: * Initiates a community search operation. The serach is performed against
126: * the specified community or all communities of the calling agent
127: * if the communityName argument is null. The results of the search are
128: * immediately returned as part of the method call if the search can be
129: * resolved using locally cached data. However, if the search requires
130: * interaction with a remote community manager a null value is returned by
131: * the method call and the search results are returned via the
132: * CommunityResponseListener callback after the remote operation has been
133: * completed. In the case where the search can be satisified using local
134: * data (i.e., the method returns a non-null value) the
135: * CommunityResponseListener is not invoked.
136: * @param communityName Name of community to search or null to globally
137: * search parent communities of calling agent
138: * @param searchFilter JNDI compliant search filter
139: * @param recursiveSearch True for recursive search into nested communities
140: * [false = search top community only]
141: * @param resultQualifier Type of entities to return in result [ALL_ENTITIES,
142: * AGENTS_ONLY, or COMMUNITIES_ONLY]
143: * @param crl Callback object to receive search results
144: * @return Collection of Entity objects matching search
145: * criteria if available in local cache. A null value
146: * is returned if cache doesn't contained named
147: * community.
148: */
149: Collection searchCommunity(String communityName,
150: String searchFilter, boolean recursiveSearch,
151: int resultQualifier, CommunityResponseListener crl);
152:
153: /**
154: * Performs attribute based search of community entities. This is a general
155: * purpose search operation using a JNDI search filter. This method is
156: * non-blocking. An empty Collection will be returned if the local cache is
157: * empty. Updated search results can be obtained by using the addListener
158: * method to receive change notifications.
159: * @param communityName Name of community to search
160: * @param filter JNDI search filter
161: * @return Collection of MessageAddress objects
162: */
163: Collection search(String communityName, String filter);
164:
165: /**
166: * Requests a collection of community names identifying the communities that
167: * contain the specified member. If the member name is null the immediate
168: * parent communities for calling agent are returned. If member is
169: * the name of a nested community the names of all immediate parent communities
170: * is returned. The results are returned directly if the member name is
171: * null or if a copy of the specified community is available in local cache.
172: * Otherwise, the results will be returned in the CommunityResponseListener
173: * callback in which case the method returns a null value.
174: * @param member Member name
175: * @param crl Listener to receive results if remote lookup is required
176: * @return A collection of community names if operation can be resolved using
177: * data from local cache, otherwise null
178: */
179: Collection listParentCommunities(String member,
180: CommunityResponseListener crl);
181:
182: /**
183: * Requests a collection of community names identifying the communities that
184: * contain the specified member and satisfy a given set of attributes.
185: * The results are returned directly if the member name is
186: * null or if a copy of the specified community is available in local cache.
187: * Otherwise, the results will be returned in the CommunityResponseListener
188: * callback in which case the method returns a null value.
189: * @param member Member name
190: * @param filter Search filter defining community attributes
191: * @param crl Listener to receive results
192: * @return A collection of community names if operation can be resolved using
193: * data from local cache, otherwise null
194: */
195: Collection listParentCommunities(String member, String filter,
196: CommunityResponseListener crl);
197:
198: /**
199: * Invokes callback when specified community is found.
200: * @param communityName Name of community
201: * @param fccb Callback invoked after community is found or timeout
202: * has lapsed
203: * @param timeout Length of time (in milliseconds) to wait for
204: * community to be located. A value of -1 disables
205: * the timeout.
206: */
207: void findCommunity(String communityName,
208: FindCommunityCallback fccb, long timeout);
209:
210: /**
211: * Lists all communities in bound in White Pages. Results are returned
212: * in CommunityResponseListener callback. The crl.getContent() method
213: * returns a Collection of community names found in white pages.
214: */
215: void listAllCommunities(CommunityResponseListener crl);
216:
217: /**
218: * Add listener for CommunityChangeEvents.
219: * @param l Listener
220: */
221: void addListener(CommunityChangeListener l);
222:
223: /**
224: * Remove listener for CommunityChangeEvents.
225: * @param l Listener
226: */
227: void removeListener(CommunityChangeListener l);
228:
229: /**
230: * Returns an array of community names of all communities of which caller is
231: * a member.
232: * @param allLevels Set to false if the list should contain only those
233: * communities in which the caller is explicitly
234: * referenced. If true the list will also include those
235: * communities in which the caller is implicitly a member
236: * as a result of community nesting.
237: * @return Array of community names
238: * @deprecated This method will be removed in 11.2.
239: * @see #listParentCommunities(String, CommunityResponseListener)
240: */
241: String[] getParentCommunities(boolean allLevels);
242:
243: /**
244: * Lists all communities in Name Server.
245: * @return Collection of community names
246: * @deprecated This method will be removed in 11.2.
247: * @see #listAllCommunities(CommunityResponseListener)
248: */
249: Collection listAllCommunities();
250:
251: /**
252: * Requests a collection of community names identifying the communities that
253: * contain the specified member.
254: * @param member Member name
255: * @return A collection of community names
256: * @deprecated This method will be removed in 11.2.
257: * @see #listParentCommunities(String, CommunityResponseListener)
258: */
259: Collection listParentCommunities(String member);
260:
261: /**
262: * Requests a collection of community names identifying the communities that
263: * contain the specified member and satisfy a given set of attributes.
264: * @param member Member name
265: * @param filter Search filter defining community attributes
266: * @return A collection of community names
267: * @deprecated This method will be removed in 11.2.
268: * @see #listParentCommunities(String, String, CommunityResponseListener)
269: */
270: Collection listParentCommunities(String member, String filter);
271:
272: }
|