diff options
Diffstat (limited to 'src/javax/jmdns/JmmDNS.java')
| -rw-r--r-- | src/javax/jmdns/JmmDNS.java | 407 |
1 files changed, 407 insertions, 0 deletions
diff --git a/src/javax/jmdns/JmmDNS.java b/src/javax/jmdns/JmmDNS.java new file mode 100644 index 0000000..1d4d85a --- /dev/null +++ b/src/javax/jmdns/JmmDNS.java @@ -0,0 +1,407 @@ +/** + * + */ +package javax.jmdns; + +import java.io.Closeable; +import java.io.IOException; +import java.net.InetAddress; +import java.util.Map; +import java.util.concurrent.atomic.AtomicReference; + +import javax.jmdns.impl.JmmDNSImpl; + +/** + * <p> + * Java Multihomed Multicast DNS + * </p> + * Uses an underlying {@link JmDNS} instance for each {@link InetAddress} found on this computer.<br/> + * 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 {@link NetworkTopologyListener}).<br/> + * 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. + * <p> + * <b>Note:</b> This API is experimental and may change in the future please let us know what work and what does not work in you application. + * </p> + * + * @author Cédrik Lime, Pierre Frisch + */ +public interface JmmDNS extends Closeable { + + /** + * JmmDNS.Factory enable the creation of new instance of JmmDNS. + */ + public static final class Factory { + private static volatile JmmDNS _instance; + + /** + * This interface defines a delegate to the EOClassDescriptionRegister class to enable subclassing. + */ + public static interface ClassDelegate { + + /** + * Allows the delegate the opportunity to construct and return a different JmmDNS. + * + * @return Should return a new JmmDNS. + * @see #classDelegate() + * @see #setClassDelegate(ClassDelegate anObject) + */ + public JmmDNS newJmmDNS(); + + } + + private static final AtomicReference<ClassDelegate> _databaseClassDelegate = new AtomicReference<ClassDelegate>(); + + private Factory() { + super(); + } + + /** + * Assigns <code>delegate</code> as JmmDNS's class delegate. The class delegate is optional. + * + * @param delegate + * The object to set as JmmDNS's class delegate. + * @see #classDelegate() + * @see JmmDNS.Factory.ClassDelegate + */ + public static void setClassDelegate(ClassDelegate delegate) { + _databaseClassDelegate.set(delegate); + } + + /** + * Returns JmmDNS's class delegate. + * + * @return JmmDNS's class delegate. + * @see #setClassDelegate(ClassDelegate anObject) + * @see JmmDNS.Factory.ClassDelegate + */ + public static ClassDelegate classDelegate() { + return _databaseClassDelegate.get(); + } + + /** + * Returns a new instance of JmmDNS using the class delegate if it exists. + * + * @return new instance of JmmDNS + */ + protected static JmmDNS newJmmDNS() { + JmmDNS dns = null; + ClassDelegate delegate = _databaseClassDelegate.get(); + if (delegate != null) { + dns = delegate.newJmmDNS(); + } + return (dns != null ? dns : new JmmDNSImpl()); + } + + /** + * Return the instance of the Multihommed Multicast DNS. + * + * @return the JmmDNS + */ + public static JmmDNS getInstance() { + if (_instance == null) { + synchronized (Factory.class) { + if (_instance == null) { + _instance = JmmDNS.Factory.newJmmDNS(); + } + } + } + return _instance; + } + } + + /** + * Return the names of the JmDNS instances. + * + * @return list of name of the JmDNS + * @see javax.jmdns.JmDNS#getName() + */ + public abstract String[] getNames(); + + /** + * Return the list HostName associated with this JmmDNS instance. + * + * @return list of host names + * @see javax.jmdns.JmDNS#getHostName() + */ + public abstract String[] getHostNames(); + + /** + * Return the list of addresses of the interface to which this instance of JmmDNS is bound. + * + * @return list of Internet Address + * @exception IOException + * @see javax.jmdns.JmDNS#getInetAddress() + */ + public abstract InetAddress[] getInetAddresses() throws IOException; + + /** + * Return the list of addresses of the interface to which this instance of JmmDNS is bound. + * + * @return list of Internet Address + * @exception IOException + * @see javax.jmdns.JmDNS#getInterface() + * @deprecated do not use this implementation yields unpredictable results use {@link #getInetAddresses()} + */ + @Deprecated + public abstract InetAddress[] getInterfaces() throws IOException; + + /** + * Get service information. If the information is not cached, the method will block until updated information is received on all DNS. + * <p/> + * Usage note: Do not call this method from the AWT event dispatcher thread. You will make the user interface unresponsive. + * + * @param type + * fully qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @return list of service info. If no service info is found the list is empty. + * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String) + */ + public abstract ServiceInfo[] getServiceInfos(String type, String name); + + /** + * Get service information. If the information is not cached, the method will block until updated information is received on all DNS. + * <p/> + * 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @param timeout + * timeout in milliseconds. Typical timeout should be 5s. + * @return list of service info. If no service info is found the list is empty. + * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, long) + */ + public abstract ServiceInfo[] getServiceInfos(String type, 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. + * <p/> + * 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @param persistent + * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. + * @return list of service info. If no service info is found the list is empty. + * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, boolean) + */ + public abstract ServiceInfo[] getServiceInfos(String type, 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. + * <p/> + * 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @param timeout + * timeout in milliseconds. Typical timeout should be 5s. + * @param persistent + * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. + * @return list of service info. If no service info is found the list is empty. + * @see javax.jmdns.JmDNS#getServiceInfo(java.lang.String, java.lang.String, boolean, long) + */ + public abstract ServiceInfo[] getServiceInfos(String type, 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String) + */ + public abstract void requestServiceInfo(String type, 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @param persistent + * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. + * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, boolean) + */ + public abstract void requestServiceInfo(String type, 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @param timeout + * timeout in milliseconds + * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, long) + */ + public abstract void requestServiceInfo(String type, 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code> . + * @param name + * unqualified service name, such as <code>foobar</code> . + * @param persistent + * if <code>true</code> ServiceListener.resolveService will be called whenever new new information is received. + * @param timeout + * timeout in milliseconds + * @see javax.jmdns.JmDNS#requestServiceInfo(java.lang.String, java.lang.String, boolean, long) + */ + public abstract void requestServiceInfo(String type, String name, boolean persistent, long timeout); + + /** + * Listen for service types. + * + * @param listener + * listener for service types + * @exception IOException + * @see javax.jmdns.JmDNS#addServiceTypeListener(javax.jmdns.ServiceTypeListener) + */ + public abstract void addServiceTypeListener(ServiceTypeListener listener) throws IOException; + + /** + * Remove listener for service types. + * + * @param listener + * listener for service types + * @see javax.jmdns.JmDNS#removeServiceTypeListener(javax.jmdns.ServiceTypeListener) + */ + public abstract void removeServiceTypeListener(ServiceTypeListener listener); + + /** + * Listen for services of a given type. The type has to be a fully qualified type name such as <code>_http._tcp.local.</code>. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code>. + * @param listener + * listener for service updates + * @see javax.jmdns.JmDNS#addServiceListener(java.lang.String, javax.jmdns.ServiceListener) + */ + public abstract void addServiceListener(String type, ServiceListener listener); + + /** + * Remove listener for services of a given type. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code>. + * @param listener + * listener for service updates + * @see javax.jmdns.JmDNS#removeServiceListener(java.lang.String, javax.jmdns.ServiceListener) + */ + public abstract void removeServiceListener(String type, ServiceListener listener); + + /** + * 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.<br> + * <b>Note</b> the Service info is cloned for each network interface. + * + * @param info + * service info to register + * @exception IOException + * @see javax.jmdns.JmDNS#registerService(javax.jmdns.ServiceInfo) + */ + public abstract void registerService(ServiceInfo info) throws IOException; + + /** + * Unregister a service. The service should have been registered. + * + * @param info + * service info to remove + * @see javax.jmdns.JmDNS#unregisterService(javax.jmdns.ServiceInfo) + */ + public abstract void unregisterService(ServiceInfo info); + + /** + * Unregister all services. + * + * @see javax.jmdns.JmDNS#unregisterAllServices() + */ + public abstract void unregisterAllServices(); + + /** + * 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. + * + * @param type + * full qualified service type, such as <code>_http._tcp.local.</code>. + * @see javax.jmdns.JmDNS#registerServiceType(java.lang.String) + */ + public abstract void registerServiceType(String type); + + /** + * Returns a list of service infos of the specified type. + * + * @param type + * Service type name, such as <code>_http._tcp.local.</code>. + * @return An array of service instance. + * @see javax.jmdns.JmDNS#list(java.lang.String) + */ + public abstract ServiceInfo[] list(String type); + + /** + * Returns a list of service infos of the specified type. + * + * @param type + * Service type name, such as <code>_http._tcp.local.</code>. + * @param timeout + * timeout in milliseconds. Typical timeout should be 6s. + * @return An array of service instance. + * @see javax.jmdns.JmDNS#list(java.lang.String, long) + */ + public abstract ServiceInfo[] list(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. + * + * @param type + * Service type name, such as <code>_http._tcp.local.</code>. + * @return A dictionary of service info by subtypes. + * @see javax.jmdns.JmDNS#listBySubtype(java.lang.String) + */ + public abstract Map<String, ServiceInfo[]> listBySubtype(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. + * + * @param type + * Service type name, such as <code>_http._tcp.local.</code>. + * @param timeout + * timeout in milliseconds. Typical timeout should be 6s. + * @return A dictionary of service info by subtypes. + * @see javax.jmdns.JmDNS#listBySubtype(java.lang.String, long) + */ + public abstract Map<String, ServiceInfo[]> listBySubtype(String type, long timeout); + + /** + * Listen to network changes. + * + * @param listener + * listener for network changes + */ + public abstract void addNetworkTopologyListener(NetworkTopologyListener listener); + + /** + * Remove listener for network changes. + * + * @param listener + * listener for network changes + */ + public abstract void removeNetworkTopologyListener(NetworkTopologyListener listener); + + /** + * Returns list of network change listeners + * + * @return list of network change listeners + */ + public abstract NetworkTopologyListener[] networkListeners(); + +} |