1/** 2 * 3 */ 4package javax.jmdns; 5 6import java.io.Closeable; 7import java.io.IOException; 8import java.net.InetAddress; 9import java.util.Map; 10import java.util.concurrent.atomic.AtomicReference; 11 12import 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 */ 27public 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#getInetAddress() 133 */ 134 public abstract InetAddress[] getInetAddresses() throws IOException; 135 136 /** 137 * Return the list of addresses of the interface to which this instance of JmmDNS is bound. 138 * 139 * @return list of Internet Address 140 * @exception IOException 141 * @see javax.jmdns.JmDNS#getInterface() 142 * @deprecated do not use this implementation yields unpredictable results use {@link #getInetAddresses()} 143 */ 144 @Deprecated 145 public abstract InetAddress[] getInterfaces() throws IOException; 146 147 /** 148 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS. 149 * <p/> 150 * Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive. 151 * 152 * @param type 153 * fully qualified service type, such as <code>_http._tcp.local.</code> . 154 * @param name 155 * unqualified service name, such as <code>foobar</code> . 156 * @return list of service info. If no service info is found the list is empty. 157 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String) 158 */ 159 public abstract ServiceInfo[] getServiceInfos(String type, String name); 160 161 /** 162 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS. 163 * <p/> 164 * 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. 165 * 166 * @param type 167 * full qualified service type, such as <code>_http._tcp.local.</code> . 168 * @param name 169 * unqualified service name, such as <code>foobar</code> . 170 * @param timeout 171 * timeout in milliseconds. Typical timeout should be 5s. 172 * @return list of service info. If no service info is found the list is empty. 173 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, long) 174 */ 175 public abstract ServiceInfo[] getServiceInfos(String type, String name, long timeout); 176 177 /** 178 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS. 179 * <p/> 180 * 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. 181 * 182 * @param type 183 * full qualified service type, such as <code>_http._tcp.local.</code> . 184 * @param name 185 * unqualified service name, such as <code>foobar</code> . 186 * @param persistent 187 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. 188 * @return list of service info. If no service info is found the list is empty. 189 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, boolean) 190 */ 191 public abstract ServiceInfo[] getServiceInfos(String type, String name, boolean persistent); 192 193 /** 194 * Get service information. If the information is not cached, the method will block until updated information is received on all DNS. 195 * <p/> 196 * 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. 197 * 198 * @param type 199 * full qualified service type, such as <code>_http._tcp.local.</code> . 200 * @param name 201 * unqualified service name, such as <code>foobar</code> . 202 * @param timeout 203 * timeout in milliseconds. Typical timeout should be 5s. 204 * @param persistent 205 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. 206 * @return list of service info. If no service info is found the list is empty. 207 * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, boolean, long) 208 */ 209 public abstract ServiceInfo[] getServiceInfos(String type, String name, boolean persistent, long timeout); 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 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String) 219 */ 220 public abstract void requestServiceInfo(String type, String name); 221 222 /** 223 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available. 224 * 225 * @param type 226 * full qualified service type, such as <code>_http._tcp.local.</code> . 227 * @param name 228 * unqualified service name, such as <code>foobar</code> . 229 * @param persistent 230 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. 231 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, boolean) 232 */ 233 public abstract void requestServiceInfo(String type, String name, boolean persistent); 234 235 /** 236 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available. 237 * 238 * @param type 239 * full qualified service type, such as <code>_http._tcp.local.</code> . 240 * @param name 241 * unqualified service name, such as <code>foobar</code> . 242 * @param timeout 243 * timeout in milliseconds 244 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, long) 245 */ 246 public abstract void requestServiceInfo(String type, String name, long timeout); 247 248 /** 249 * Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available. 250 * 251 * @param type 252 * full qualified service type, such as <code>_http._tcp.local.</code> . 253 * @param name 254 * unqualified service name, such as <code>foobar</code> . 255 * @param persistent 256 * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. 257 * @param timeout 258 * timeout in milliseconds 259 * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, boolean, long) 260 */ 261 public abstract void requestServiceInfo(String type, String name, boolean persistent, long timeout); 262 263 /** 264 * Listen for service types. 265 * 266 * @param listener 267 * listener for service types 268 * @exception IOException 269 * @see javax.jmdns.JmDNS#addServiceTypeListener(javax.jmdns.ServiceTypeListener) 270 */ 271 public abstract void addServiceTypeListener(ServiceTypeListener listener) throws IOException; 272 273 /** 274 * Remove listener for service types. 275 * 276 * @param listener 277 * listener for service types 278 * @see javax.jmdns.JmDNS#removeServiceTypeListener(javax.jmdns.ServiceTypeListener) 279 */ 280 public abstract void removeServiceTypeListener(ServiceTypeListener listener); 281 282 /** 283 * Listen for services of a given type. The type has to be a fully qualified type name such as <code>_http._tcp.local.</code>. 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#addServiceListener(java.lang.String, javax.jmdns.ServiceListener) 290 */ 291 public abstract void addServiceListener(String type, ServiceListener listener); 292 293 /** 294 * Remove listener for services of a given type. 295 * 296 * @param type 297 * full qualified service type, such as <code>_http._tcp.local.</code>. 298 * @param listener 299 * listener for service updates 300 * @see javax.jmdns.JmDNS#removeServiceListener(java.lang.String, javax.jmdns.ServiceListener) 301 */ 302 public abstract void removeServiceListener(String type, ServiceListener listener); 303 304 /** 305 * 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> 306 * <b>Note</b> the Service info is cloned for each network interface. 307 * 308 * @param info 309 * service info to register 310 * @exception IOException 311 * @see javax.jmdns.JmDNS#registerService(javax.jmdns.ServiceInfo) 312 */ 313 public abstract void registerService(ServiceInfo info) throws IOException; 314 315 /** 316 * Unregister a service. The service should have been registered. 317 * 318 * @param info 319 * service info to remove 320 * @see javax.jmdns.JmDNS#unregisterService(javax.jmdns.ServiceInfo) 321 */ 322 public abstract void unregisterService(ServiceInfo info); 323 324 /** 325 * Unregister all services. 326 * 327 * @see javax.jmdns.JmDNS#unregisterAllServices() 328 */ 329 public abstract void unregisterAllServices(); 330 331 /** 332 * 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. 333 * 334 * @param type 335 * full qualified service type, such as <code>_http._tcp.local.</code>. 336 * @see javax.jmdns.JmDNS#registerServiceType(java.lang.String) 337 */ 338 public abstract void registerServiceType(String type); 339 340 /** 341 * Returns a list of service infos of the specified type. 342 * 343 * @param type 344 * Service type name, such as <code>_http._tcp.local.</code>. 345 * @return An array of service instance. 346 * @see javax.jmdns.JmDNS#list(java.lang.String) 347 */ 348 public abstract ServiceInfo[] list(String type); 349 350 /** 351 * Returns a list of service infos of the specified type. 352 * 353 * @param type 354 * Service type name, such as <code>_http._tcp.local.</code>. 355 * @param timeout 356 * timeout in milliseconds. Typical timeout should be 6s. 357 * @return An array of service instance. 358 * @see javax.jmdns.JmDNS#list(java.lang.String, long) 359 */ 360 public abstract ServiceInfo[] list(String type, long timeout); 361 362 /** 363 * 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. 364 * 365 * @param type 366 * Service type name, such as <code>_http._tcp.local.</code>. 367 * @return A dictionary of service info by subtypes. 368 * @see javax.jmdns.JmDNS#listBySubtype(java.lang.String) 369 */ 370 public abstract Map<String, ServiceInfo[]> listBySubtype(String type); 371 372 /** 373 * 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. 374 * 375 * @param type 376 * Service type name, such as <code>_http._tcp.local.</code>. 377 * @param timeout 378 * timeout in milliseconds. Typical timeout should be 6s. 379 * @return A dictionary of service info by subtypes. 380 * @see javax.jmdns.JmDNS#listBySubtype(java.lang.String, long) 381 */ 382 public abstract Map<String, ServiceInfo[]> listBySubtype(String type, long timeout); 383 384 /** 385 * Listen to network changes. 386 * 387 * @param listener 388 * listener for network changes 389 */ 390 public abstract void addNetworkTopologyListener(NetworkTopologyListener listener); 391 392 /** 393 * Remove listener for network changes. 394 * 395 * @param listener 396 * listener for network changes 397 */ 398 public abstract void removeNetworkTopologyListener(NetworkTopologyListener listener); 399 400 /** 401 * Returns list of network change listeners 402 * 403 * @return list of network change listeners 404 */ 405 public abstract NetworkTopologyListener[] networkListeners(); 406 407} 408