1 /**
2 *
3 */
4 package javax.jmdns;
5
6 import java.io.Closeable;
7 import java.io.IOException;
8 import java.net.InetAddress;
9 import java.util.Map;
10 import java.util.concurrent.atomic.AtomicReference;
11
12 import javax.jmdns.impl.JmmDNSImpl;
13
14 /**
15 * <p>
16 * Java Multihomed Multicast DNS
17 * </p>
18 * Uses an underlying {@link JmDNS} instance for each {@link InetAddress} found on this computer.<br/>
19 * This class will monitor network topology changes, and will create or destroy JmDNS instances as required. It is your responsibility to maintain services registration (hint: use a {@link NetworkTopologyListener}).<br/>
20 * Most of this class methods have no notion of transaction: if an Exception is raised in the middle of execution, you may be in an incoherent state.
21 * <p>
22 * <b>Note:</b> This API is experimental and may change in the future please let us know what work and what does not work in you application.
23 * </p>
24 *
25 * @author Cédrik Lime, Pierre Frisch
26 */
27 public interface JmmDNS extends Closeable {
28
29 /**
30 * JmmDNS.Factory enable the creation of new instance of JmmDNS.
31 */
32 public static final class Factory {
33 private static volatile JmmDNS _instance;
34
35 /**
36 * This interface defines a delegate to the EOClassDescriptionRegister class to enable subclassing.
37 */
38 public static interface ClassDelegate {
39
40 /**
41 * Allows the delegate the opportunity to construct and return a different JmmDNS.
42 *
43 * @return Should return a new JmmDNS.
44 * @see #classDelegate()
45 * @see #setClassDelegate(ClassDelegate anObject)
46 */
47 public JmmDNS newJmmDNS();
48
49 }
50
51 private static final AtomicReference<ClassDelegate> _databaseClassDelegate = new AtomicReference<ClassDelegate>();
52
53 private Factory() {
54 super();
55 }
56
57 /**
58 * Assigns <code>delegate</code> as JmmDNS's class delegate. The class delegate is optional.
59 *
60 * @param delegate
61 * The object to set as JmmDNS's class delegate.
62 * @see #classDelegate()
63 * @see JmmDNS.Factory.ClassDelegate
64 */
65 public static void setClassDelegate(ClassDelegate delegate) {
66 _databaseClassDelegate.set(delegate);
67 }
68
69 /**
70 * Returns JmmDNS's class delegate.
71 *
72 * @return JmmDNS's class delegate.
73 * @see #setClassDelegate(ClassDelegate anObject)
74 * @see JmmDNS.Factory.ClassDelegate
75 */
76 public static ClassDelegate classDelegate() {
77 return _databaseClassDelegate.get();
78 }
79
80 /**
81 * Returns a new instance of JmmDNS using the class delegate if it exists.
82 *
83 * @return new instance of JmmDNS
84 */
85 protected static JmmDNS newJmmDNS() {
86 JmmDNS dns = null;
87 ClassDelegate delegate = _databaseClassDelegate.get();
88 if (delegate != null) {
89 dns = delegate.newJmmDNS();
90 }
91 return (dns != null ? dns : new JmmDNSImpl());
92 }
93
94 /**
95 * Return the instance of the Multihommed Multicast DNS.
96 *
97 * @return the JmmDNS
98 */
99 public static JmmDNS getInstance() {
100 if (_instance == null) {
101 synchronized (Factory.class) {
102 if (_instance == null) {
103 _instance = JmmDNS.Factory.newJmmDNS();
104 }
105 }
106 }
107 return _instance;
108 }
109 }
110
111 /**
112 * Return the names of the JmDNS instances.
113 *
114 * @return list of name of the JmDNS
115 * @see javax.jmdns.JmDNS#getName()
116 */
117 public abstract String[] getNames();
118
119 /**
120 * Return the list HostName associated with this JmmDNS instance.
121 *
122 * @return list of host names
123 * @see javax.jmdns.JmDNS#getHostName()
124 */
125 public abstract String[] getHostNames();
126
127 /**
128 * Return the list of addresses of the interface to which this instance of JmmDNS is bound.
129 *
130 * @return list of Internet Address
131 * @exception IOException
132 * @see javax.jmdns.JmDNS#getInterface()
133 */
134 public abstract InetAddress[] getInterfaces() throws IOException;
135
136 /**
137 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS.
138 * <p/>
139 * Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive.
140 *
141 * @param type
142 * fully qualified service type, such as <code>_http._tcp.local.</code> .
143 * @param name
144 * unqualified service name, such as <code>foobar</code> .
145 * @return list of service info. If no service info is found the list is empty.
146 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String)
147 */
148 public abstract ServiceInfo[] getServiceInfos(String type, String name);
149
150 /**
151 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS.
152 * <p/>
153 * Usage note: If you call this method from the AWT event dispatcher thread, use a small timeout, or you will make the user interface unresponsive.
154 *
155 * @param type
156 * full qualified service type, such as <code>_http._tcp.local.</code> .
157 * @param name
158 * unqualified service name, such as <code>foobar</code> .
159 * @param timeout
160 * timeout in milliseconds. Typical timeout should be 5s.
161 * @return list of service info. If no service info is found the list is empty.
162 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, long)
163 */
164 public abstract ServiceInfo[] getServiceInfos(String type, String name, long timeout);
165
166 /**
167 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS.
168 * <p/>
169 * Usage note: If you call this method from the AWT event dispatcher thread, use a small timeout, or you will make the user interface unresponsive.
170 *
171 * @param type
172 * full qualified service type, such as <code>_http._tcp.local.</code> .
173 * @param name
174 * unqualified service name, such as <code>foobar</code> .
175 * @param persistent
176 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
177 * @return list of service info. If no service info is found the list is empty.
178 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, boolean)
179 */
180 public abstract ServiceInfo[] getServiceInfos(String type, String name, boolean persistent);
181
182 /**
183 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS.
184 * <p/>
185 * Usage note: If you call this method from the AWT event dispatcher thread, use a small timeout, or you will make the user interface unresponsive.
186 *
187 * @param type
188 * full qualified service type, such as <code>_http._tcp.local.</code> .
189 * @param name
190 * unqualified service name, such as <code>foobar</code> .
191 * @param timeout
192 * timeout in milliseconds. Typical timeout should be 5s.
193 * @param persistent
194 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
195 * @return list of service info. If no service info is found the list is empty.
196 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, boolean, long)
197 */
198 public abstract ServiceInfo[] getServiceInfos(String type, String name, boolean persistent, long timeout);
199
200 /**
201 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.
202 *
203 * @param type
204 * full qualified service type, such as <code>_http._tcp.local.</code> .
205 * @param name
206 * unqualified service name, such as <code>foobar</code> .
207 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String)
208 */
209 public abstract void requestServiceInfo(String type, String name);
210
211 /**
212 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.
213 *
214 * @param type
215 * full qualified service type, such as <code>_http._tcp.local.</code> .
216 * @param name
217 * unqualified service name, such as <code>foobar</code> .
218 * @param persistent
219 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
220 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, boolean)
221 */
222 public abstract void requestServiceInfo(String type, String name, boolean persistent);
223
224 /**
225 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.
226 *
227 * @param type
228 * full qualified service type, such as <code>_http._tcp.local.</code> .
229 * @param name
230 * unqualified service name, such as <code>foobar</code> .
231 * @param timeout
232 * timeout in milliseconds
233 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, long)
234 */
235 public abstract void requestServiceInfo(String type, String name, long timeout);
236
237 /**
238 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.
239 *
240 * @param type
241 * full qualified service type, such as <code>_http._tcp.local.</code> .
242 * @param name
243 * unqualified service name, such as <code>foobar</code> .
244 * @param persistent
245 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received.
246 * @param timeout
247 * timeout in milliseconds
248 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, boolean, long)
249 */
250 public abstract void requestServiceInfo(String type, String name, boolean persistent, long timeout);
251
252 /**
253 * Listen for service types.
254 *
255 * @param listener
256 * listener for service types
257 * @exception IOException
258 * @see javax.jmdns.JmDNS#addServiceTypeListener(javax.jmdns.ServiceTypeListener)
259 */
260 public abstract void addServiceTypeListener(ServiceTypeListener listener) throws IOException;
261
262 /**
263 * Remove listener for service types.
264 *
265 * @param listener
266 * listener for service types
267 * @see javax.jmdns.JmDNS#removeServiceTypeListener(javax.jmdns.ServiceTypeListener)
268 */
269 public abstract void removeServiceTypeListener(ServiceTypeListener listener);
270
271 /**
272 * Listen for services of a given type. The type has to be a fully qualified type name such as <code>_http._tcp.local.</code>.
273 *
274 * @param type
275 * full qualified service type, such as <code>_http._tcp.local.</code>.
276 * @param listener
277 * listener for service updates
278 * @see javax.jmdns.JmDNS#addServiceListener(java.lang.String, javax.jmdns.ServiceListener)
279 */
280 public abstract void addServiceListener(String type, ServiceListener listener);
281
282 /**
283 * Remove listener for services of a given type.
284 *
285 * @param type
286 * full qualified service type, such as <code>_http._tcp.local.</code>.
287 * @param listener
288 * listener for service updates
289 * @see javax.jmdns.JmDNS#removeServiceListener(java.lang.String, javax.jmdns.ServiceListener)
290 */
291 public abstract void removeServiceListener(String type, ServiceListener listener);
292
293 /**
294 * Register a service. The service is registered for access by other jmdns clients. The name of the service may be changed to make it unique.<br>
295 * <b>Note</b> the Service info is cloned for each network interface.
296 *
297 * @param info
298 * service info to register
299 * @exception IOException
300 * @see javax.jmdns.JmDNS#registerService(javax.jmdns.ServiceInfo)
301 */
302 public abstract void registerService(ServiceInfo info) throws IOException;
303
304 /**
305 * Unregister a service. The service should have been registered.
306 *
307 * @param info
308 * service info to remove
309 * @see javax.jmdns.JmDNS#unregisterService(javax.jmdns.ServiceInfo)
310 */
311 public abstract void unregisterService(ServiceInfo info);
312
313 /**
314 * Unregister all services.
315 *
316 * @see javax.jmdns.JmDNS#unregisterAllServices()
317 */
318 public abstract void unregisterAllServices();
319
320 /**
321 * Register a service type. If this service type was not already known, all service listeners will be notified of the new service type. Service types are automatically registered as they are discovered.
322 *
323 * @param type
324 * full qualified service type, such as <code>_http._tcp.local.</code>.
325 * @see javax.jmdns.JmDNS#registerServiceType(java.lang.String)
326 */
327 public abstract void registerServiceType(String type);
328
329 /**
330 * Returns a list of service infos of the specified type.
331 *
332 * @param type
333 * Service type name, such as <code>_http._tcp.local.</code>.
334 * @return An array of service instance.
335 * @see javax.jmdns.JmDNS#list(java.lang.String)
336 */
337 public abstract ServiceInfo[] list(String type);
338
339 /**
340 * Returns a list of service infos of the specified type.
341 *
342 * @param type
343 * Service type name, such as <code>_http._tcp.local.</code>.
344 * @param timeout
345 * timeout in milliseconds. Typical timeout should be 6s.
346 * @return An array of service instance.
347 * @see javax.jmdns.JmDNS#list(java.lang.String, long)
348 */
349 public abstract ServiceInfo[] list(String type, long timeout);
350
351 /**
352 * Returns a list of service infos of the specified type sorted by subtype. Any service that do not register a subtype is listed in the empty subtype section.
353 *
354 * @param type
355 * Service type name, such as <code>_http._tcp.local.</code>.
356 * @return A dictionary of service info by subtypes.
357 * @see javax.jmdns.JmDNS#listBySubtype(java.lang.String)
358 */
359 public abstract Map<String, ServiceInfo[]> listBySubtype(String type);
360
361 /**
362 * Returns a list of service infos of the specified type sorted by subtype. Any service that do not register a subtype is listed in the empty subtype section.
363 *
364 * @param type
365 * Service type name, such as <code>_http._tcp.local.</code>.
366 * @param timeout
367 * timeout in milliseconds. Typical timeout should be 6s.
368 * @return A dictionary of service info by subtypes.
369 * @see javax.jmdns.JmDNS#listBySubtype(java.lang.String, long)
370 */
371 public abstract Map<String, ServiceInfo[]> listBySubtype(String type, long timeout);
372
373 /**
374 * Listen to network changes.
375 *
376 * @param listener
377 * listener for network changes
378 */
379 public abstract void addNetworkTopologyListener(NetworkTopologyListener listener);
380
381 /**
382 * Remove listener for network changes.
383 *
384 * @param listener
385 * listener for network changes
386 */
387 public abstract void removeNetworkTopologyListener(NetworkTopologyListener listener);
388
389 /**
390 * Returns list of network change listeners
391 *
392 * @return list of network change listeners
393 */
394 public abstract NetworkTopologyListener[] networkListeners();
395
396 }