JmDNS
Date: 2017-02-10

javax.jmdns

## Class JmDNS

- java.lang.Object
- - javax.jmdns.JmDNS

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
  Direct Known Subclasses:
    JmDNSImpl

      public abstract class JmDNS
      extends java.lang.Object
      implements java.io.Closeable

  mDNS implementation in Java.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `JmDNS.Delegate`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `VERSION` The version of JmDNS.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JmDNS()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addServiceListener(java.lang.String type, ServiceListener listener)` Listen for services of a given type.
    `abstract void` | `addServiceTypeListener(ServiceTypeListener listener)` Listen for service types.
    `static JmDNS` | `create()` Create an instance of JmDNS.
    `static JmDNS` | `create(java.net.InetAddress addr)` Create an instance of JmDNS and bind it to a specific network interface given its IP-address.
    `static JmDNS` | `create(java.net.InetAddress addr, java.lang.String name)` Create an instance of JmDNS and bind it to a specific network interface given its IP-address.
    `static JmDNS` | `create(java.lang.String name)` Create an instance of JmDNS.
    `abstract JmDNS.Delegate` | `getDelegate()` Returns the instance delegate
    `abstract java.lang.String` | `getHostName()` Return the HostName associated with this JmDNS instance.
    `abstract java.net.InetAddress` | `getInterface()` Return the address of the interface to which this instance of JmDNS is bound.
    `abstract java.lang.String` | `getName()` Return the name of the JmDNS instance.
    `abstract ServiceInfo` | `getServiceInfo(java.lang.String type, java.lang.String name)` Get service information.
    `abstract ServiceInfo` | `getServiceInfo(java.lang.String type, java.lang.String name, boolean persistent)` Get service information.
    `abstract ServiceInfo` | `getServiceInfo(java.lang.String type, java.lang.String name, boolean persistent, long timeout)` Get service information.
    `abstract ServiceInfo` | `getServiceInfo(java.lang.String type, java.lang.String name, long timeout)` Get service information.
    `abstract ServiceInfo[]` | `list(java.lang.String type)` Returns a list of service infos of the specified type.
    `abstract ServiceInfo[]` | `list(java.lang.String type, long timeout)` Returns a list of service infos of the specified type.
    `abstract java.util.Map<java.lang.String,ServiceInfo[]>` | `listBySubtype(java.lang.String type)` Returns a list of service infos of the specified type sorted by subtype.
    `abstract java.util.Map<java.lang.String,ServiceInfo[]>` | `listBySubtype(java.lang.String type, long timeout)` Returns a list of service infos of the specified type sorted by subtype.
    `abstract void` | `printServices()` Deprecated. since 3.2.2
    `abstract void` | `registerService(ServiceInfo info)` Register a service.
    `abstract boolean` | `registerServiceType(java.lang.String type)` Register a service type.
    `abstract void` | `removeServiceListener(java.lang.String type, ServiceListener listener)` Remove listener for services of a given type.
    `abstract void` | `removeServiceTypeListener(ServiceTypeListener listener)` Remove listener for service types.
    `abstract void` | `requestServiceInfo(java.lang.String type, java.lang.String name)` Request service information.
    `abstract void` | `requestServiceInfo(java.lang.String type, java.lang.String name, boolean persistent)` Request service information.
    `abstract void` | `requestServiceInfo(java.lang.String type, java.lang.String name, boolean persistent, long timeout)` Request service information.
    `abstract void` | `requestServiceInfo(java.lang.String type, java.lang.String name, long timeout)` Request service information.
    `abstract JmDNS.Delegate` | `setDelegate(JmDNS.Delegate value)` Sets the instance delegate
    `abstract void` | `unregisterAllServices()` Unregister all services.
    `abstract void` | `unregisterService(ServiceInfo info)` Unregister a service.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.io.Closeable

      `close`

- - ### Field Detail

    - #### VERSION

          public static final java.lang.String VERSION

      The version of JmDNS.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JmDNS

          public JmDNS()

  - ### Method Detail

    - #### create

          public static JmDNS create()
                              throws java.io.IOException

      Create an instance of JmDNS.

      Note: This is a convenience method. The preferred constructor is `create(InetAddress, String)`.
      Check that your platform correctly handle the default localhost IP address and the local hostname. In doubt use the explicit constructor.
      This call is equivalent to `create(null, null)`.

      Returns:
        jmDNS instance
      Throws:
        `java.io.IOException` - if an exception occurs during the socket creation
      See Also:
        `create(InetAddress, String)`

    - #### create

          public static JmDNS create(java.net.InetAddress addr)
                              throws java.io.IOException

      Create an instance of JmDNS and bind it to a specific network interface given its IP-address.

      Note: This is a convenience method. The preferred constructor is `create(InetAddress, String)`.
      Check that your platform correctly handle the default localhost IP address and the local hostname. In doubt use the explicit constructor.
      This call is equivalent to `create(addr, null)`.

      Parameters:
        `addr` - IP address to bind to.
      Returns:
        jmDNS instance
      Throws:
        `java.io.IOException` - if an exception occurs during the socket creation
      See Also:
        `create(InetAddress, String)`

    - #### create

          public static JmDNS create(java.lang.String name)
                              throws java.io.IOException

      Create an instance of JmDNS.

      Note: This is a convenience method. The preferred constructor is `create(InetAddress, String)`.
      Check that your platform correctly handle the default localhost IP address and the local hostname. In doubt use the explicit constructor.
      This call is equivalent to `create(null, name)`.

      Parameters:
        `name` - name of the newly created JmDNS
      Returns:
        jmDNS instance
      Throws:
        `java.io.IOException` - if an exception occurs during the socket creation
      See Also:
        `create(InetAddress, String)`

    - #### create

          public static JmDNS create(java.net.InetAddress addr,
                     java.lang.String name)
                              throws java.io.IOException

      Create an instance of JmDNS and bind it to a specific network interface given its IP-address.

      If `addr` parameter is null this method will try to resolve to a local IP address of the machine using a network discovery:
      1. Check the system property `net.mdns.interface`
      2. Check the JVM local host
      3. Use the `NetworkTopologyDiscovery` to find a valid network interface and IP.
      4. In the last resort bind to the loopback address. This is non functional in most cases.
      If `name` parameter is null will use the hostname. The hostname is determined by the following algorithm:
      1. Get the hostname from the InetAdress obtained before.
      2. If the hostname is a reverse lookup default to `JmDNS name` or `computer` if null.
      3. If the name contains `'.'` replace them by `'-'`
      4. Add `.local.` at the end of the name.

      Note: If you need to use a custom `NetworkTopologyDiscovery` it must be setup before any call to this method. This is done by setting up a `NetworkTopologyDiscovery.Factory.ClassDelegate` and installing it using `NetworkTopologyDiscovery.Factory.setClassDelegate(NetworkTopologyDiscovery.Factory.ClassDelegate)`. This must be done before creating a `JmDNS` or `JmmDNS` instance.

      Parameters:
        `addr` - IP address to bind to.
        `name` - name of the newly created JmDNS
      Returns:
        jmDNS instance
      Throws:
        `java.io.IOException` - if an exception occurs during the socket creation

    - #### getName

          public abstract java.lang.String getName()

      Return the name of the JmDNS instance. This is an arbitrary string that is useful for distinguishing instances.
      Returns:
        name of the JmDNS

    - #### getHostName

          public abstract java.lang.String getHostName()

      Return the HostName associated with this JmDNS instance. Note: May not be the same as what started. The host name is subject to negotiation.
      Returns:
        Host name

    - #### getInterface

          public abstract java.net.InetAddress getInterface()
                                                     throws java.io.IOException

      Return the address of the interface to which this instance of JmDNS is bound.
      Returns:
        Internet Address
      Throws:
        `java.io.IOException` - if there is an error in the underlying protocol, such as a TCP error.

    - #### getServiceInfo

          public abstract ServiceInfo getServiceInfo(java.lang.String type,
                                   java.lang.String name)

      Get service information. If the information is not cached, the method will block until updated information is received.

      Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive.
      Parameters:
        `type` - fully qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
      Returns:
        null if the service information cannot be obtained

    - #### getServiceInfo

          public abstract ServiceInfo getServiceInfo(java.lang.String type,
                                   java.lang.String name,
                                   long timeout)

      Get service information. If the information is not cached, the method will block for the given timeout until updated information is received.

      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.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
        `timeout` - timeout in milliseconds. Typical timeout should be 5s.
      Returns:
        null if the service information cannot be obtained

    - #### getServiceInfo

          public abstract ServiceInfo getServiceInfo(java.lang.String type,
                                   java.lang.String name,
                                   boolean persistent)

      Get service information. If the information is not cached, the method will block until updated information is received.

      Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive.
      Parameters:
        `type` - fully qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
        `persistent` - if `true` ServiceListener.resolveService will be called whenever new new information is received.
      Returns:
        null if the service information cannot be obtained

    - #### getServiceInfo

          public abstract ServiceInfo getServiceInfo(java.lang.String type,
                                   java.lang.String name,
                                   boolean persistent,
                                   long timeout)

      Get service information. If the information is not cached, the method will block for the given timeout until updated information is received.

      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.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
        `timeout` - timeout in milliseconds. Typical timeout should be 5s.
        `persistent` - if `true` ServiceListener.resolveService will be called whenever new new information is received.
      Returns:
        null if the service information cannot be obtained

    - #### requestServiceInfo

          public abstract void requestServiceInfo(java.lang.String type,
                                java.lang.String name)

      Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.

      Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .

    - #### requestServiceInfo

          public abstract void requestServiceInfo(java.lang.String type,
                                java.lang.String name,
                                boolean persistent)

      Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.

      Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
        `persistent` - if `true` ServiceListener.resolveService will be called whenever new new information is received.

    - #### requestServiceInfo

          public abstract void requestServiceInfo(java.lang.String type,
                                java.lang.String name,
                                long timeout)

      Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
        `timeout` - timeout in milliseconds

    - #### requestServiceInfo

          public abstract void requestServiceInfo(java.lang.String type,
                                java.lang.String name,
                                boolean persistent,
                                long timeout)

      Request service information. The information about the service is requested and the ServiceListener.resolveService method is called as soon as it is available.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
        `persistent` - if `true` ServiceListener.resolveService will be called whenever new new information is received.
        `timeout` - timeout in milliseconds

    - #### addServiceTypeListener

          public abstract void addServiceTypeListener(ServiceTypeListener listener)
                                               throws java.io.IOException

      Listen for service types.
      Parameters:
        `listener` - listener for service types
      Throws:
        `java.io.IOException` - if there is an error in the underlying protocol, such as a TCP error.

    - #### removeServiceTypeListener

          public abstract void removeServiceTypeListener(ServiceTypeListener listener)

      Remove listener for service types.
      Parameters:
        `listener` - listener for service types

    - #### addServiceListener

          public abstract void addServiceListener(java.lang.String type,
                                ServiceListener listener)

      Listen for services of a given type. The type has to be a fully qualified type name such as `_http._tcp.local.`.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.`.
        `listener` - listener for service updates

    - #### removeServiceListener

          public abstract void removeServiceListener(java.lang.String type,
                                   ServiceListener listener)

      Remove listener for services of a given type.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.`.
        `listener` - listener for service updates

    - #### registerService

          public abstract void registerService(ServiceInfo info)
                                        throws java.io.IOException

      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.
      Note that the given `ServiceInfo` is bound to this `JmDNS` instance, and should not be reused for any other registerService(ServiceInfo).
      Parameters:
        `info` - service info to register
      Throws:
        `java.io.IOException` - if there is an error in the underlying protocol, such as a TCP error.

    - #### unregisterService

          public abstract void unregisterService(ServiceInfo info)

      Unregister a service. The service should have been registered.

      Note: Unregistered services will not disappear form the list of services immediately. According to the specification, when unregistering services we send goodbye packets and then wait 1s before purging the cache.
      This is support for shared records that can be rescued by some other cooperation DNS.

           Clients receiving a Multicast DNS Response with a TTL of zero SHOULD NOT immediately delete the record from the cache, but instead record a TTL of 1 and then delete the record one second later.

      Parameters:
        `info` - service info to remove

    - #### unregisterAllServices

          public abstract void unregisterAllServices()

      Unregister all services.

    - #### registerServiceType

          public abstract boolean registerServiceType(java.lang.String type)

      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.

      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.`.
      Returns:
        `true` if the type or subtype was added, `false` if the type was already registered.

    - #### printServices

          @Deprecated
          public abstract void printServices()

      Deprecated. since 3.2.2
      List Services and serviceTypes. Debugging Only

    - #### list

          public abstract ServiceInfo[] list(java.lang.String type)

      Returns a list of service infos of the specified type.
      Parameters:
        `type` - Service type name, such as `_http._tcp.local.`.
      Returns:
        An array of service instance.

    - #### list

          public abstract ServiceInfo[] list(java.lang.String type,
                           long timeout)

      Returns a list of service infos of the specified type.
      Parameters:
        `type` - Service type name, such as `_http._tcp.local.`.
        `timeout` - timeout in milliseconds. Typical timeout should be 6s.
      Returns:
        An array of service instance.

    - #### listBySubtype

          public abstract java.util.Map<java.lang.String,ServiceInfo[]> listBySubtype(java.lang.String type)

      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.
      Parameters:
        `type` - Service type name, such as `_http._tcp.local.`.
      Returns:
        A dictionary of service info by subtypes.

    - #### listBySubtype

          public abstract java.util.Map<java.lang.String,ServiceInfo[]> listBySubtype(java.lang.String type,
                                                                    long timeout)

      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.
      Parameters:
        `type` - Service type name, such as `_http._tcp.local.`.
        `timeout` - timeout in milliseconds. Typical timeout should be 6s.
      Returns:
        A dictionary of service info by subtypes.

    - #### getDelegate

          public abstract JmDNS.Delegate getDelegate()

      Returns the instance delegate
      Returns:
        instance delegate

    - #### setDelegate

          public abstract JmDNS.Delegate setDelegate(JmDNS.Delegate value)

      Sets the instance delegate
      Parameters:
        `value` - new instance delegate
      Returns:
        previous instance delegate