Package jmri.util.zeroconf

Class ZeroConfServiceManager

java.lang.Object

jmri.util.zeroconf.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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	ZeroConfServiceManager.NetworkListener
static class	ZeroConfServiceManager.Protocol

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static java.util.HashMap<java.net.InetAddress,javax.jmdns.JmDNS>	JMDNS_SERVICES	There can only be one JmDNS object per InetAddress per JVM, so this collection of JmDNS objects is static.
protected ZeroConfServiceManager.NetworkListener	networkListener
protected ZeroConfPreferences	preferences
protected java.util.HashMap<java.lang.String,ZeroConfService>	services
protected java.lang.Runnable	shutDownTask

Constructor Summary

Constructors

Constructor	Description
ZeroConfServiceManager()

Method Summary

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

Field Detail

JMDNS_SERVICES

static final java.util.HashMap<java.net.InetAddress,javax.jmdns.JmDNS> JMDNS_SERVICES

There can only be one JmDNS object per InetAddress per JVM, so this collection of JmDNS objects is static. All access must be through getDNSes() to ensure this is populated correctly.

services

protected final java.util.HashMap<java.lang.String,ZeroConfService> services

networkListener

protected final ZeroConfServiceManager.NetworkListener networkListener

shutDownTask

protected final java.lang.Runnable shutDownTask

preferences

protected final ZeroConfPreferences preferences

Constructor Detail

ZeroConfServiceManager

public ZeroConfServiceManager()

Method Detail

create

public ZeroConfService create(java.lang.String type,
                              int port)

Create a ZeroConfService with the minimal required settings. This method calls create(java.lang.String, int, java.util.HashMap) with an empty props HashMap.

Parameters:

type - The service protocol

port - The port the service runs over

Returns:

A new unpublished ZeroConfService, or an existing service

See Also:

create(java.lang.String, java.lang.String, int, int, int, java.util.HashMap)

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.

getAddresses

@Nonnull
public java.util.Set<java.net.InetAddress> getAddresses()

Get all addresses that JmDNS instances can be created for excluding loopback addresses.

Returns:

the addresses

See Also:

getAddresses(jmri.util.zeroconf.ZeroConfServiceManager.Protocol), getAddresses(jmri.util.zeroconf.ZeroConfServiceManager.Protocol, boolean, boolean)

getAddresses

@Nonnull
public java.util.Set<java.net.InetAddress> getAddresses(ZeroConfServiceManager.Protocol protocol)

Get all addresses that JmDNS instances can be created for excluding loopback addresses.

Parameters:

protocol - the Internet protocol

Returns:

the addresses

See Also:

getAddresses(), getAddresses(jmri.util.zeroconf.ZeroConfServiceManager.Protocol, boolean, boolean)

getAddresses

@Nonnull
public 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.

Parameters:

protocol - the IP protocol addresses to return

useLinkLocal - true to include link-local addresses; false otherwise

useLoopback - true to include loopback addresses; false otherwise

Returns:

the addresses

See Also:

getAddresses(), getAddresses(jmri.util.zeroconf.ZeroConfServiceManager.Protocol)

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.

getPreferences

public ZeroConfPreferences getPreferences()

isPublished

public boolean isPublished(ZeroConfService service)

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