// Copyright 2003-2005 Arthur van Hoff, Rick Blair
// Licensed under Apache License version 2.0
// Original license LGPL
package javax.jmdns;
import java.net.Inet4Address;
import java.net.Inet6Address;
import java.net.InetAddress;
import java.util.Enumeration;
import java.util.Map;
import javax.jmdns.impl.ServiceInfoImpl;
/**
* <p>
* The fully qualified service name is build using up to 5 components with the
* following structure:
*
* <pre>
* <app>.<protocol>.<servicedomain>.<parentdomain>.<br/>
* <Instance>.<app>.<protocol>.<servicedomain>.<parentdomain>.<br/>
* <sub>._sub.<app>.<protocol>.<servicedomain>.<parentdomain>.
* </pre>
*
* <ol>
* <li><servicedomain>.<parentdomain>: This is the domain scope of
* the service typically "local.", but this can also be something similar to
* "in-addr.arpa." or "ip6.arpa."</li>
* <li><protocol>: This is either "_tcp" or "_udp"</li>
* <li><app>: This define the application protocol. Typical example are
* "_http", "_ftp", etc.</li>
* <li><Instance>: This is the service name</li>
* <li><sub>: This is the subtype for the application protocol</li>
* </ol>
* </p>
*/
public abstract class ServiceInfo implements Cloneable
{
/**
* This is the no value text byte. According top the specification it is one
* byte with 0 value.
*/
public static final byte[] NO_VALUE = new byte[0];
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param text string describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final String text)
{
return new ServiceInfoImpl(type, name, "", port, 0, 0, false, text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param text string describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final String text)
{
return new ServiceInfoImpl(type, name, subtype, port, 0, 0, false, text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param text string describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final int weight, final int priority, final String text)
{
return new ServiceInfoImpl(type, name, "", port, weight, priority, false, text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param text string describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final int weight, final int priority,
final String text)
{
return new ServiceInfoImpl(type, name, subtype, port, weight, priority, false,
text);
}
/**
* Construct a service description for registering with JmDNS. The
* properties hashtable must map property names to either Strings or byte
* arrays describing the property values.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param props properties describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final int weight, final int priority,
final Map<String, ?> props)
{
return new ServiceInfoImpl(type, name, "", port, weight, priority, false, props);
}
/**
* Construct a service description for registering with JmDNS. The
* properties hashtable must map property names to either Strings or byte
* arrays describing the property values.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param props properties describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final int weight, final int priority,
final Map<String, ?> props)
{
return new ServiceInfoImpl(type, name, subtype, port, weight, priority, false,
props);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param text bytes describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final int weight, final int priority, final byte[] text)
{
return new ServiceInfoImpl(type, name, "", port, weight, priority, false, text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param text bytes describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final int weight, final int priority,
final byte[] text)
{
return new ServiceInfoImpl(type, name, subtype, port, weight, priority, false,
text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param text string describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final int weight, final int priority,
final boolean persistent, final String text)
{
return new ServiceInfoImpl(type, name, "", port, weight, priority, persistent,
text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param text string describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final int weight, final int priority,
final boolean persistent, final String text)
{
return new ServiceInfoImpl(type, name, subtype, port, weight, priority,
persistent, text);
}
/**
* Construct a service description for registering with JmDNS. The
* properties hashtable must map property names to either Strings or byte
* arrays describing the property values.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param props properties describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final int weight, final int priority,
final boolean persistent, final Map<String, ?> props)
{
return new ServiceInfoImpl(type, name, "", port, weight, priority, persistent,
props);
}
/**
* Construct a service description for registering with JmDNS. The
* properties hashtable must map property names to either Strings or byte
* arrays describing the property values.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param props properties describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final int weight, final int priority,
final boolean persistent, final Map<String, ?> props)
{
return new ServiceInfoImpl(type, name, subtype, port, weight, priority,
persistent, props);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param text bytes describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final int port, final int weight, final int priority,
final boolean persistent, final byte[] text)
{
return new ServiceInfoImpl(type, name, "", port, weight, priority, persistent,
text);
}
/**
* Construct a service description for registering with JmDNS.
*
* @param type fully qualified service type name, such as
* <code>_http._tcp.local.</code>.
* @param name unqualified service instance name, such as
* <code>foobar</code>
* @param subtype service subtype see draft-cheshire-dnsext-dns-sd-06.txt
* chapter 7.1 Selective Instance Enumeration
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param text bytes describing the service
* @return new service info
*/
public static ServiceInfo create(final String type, final String name,
final String subtype, final int port, final int weight, final int priority,
final boolean persistent, final byte[] text)
{
return new ServiceInfoImpl(type, name, subtype, port, weight, priority,
persistent, text);
}
/**
* Construct a service description for registering with JmDNS. The
* properties hashtable must map property names to either Strings or byte
* arrays describing the property values.
*
* @param qualifiedNameMap dictionary of values to build the fully qualified
* service name. Mandatory keys are Application and Instance. The
* Domain default is local, the Protocol default is tcp and the
* subtype default is none.
* @param port the local port on which the service runs
* @param weight weight of the service
* @param priority priority of the service
* @param persistent if <code>true</code> ServiceListener.resolveService
* will be called whenever new new information is received.
* @param props properties describing the service
* @return new service info
*/
public static ServiceInfo create(final Map<Fields, String> qualifiedNameMap,
final int port, final int weight, final int priority,
final boolean persistent, final Map<String, ?> props)
{
return new ServiceInfoImpl(qualifiedNameMap, port, weight, priority, persistent,
props);
}
/**
* Returns true if the service info is filled with data.
*
* @return <code>true</code> if the service info has data,
* <code>false</code> otherwise.
*/
public abstract boolean hasData();
/**
* Fully qualified service type name, such as <code>_http._tcp.local.</code>
*
* @return service type name
*/
public abstract String getType();
/**
* Fully qualified service type name with the subtype if appropriate, such
* as <code>_printer._sub._http._tcp.local.</code>
*
* @return service type name
*/
public abstract String getTypeWithSubtype();
/**
* Unqualified service instance name, such as <code>foobar</code> .
*
* @return service name
*/
public abstract String getName();
/**
* The key is used to retrieve service info in hash tables.<br/>
* The key is the lower case qualified name.
*
* @return the key
*/
public abstract String getKey();
/**
* Fully qualified service name, such as
* <code>foobar._http._tcp.local.</code> .
*
* @return qualified service name
*/
public abstract String getQualifiedName();
/**
* Get the name of the server.
*
* @return server name
*/
public abstract String getServer();
/**
* Returns the host IP address string in textual presentation.<br/>
* <b>Note:</b> This can be either an IPv4 or an IPv6 representation.
*
* @return the host raw IP address in a string format.
* @deprecated since 3.2.3
* @see #getHostAddresses()
*/
@Deprecated
public abstract String getHostAddress();
/**
* Returns the host IP addresses string in textual presentation.
*
* @return list of host raw IP address in a string format.
*/
public abstract String[] getHostAddresses();
/**
* Get the host address of the service.<br/>
*
* @return host Internet address
* @deprecated since 3.1.8
* @see #getInetAddresses()
*/
@Deprecated
public abstract InetAddress getAddress();
/**
* Get the InetAddress of the service. This will return the IPv4 if it
* exist, otherwise it return the IPv6 if set.<br/>
* <b>Note:</b> This return null if the service IP address cannot be
* resolved.
*
* @return Internet address
* @deprecated since 3.2.3
* @see #getInetAddresses()
*/
@Deprecated
public abstract InetAddress getInetAddress();
/**
* Get the IPv4 InetAddress of the service.<br/>
* <b>Note:</b> This return null if the service IPv4 address cannot be
* resolved.
*
* @return Internet address
* @deprecated since 3.2.3
* @see #getInet4Addresses()
*/
@Deprecated
public abstract Inet4Address getInet4Address();
/**
* Get the IPv6 InetAddress of the service.<br/>
* <b>Note:</b> This return null if the service IPv6 address cannot be
* resolved.
*
* @return Internet address
* @deprecated since 3.2.3
* @see #getInet6Addresses()
*/
@Deprecated
public abstract Inet6Address getInet6Address();
/**
* Returns a list of all InetAddresses that can be used for this service.
* <p>
* In a multi-homed environment service info can be associated with more
* than one address.
* </p>
*
* @return list of InetAddress objects
*/
public abstract InetAddress[] getInetAddresses();
/**
* Returns a list of all IPv4 InetAddresses that can be used for this
* service.
* <p>
* In a multi-homed environment service info can be associated with more
* than one address.
* </p>
*
* @return list of InetAddress objects
*/
public abstract Inet4Address[] getInet4Addresses();
/**
* Returns a list of all IPv6 InetAddresses that can be used for this
* service.
* <p>
* In a multi-homed environment service info can be associated with more
* than one address.
* </p>
*
* @return list of InetAddress objects
*/
public abstract Inet6Address[] getInet6Addresses();
/**
* Get the port for the service.
*
* @return service port
*/
public abstract int getPort();
/**
* Get the priority of the service.
*
* @return service priority
*/
public abstract int getPriority();
/**
* Get the weight of the service.
*
* @return service weight
*/
public abstract int getWeight();
/**
* Get the text for the service as raw bytes.
*
* @return raw service text
*/
public abstract byte[] getTextBytes();
/**
* Get the text for the service. This will interpret the text bytes as a
* UTF8 encoded string. Will return null if the bytes are not a valid UTF8
* encoded string.<br/>
* <b>Note:</b> Do not use. This method make the assumption that the TXT
* record is one string. This is false. The TXT record is a series of key
* value pairs.
*
* @return service text
* @see #getPropertyNames()
* @see #getPropertyBytes(String)
* @see #getPropertyString(String)
* @deprecated since 3.1.7
*/
@Deprecated
public abstract String getTextString();
/**
* Get the URL for this service. An http URL is created by combining the
* address, port, and path properties.
*
* @return service URL
* @deprecated since 3.2.3
* @see #getURLs()
*/
@Deprecated
public abstract String getURL();
/**
* Get the list of URL for this service. An http URL is created by combining
* the address, port, and path properties.
*
* @return list of service URL
*/
public abstract String[] getURLs();
/**
* Get the URL for this service. An URL is created by combining the
* protocol, address, port, and path properties.
*
* @param protocol requested protocol
* @return service URL
* @deprecated since 3.2.3
* @see #getURLs()
*/
@Deprecated
public abstract String getURL(String protocol);
/**
* Get the list of URL for this service. An URL is created by combining the
* protocol, address, port, and path properties.
*
* @param protocol requested protocol
* @return list of service URL
*/
public abstract String[] getURLs(String protocol);
/**
* Get a property of the service. This involves decoding the text bytes into
* a property list. Returns null if the property is not found or the text
* data could not be decoded correctly.
*
* @param name property name
* @return raw property text
*/
public abstract byte[] getPropertyBytes(final String name);
/**
* Get a property of the service. This involves decoding the text bytes into
* a property list. Returns null if the property is not found, the text data
* could not be decoded correctly, or the resulting bytes are not a valid
* UTF8 string.
*
* @param name property name
* @return property text
*/
public abstract String getPropertyString(final String name);
/**
* Enumeration of the property names.
*
* @return property name enumeration
*/
public abstract Enumeration<String> getPropertyNames();
/**
* Returns a description of the service info suitable for printing.
*
* @return service info description
*/
public abstract String getNiceTextString();
/**
* Set the text for the service. Setting the text will fore a re-announce of
* the service.
*
* @param text the raw byte representation of the text field.
* @exception IllegalStateException if attempting to set the text for a non
* persistent service info.
*/
public abstract void setText(final byte[] text) throws IllegalStateException;
/**
* Set the text for the service. Setting the text will fore a re-announce of
* the service.
*
* @param props a key=value map that will be encoded into raw bytes.
* @exception IllegalStateException if attempting to set the text for a non
* persistent service info.
*/
public abstract void setText(final Map<String, ?> props) throws IllegalStateException;
/**
* Returns <code>true</code> if ServiceListener.resolveService will be
* called whenever new new information is received.
*
* @return the persistent
*/
public abstract boolean isPersistent();
/**
* Returns the domain of the service info suitable for printing.
*
* @return service domain
*/
public abstract String getDomain();
/**
* Returns the protocol of the service info suitable for printing.
*
* @return service protocol
*/
public abstract String getProtocol();
/**
* Returns the application of the service info suitable for printing.
*
* @return service application
*/
public abstract String getApplication();
/**
* Returns the sub type of the service info suitable for printing.
*
* @return service sub type
*/
public abstract String getSubtype();
/**
* Returns a dictionary of the fully qualified name component of this
* service.
*
* @return dictionary of the fully qualified name components
*/
public abstract Map<Fields, String> getQualifiedNameMap();
/*
* (non-Javadoc)
*
* @see java.lang.Object#clone()
*/
@Override
public ServiceInfo clone()
{
try
{
return (ServiceInfo) super.clone();
}
catch (CloneNotSupportedException exception)
{
// clone is supported
return null;
}
}
/**
* Fields for the fully qualified map.
*/
public enum Fields
{
/**
* Domain Field.
*/
Domain,
/**
* Protocol Field.
*/
Protocol,
/**
* Application Field.
*/
Application,
/**
* Instance Field.
*/
Instance,
/**
* Subtype Field.
*/
Subtype
}
}