Source code: com/fetish/directory/Directory.java
1 package com.fetish.directory;
2
3 import java.rmi.MarshalledObject;
4 import java.rmi.Remote;
5
6 import net.jini.core.lookup.*;
7 import net.jini.core.event.EventRegistration;
8 import net.jini.core.event.RemoteEventListener;
9 import net.jini.core.entry.Entry;
10 import net.jini.lookup.ServiceItemFilter;
11
12 /**
13 * Interface with the methods that a Fetish member can invoke on the
14 * Directory.
15 */
16
17 public interface Directory extends Remote {
18
19 /**
20 * Returns at most maxMatches items matching the template, plus the total
21 * number of items that match the template. The return value is never
22 * null, and the returned items array is only null if maxMatches is zero.
23 * For each returned item, if the service object cannot be deserialized,
24 * the service field of the item is set to null and no exception is
25 * thrown. Similarly, if an attribute set cannot be deserialized, that
26 * element of the attributeSets array is set to null and no exception
27 * is thrown.
28 *
29 * @param service interface to match
30 * @param entries template specifying the valid values searched for
31 * @param id identifier of the searched service implementation
32 * @param filter filter to restrict the returned objects
33 * @param maxMatches maximum number of matches to return
34 * @return a ServiceMatches instance that contains at most maxMatches
35 * items matching the template, plus the total number of items
36 * that match the template. The return value is never null, and
37 * the returned items array is only null if maxMatches is zero.
38 * @throws java.rmi.RemoteException
39 */
40 // Canviat FetishServiceId per ServiceID
41
42 public ServiceMatches lookup( SearchCriteriaInterface criteria,
43 int nHops,
44 long timeout,
45 int maxResponses ) throws java.rmi.RemoteException;
46
47 /**
48 * Extends the lookup process to all nodes connected to one
49 * (except that from which the lookup request came from). Takes account
50 * of the search id, to avoid cycles. If the search request has an id
51 * that is already in the list of search ids, the request is rejected,
52 * and the call returns inmediately.
53 * @param criteria The criteria the Jini lookup will take in account
54 * @param searchID The search id of the lookup. It will be stored to avoid
55 * cycles in the lookup (transitive cycles).
56 * @param target The node that started the lookup process. It will be
57 * notified of all service matches found in this node and those nodes
58 * searched by this one within the lookup expansion mechanism.
59 * @param excluded The node that extends the lookup process to this one. The
60 * expansion won't go back to that node to avoid direct lookup cycles.
61 * @param nHops Maximum number of times a lookup will hop from a node to
62 * another. This will limit the lookup process to a fixed radius.
63 * @param timeout Maximum allowed time for the lookup, expressed in
64 * milliseconds.
65 */
66 public boolean lookup( SearchCriteriaInterface criteria,
67 SearchIDInterface searchID,
68 String target,
69 String excluded,
70 int nHops,
71 long timeout,
72 int maxResponses ) throws java.rmi.RemoteException;
73
74
75 /**
76 * Adds results obtained from a remote FADA.
77 * This method is called from a FADA node that wants to return the results
78 * of a local search to a FADA node that has asked for them.
79 * @param id The SearchIDInterface that identifies the lookup process in
80 * this FADA node
81 * @param sm The ServiceMatches object that contains the remote results.
82 * @throws java.rmi.RemoteException
83 */
84 public void addLookupResult( SearchIDInterface id, ServiceMatches sm )
85 throws java.rmi.RemoteException;
86
87 /**
88 * Increases the number of started searches.
89 * Adds numSearches to the number of searches to expect results from.
90 * <em>THIS METHOD IS ACTUALLY NOT BEING USED</em>
91 * @param id The SearchIDInterface that identifies the lookup process in
92 * this FADA node
93 * @param numSearches The amount of searches started from a remote node.
94 * @throws java.rmi.RemoteException;
95 */
96 public void startedSearches( SearchIDInterface id, int numSearches )
97 throws java.rmi.RemoteException;
98
99 /**
100 * Returns all services registered in this Fada node.
101 */
102 public ServiceMatches getServices() throws java.rmi.RemoteException;
103
104 /**
105 * <Copy & Paste from the JINI API register method>
106 * Register a new service or re-register an existing service. The method
107 * is defined so that it can be used in an idempotent fashion.
108 * Specifically, if a call to register results in a RemoteException (in
109 * which case the item might or might not have been registered), the
110 * caller can simply repeat the call to register with the same parameters,
111 * until it succeeds.
112 * <p>
113 * To register a new service, item.serviceID should be null. In that
114 * case, if item.service does not equal (using MarshalledObject.equals)
115 * any existing item's service object, then a new service ID will be
116 * assigned and included in the returned ServiceRegistration. The
117 * service ID is unique over time and space with respect to all other
118 * service IDs generated by all lookup services. If item.service does
119 * equal an existing item's service object, the existing item is first
120 * deleted from the lookup service (even if it has different attributes)
121 * and its lease is cancelled, but that item's service ID is reused for
122 * the newly registered item.
123 * <p>
124 * To re-register an existing service, or to register the service in any
125 * other lookup service, item.serviceID should be set to the same service
126 * ID that was returned by the initial registration. If an item is
127 * already registered under the same service ID, the existing item is
128 * first deleted (even if it has different attributes or a different
129 * service instance) and its lease is cancelled. Note that service
130 * object equality is not checked in this case, to allow for reasonable
131 * evolution of the service (e.g., the serialized form of the stub
132 * changes, or the service implements a new interface).
133 * <p>
134 * Any duplicate attribute sets included in a service item are eliminated
135 * in the stored representation of the item. The lease duration request
136 * is not exact; the returned lease is allowed to have a shorter (but not
137 * longer) duration than what was requested.
138 *
139 * @param item service item to register
140 * @param leaseDuration requested lease duration
141 * @return a ServiceRegistration in this lookup service for the specified
142 * service item
143 * @throws java.rmi.RemoteException
144 */
145
146 public ServiceRegistration register( ServiceItem item,
147 long leaseDuration) throws java.rmi.RemoteException;
148
149 /**
150 * Deletes a registration from the node.
151 *
152 * @param sid The <b>ServiceID</b> provided at registration time.
153 * @throws java.rmi.RemoteException
154 */
155 public void unregister( ServiceID sid ) throws java.rmi.RemoteException;
156
157 /*
158 * Registers for event notification. The registration is leased; the
159 * lease expiration request is not exact. The registration is persistent
160 * across restarts (crashes) of the lookup service until the lease expires
161 * or is cancelled. The event ID in the returned EventRegistration is
162 * unique at least with respect to all other active event registrations
163 * in this lookup service with different service templates or transitions.
164 * <p>
165 * While the event registration is in effect, a ServiceEvent is sent to
166 * the specified listener whenever a register, lease cancellation or
167 * expiration, or attribute change operation results in an item changing
168 * state in a way that satisfies the template and transition combination.
169 *
170 * @param tmpl template to match
171 * @param transitions bitwise OR of any non-empty set of transition values
172 * @param listener listener to send events to
173 * @param handback object to include in every ServiceEvent generated
174 * @param leaseDuration requested lease duration
175 * @return an EventRegistration object to the entity that registered the
176 * specified remote listener
177 * @throws java.rmi.RemoteException
178 *
179
180 public EventRegistration notify( ServiceTemplate tmpl,
181 int transitions,
182 RemoteEventListener listener,
183 MarshalledObject handback,
184 long leaseDuration ) throws java.rmi.RemoteException;
185 */
186
187 }