Package jmri.util.zeroconf

Class ZeroConfServiceManager

  • All Implemented Interfaces:
    Disposable, InstanceManagerAutoDefault
    public class ZeroConfServiceManager
extends java.lang.Object
implements InstanceManagerAutoDefault, Disposable
    A ZeroConfServiceManager object manages zeroConf network service advertisements.

    ZeroConfService objects encapsulate zeroConf network services created using JmDNS, providing methods to start and stop service advertisements and to query service state. Typical usage would be: 

     ZeroConfService myService = ZeroConfService.create("_withrottle._tcp.local.", port);
 myService.publish();
    or, if you do not wish to retain the ZeroConfService object: 
     ZeroConfService.create("_http._tcp.local.", port).publish();
    ZeroConfService objects can also be created with a HashMap of properties that are included in the TXT record for the service advertisement. This HashMap should remain small, but it could include information such as the default path (for a web server), a specific protocol version, or other information. Note that all service advertisements include the JMRI version, using the key "version", and the JMRI version numbers in a string "major.minor.test" with the key "jmri"

    All ZeroConfServices are published with the computer's hostname as the mDNS hostname (unless it cannot be determined by JMRI), as well as the JMRI node name in the TXT record with the key "node".

    All ZeroConfServices are automatically stopped when the JMRI application shuts down. Use allServices() to get a collection of all published ZeroConfService objects.

    This file is part of JMRI.

    JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

    JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

    See Also:
    JmDNS, ServiceInfo

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Collection<ZeroConfService> allServices()
      A list of published ZeroConfServices
      ZeroConfService create​(java.lang.String type, int port)
      Create a ZeroConfService with the minimal required settings.
      ZeroConfService create​(java.lang.String type, int port, java.util.HashMap<java.lang.String,​java.lang.String> properties)
      Create a ZeroConfService with an automatically detected server name.
      ZeroConfService create​(java.lang.String type, java.lang.String name, int port, int weight, int priority, java.util.HashMap<java.lang.String,​java.lang.String> properties)
      Create a ZeroConfService.
      void dispose()
      Called when disposing of a disposable.
      java.lang.String FQDN​(java.net.InetAddress address)
      Return the fully qualified domain name or "computer" if the system name cannot be determined.
      java.util.Set<java.net.InetAddress> getAddresses()
      Get all addresses that JmDNS instances can be created for excluding loopback addresses.
      java.util.Set<java.net.InetAddress> getAddresses​(ZeroConfServiceManager.Protocol protocol)
      Get all addresses that JmDNS instances can be created for excluding loopback addresses.
      java.util.Set<java.net.InetAddress> getAddresses​(ZeroConfServiceManager.Protocol protocol, boolean useLinkLocal, boolean useLoopback)
      Get all addresses of a specific IP protocol that JmDNS instances can be created for.
      (package private) java.util.HashMap<java.net.InetAddress,​javax.jmdns.JmDNS> getDNSes()
      The list of JmDNS handlers.
      ZeroConfPreferences getPreferences()  
      static java.lang.String hostName​(java.lang.String string)
      Return an RFC 1123 compliant host name in all lower-case punycode from a given string.
      java.lang.String hostName​(java.net.InetAddress address)
      Return the system name or "computer" if the system name cannot be determined.
      boolean isPublished​(ZeroConfService service)  
      protected java.lang.String key​(java.lang.String type, java.lang.String name)
      Generate a ZeroConfService getKey for searching in the HashMap of running services.
      void publish​(ZeroConfService service)
      Start advertising the service.
      void stop​(ZeroConfService service)
      Stop advertising the service.
      void stopAll()
      Stop advertising all services.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • create

        public ZeroConfService create​(java.lang.String type,
                              int port,
                              java.util.HashMap<java.lang.String,​java.lang.String> properties)
        Create a ZeroConfService with an automatically detected server name. This method calls create(java.lang.String, java.lang.String, int, int, int, java.util.HashMap) with the default weight and priority, and with the result of WebServerPreferences.getRailroadName() reformatted to replace dots and dashes with spaces.
        Parameters:
        type - The service protocol
        port - The port the service runs over
        properties - Additional information to be listed in service advertisement
        Returns:
        A new unpublished ZeroConfService, or an existing service

      • create

        public ZeroConfService create​(java.lang.String type,
                              java.lang.String name,
                              int port,
                              int weight,
                              int priority,
                              java.util.HashMap<java.lang.String,​java.lang.String> properties)
        Create a ZeroConfService. The property version is added or replaced with the current JMRI version as its value. The property jmri is added or replaced with the JMRI major.minor.test version string as its value.

        If a service with the same getKey as the new service is already published, the original service is returned unmodified.

        Parameters:
        type - The service protocol
        name - The name of the JMRI server listed on client devices
        port - The port the service runs over
        weight - Default value is 0
        priority - Default value is 0
        properties - Additional information to be listed in service advertisement
        Returns:
        A new unpublished ZeroConfService, or an existing service

      • key

        protected java.lang.String key​(java.lang.String type,
                               java.lang.String name)
        Generate a ZeroConfService getKey for searching in the HashMap of running services.
        Parameters:
        type - the service type (usually a protocol name or mapping)
        name - the service name (usually the JMRI railroad name or system host name)
        Returns:
        The combination of the name and type of the service.

      • publish

        public void publish​(ZeroConfService service)
        Start advertising the service.
        Parameters:
        service - The service to publish

      • stop

        public void stop​(ZeroConfService service)
        Stop advertising the service.
        Parameters:
        service - The service to stop advertising

      • stopAll

        public void stopAll()
        Stop advertising all services.

      • allServices

        public java.util.Collection<ZeroConfService> allServices()
        A list of published ZeroConfServices
        Returns:
        Collection of ZeroConfServices

      • getDNSes

        java.util.HashMap<java.net.InetAddress,​javax.jmdns.JmDNS> getDNSes()
        The list of JmDNS handlers. This is package private.
        Returns:
        a HashMap of JmDNS objects, accessible by InetAddress keys.

      • hostName

        @Nonnull
public static java.lang.String hostName​(@Nonnull
                                        java.lang.String string)
        Return an RFC 1123 compliant host name in all lower-case punycode from a given string.

        RFC 1123 mandates that host names contain only the ASCII characters a-z, digits, minus signs ("-") and that the host name be not longer than 63 characters.

        Punycode converts non-ASCII characters into an ASCII encoding per RFC 3492, so this method repeatedly converts the name into punycode, shortening the name, until the punycode converted name is 63 characters or less in length.

        If the input string cannot be converted to puny code, or is an empty string, the input is replaced with NodeIdentity.networkIdentity().

        The algorithm for converting the input is:

        1. Convert to lower case using the Locale.ROOT locale.
        2. Remove any leading whitespace, dots ("."), underscores ("_"), and minus signs ("-")
        3. Truncate to 63 characters if necessary
        4. Convert whitespace, dots ("."), and underscores ("_") to minus signs ("-")
        5. Repeatedly convert to punycode, removing the last character as needed until the punycode is 63 characters or less
        6. Repeat process with NodeIdentity#networkIdentity() as input if above never yields a usable host name
        Parameters:
        string - String to convert to host name
        Returns:
        An RFC 1123 compliant host name

      • hostName

        public java.lang.String hostName​(java.net.InetAddress address)
        Return the system name or "computer" if the system name cannot be determined. This method returns the first part of the fully qualified domain name from FQDN(java.net.InetAddress).
        Parameters:
        address - The InetAddress for the host name.
        Returns:
        The hostName associated with the first interface encountered.

      • FQDN

        public java.lang.String FQDN​(java.net.InetAddress address)
        Return the fully qualified domain name or "computer" if the system name cannot be determined. This method uses the JmDNS.getHostName() method to get the name.
        Parameters:
        address - The InetAddress for the FQDN.
        Returns:
        The fully qualified domain name.

      • dispose

        public void dispose()
        Description copied from interface: Disposable
        Called when disposing of a disposable.

        Note there are no assurances this method will not be called multiple times against a single instance of this Disposable. It is the responsibility of this Disposable to protect itself and the application from ensuring that calling this method multiple times has no unwanted side effects.

        Specified by:
        dispose in interface Disposable