JmmDNS
Date: 2017-02-10

javax.jmdns

## Interface JmmDNS

- All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
  All Known Implementing Classes:
    JmmDNSImpl

      public interface JmmDNS
      extends java.io.Closeable

  Java Multihomed Multicast DNS

  Uses an underlying `JmDNS` instance for each `InetAddress` found on this computer.
  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 `NetworkTopologyListener`).
  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.

  Note: This API is experimental and may change in the future please let us know what work and what does not work in you application.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `JmmDNS.Factory` JmmDNS.Factory enable the creation of new instance of JmmDNS.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addNetworkTopologyListener(NetworkTopologyListener listener)` Listen to network changes.
    `void` | `addServiceListener(java.lang.String type, ServiceListener listener)` Listen for services of a given type.
    `void` | `addServiceTypeListener(ServiceTypeListener listener)` Listen for service types.
    `java.lang.String[]` | `getHostNames()` Return the list HostName associated with this JmmDNS instance.
    `java.net.InetAddress[]` | `getInterfaces()` Return the list of addresses of the interface to which this instance of JmmDNS is bound.
    `java.lang.String[]` | `getNames()` Return the names of the JmDNS instances.
    `ServiceInfo[]` | `getServiceInfos(java.lang.String type, java.lang.String name)` Get service information.
    `ServiceInfo[]` | `getServiceInfos(java.lang.String type, java.lang.String name, boolean persistent)` Get service information.
    `ServiceInfo[]` | `getServiceInfos(java.lang.String type, java.lang.String name, boolean persistent, long timeout)` Get service information.
    `ServiceInfo[]` | `getServiceInfos(java.lang.String type, java.lang.String name, long timeout)` Get service information.
    `ServiceInfo[]` | `list(java.lang.String type)` Returns a list of service infos of the specified type.
    `ServiceInfo[]` | `list(java.lang.String type, long timeout)` Returns a list of service infos of the specified type.
    `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.
    `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.
    `NetworkTopologyListener[]` | `networkListeners()` Returns list of network change listeners
    `void` | `registerService(ServiceInfo info)` Register a service.
    `void` | `registerServiceType(java.lang.String type)` Register a service type.
    `void` | `removeNetworkTopologyListener(NetworkTopologyListener listener)` Remove listener for network changes.
    `void` | `removeServiceListener(java.lang.String type, ServiceListener listener)` Remove listener for services of a given type.
    `void` | `removeServiceTypeListener(ServiceTypeListener listener)` Remove listener for service types.
    `void` | `requestServiceInfo(java.lang.String type, java.lang.String name)` Request service information.
    `void` | `requestServiceInfo(java.lang.String type, java.lang.String name, boolean persistent)` Request service information.
    `void` | `requestServiceInfo(java.lang.String type, java.lang.String name, boolean persistent, long timeout)` Request service information.
    `void` | `requestServiceInfo(java.lang.String type, java.lang.String name, long timeout)` Request service information.
    `void` | `unregisterAllServices()` Unregister all services.
    `void` | `unregisterService(ServiceInfo info)` Unregister a service.

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

      `close`

- - ### Method Detail

    - #### getNames

          java.lang.String[] getNames()

      Return the names of the JmDNS instances.
      Returns:
        list of name of the JmDNS
      See Also:
        `JmDNS.getName()`

    - #### getHostNames

          java.lang.String[] getHostNames()

      Return the list HostName associated with this JmmDNS instance.
      Returns:
        list of host names
      See Also:
        `JmDNS.getHostName()`

    - #### getInterfaces

          java.net.InetAddress[] getInterfaces()
                                               throws java.io.IOException

      Return the list of addresses of the interface to which this instance of JmmDNS is bound.
      Returns:
        list of Internet Address
      Throws:
        `java.io.IOException`
      See Also:
        `JmDNS.getInterface()`

    - #### getServiceInfos

          ServiceInfo[] getServiceInfos(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 on all DNS.

      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:
        list of service info. If no service info is found the list is empty.
      See Also:
        `JmDNS.getServiceInfo(java.lang.String, java.lang.String)`

    - #### getServiceInfos

          ServiceInfo[] getServiceInfos(java.lang.String type,
                                      java.lang.String name,
                                      long timeout)

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

      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:
        list of service info. If no service info is found the list is empty.
      See Also:
        `JmDNS.getServiceInfo(java.lang.String, java.lang.String, long)`

    - #### getServiceInfos

          ServiceInfo[] getServiceInfos(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 on all DNS.

      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` .
        `persistent` - if `true` ServiceListener.resolveService will be called whenever new new information is received.
      Returns:
        list of service info. If no service info is found the list is empty.
      See Also:
        `JmDNS.getServiceInfo(java.lang.String, java.lang.String, boolean)`

    - #### getServiceInfos

          ServiceInfo[] getServiceInfos(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 until updated information is received on all DNS.

      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:
        list of service info. If no service info is found the list is empty.
      See Also:
        `JmDNS.getServiceInfo(java.lang.String, java.lang.String, boolean, long)`

    - #### requestServiceInfo

          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.
      Parameters:
        `type` - full qualified service type, such as `_http._tcp.local.` .
        `name` - unqualified service name, such as `foobar` .
      See Also:
        `JmDNS.requestServiceInfo(java.lang.String, java.lang.String)`

    - #### requestServiceInfo

          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.
      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.
      See Also:
        `JmDNS.requestServiceInfo(java.lang.String, java.lang.String, boolean)`

    - #### requestServiceInfo

          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
      See Also:
        `JmDNS.requestServiceInfo(java.lang.String, java.lang.String, long)`

    - #### requestServiceInfo

          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
      See Also:
        `JmDNS.requestServiceInfo(java.lang.String, java.lang.String, boolean, long)`

    - #### addServiceTypeListener

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

      Listen for service types.
      Parameters:
        `listener` - listener for service types
      Throws:
        `java.io.IOException`
      See Also:
        `JmDNS.addServiceTypeListener(javax.jmdns.ServiceTypeListener)`

    - #### removeServiceTypeListener

          void removeServiceTypeListener(ServiceTypeListener listener)

      Remove listener for service types.
      Parameters:
        `listener` - listener for service types
      See Also:
        `JmDNS.removeServiceTypeListener(javax.jmdns.ServiceTypeListener)`

    - #### addServiceListener

          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
      See Also:
        `JmDNS.addServiceListener(java.lang.String, javax.jmdns.ServiceListener)`

    - #### removeServiceListener

          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
      See Also:
        `JmDNS.removeServiceListener(java.lang.String, javax.jmdns.ServiceListener)`

    - #### registerService

          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 the Service info is cloned for each network interface.
      Parameters:
        `info` - service info to register
      Throws:
        `java.io.IOException`
      See Also:
        `JmDNS.registerService(javax.jmdns.ServiceInfo)`

    - #### unregisterService

          void unregisterService(ServiceInfo info)

      Unregister a service. The service should have been registered.
      Parameters:
        `info` - service info to remove
      See Also:
        `JmDNS.unregisterService(javax.jmdns.ServiceInfo)`

    - #### unregisterAllServices

          void unregisterAllServices()

      Unregister all services.
      See Also:
        `JmDNS.unregisterAllServices()`

    - #### registerServiceType

          void 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.`.
      See Also:
        `JmDNS.registerServiceType(java.lang.String)`

    - #### list

          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.
      See Also:
        `JmDNS.list(java.lang.String)`

    - #### list

          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.
      See Also:
        `JmDNS.list(java.lang.String, long)`

    - #### listBySubtype

          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.
      See Also:
        `JmDNS.listBySubtype(java.lang.String)`

    - #### listBySubtype

          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.
      See Also:
        `JmDNS.listBySubtype(java.lang.String, long)`

    - #### addNetworkTopologyListener

          void addNetworkTopologyListener(NetworkTopologyListener listener)

      Listen to network changes.
      Parameters:
        `listener` - listener for network changes

    - #### removeNetworkTopologyListener

          void removeNetworkTopologyListener(NetworkTopologyListener listener)

      Remove listener for network changes.
      Parameters:
        `listener` - listener for network changes

    - #### networkListeners

          NetworkTopologyListener[] networkListeners()

      Returns list of network change listeners
      Returns:
        list of network change listeners