README

UdpSocket, MIT (c) 2019-2025 miktim@mail.ru  

Java SE 7+ UDP broadcast/unicast/multicast sender/receiver  

The UDP protocol does not guarantee datagram delivery, ordering, or duplicate protection.
The maximum safe UDP payload size is ~508 bytes.  

Release notes:
  - don't forget to open the required UDP port in your firewall;
  - the UdpSocket type (broadcast/unicast/multicast) is determined by the requested address (inetAddr);
  - non-multicast IPv4 addresses ending in .255 are considered broadcast;
  - multicast sockets are created with loopback disabled and one hop;
  - DO NOT disable datagram socket timeout.

The jar ./dist/udpsocket-... file was generated with debugging info using JDK1.8 for target JDK1.7

package org.miktim.udpsocket;

Overview:

  Class UdpSocket extends Thread implements Closeable, AutoCloseable;

    Constants:
      static final String VERSION = "3.1.2";
  
    Constructors:
      UdpSocket(int port) throws IOException; 
        - creates broadcast socket (255.255.255.255)
        - binds it to 0.0.0.0:port
      UdpSocket(int port, InetAddress inetAddr) throws IOException;
        - creates socket, joins multicast group if any
        - binds socket to 0.0.0.0:port
      UdpSocket(int port, InetAddress inetAddr, InetAddress localAddr) throws IOException;
        - creates socket, joins multicast group if any
        - binds socket to localAddr:port
      UdpSocket(int port, InetAddress inetAddr, SocketAddress socketAddr) throws IOException;
        - creates socket, joins multicast group if any
        - binds socket to socketAddr

    Methods:
      static boolean isAvailable(int port);
        - checks whether the port is available.
      static boolean seemsBroadcast(InetAddress inetAddr);
        - the address is considered broadcast

      static void send(byte[] buf, int len, int port, InetAddress inetAddr) throws IOException;
        - sends a datagram to the remote inetAddr:port, binds to the 0.0.0.0:port
      static void send(byte[] buf, int len, int port, InetAddress inetAddr, InetAddress localAddr) throws IOException;
        - sends a datagram, binds to the localAddr:port
      static void send(byte[] buf, int len, int port, InetAddress inetAddr, SocketAddress socketAddr) throws IOException;
        - sends a datagram, binds to the socketAddr

      void send(byte[] buf) throws IOException;
        - sends datagram to inetAddr, port
      void send(byte[] buf, int len) throws IOException;
        - sends datagram to inetAddr, port

      void setPayloadSize(int size); 
        - sets the payload buffer length for receiving packets
      int getPayloadSize();
        - default: 1500 bytes

      void receive(UdpSocket.Handler handler) throws IOException; 
        - calls handler.onStart, starts receiving datagrams

      void close();
        - [stops receiving, calls handler.onClose,] [leaves multicast group,] [disconnect,] close socket

      boolean isOpen(); 
      boolean isReceiving();
      boolean isMulticast();
        - returns true if the inetAddr is multicast
      boolean isBroadcast();
        - returns true if the inetAddr seems broadcast
      InetAddress getInetAddress();
        - returns the inetAddr argument;
      int getPort();
        - returns the port argument;
      InetAddress getLocalAddress();
        - returns the local address to which the socket is bound.
      void setReuseAddress(boolean on);
        - enable/disable reuse of this socket
      boolean getReuseAddress();
        - enabled by default

      DatagramSocket getDatagramSocket();

      String toString()
        - datagram/multicast SOCKET info

    Interface UdpSocket.Handler:
      void onStart(UdpSocket socket);
      void onPacket(UdpSocket socket, DatagramPacket packet);
      void onError(UdpSocket socket, Exception e);
      void onClose(UdpSocket socket); 
        - called BEFORE closing the socket

Helpful Links:  
  - using multicast: 
      https://docs.oracle.com/cd/E23824_01/html/821-1602/sockets-137.html  
  - IANA address and port registry:  
      https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml  
      https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml