Package org.apache.commons.net

# Class DatagramSocketClient

java.lang.Object
org.apache.commons.net.DatagramSocketClient

All Implemented Interfaces:
  `AutoCloseable`

Direct Known Subclasses:
  `CharGenUDPClient`, `DaytimeUDPClient`, `DiscardUDPClient`, `NTPUDPClient`, `TFTP`, `TimeUDPClient`

public abstract class DatagramSocketClient extends Object implements AutoCloseable
The DatagramSocketClient provides the basic operations that are required of client objects accessing datagram sockets. It is meant to be subclassed to avoid having to rewrite the same code over and over again to open a socket, close a socket, set timeouts, etc. Of special note is the `setDatagramSocketFactory)` method, which allows you to control the type of DatagramSocket the DatagramSocketClient creates for network communications. This is especially useful for adding things like proxy support as well as better support for applets. For example, you could create a `DatagramSocketFactory` that requests browser security capabilities before creating a socket. All classes derived from DatagramSocketClient should use the `_socketFactory_` member variable to create DatagramSocket instances rather than instantiating them by directly invoking a constructor. By honoring this contract you guarantee that a user will always be able to provide his own Socket implementations by substituting his own SocketFactory.

See Also:
  - `DatagramSocketFactory`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected boolean`
  `_isOpen_`
  A status variable indicating if the client's socket is currently open.
  `protected DatagramSocket`
  `_socket_`
  The datagram socket used for the connection.
  `protected DatagramSocketFactory`
  `_socketFactory_`
  The datagram socket's DatagramSocketFactory.
  `protected int`
  `_timeout_`
  The timeout to use after opening a socket.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DatagramSocketClient()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected DatagramSocket`
  `checkOpen()`
  Gets the non-null DatagramSocket or throws `NullPointerException`.
  `void`
  `close()`
  Closes the DatagramSocket used for the connection.
  `Charset`
  `getCharset()`
  Gets the charset.
  `String`
  `getCharsetName()`
  Deprecated.
  Use `getCharset()` instead
  `int`
  `getDefaultTimeout()`
  Gets the default timeout in milliseconds that is used when opening a socket.
  `InetAddress`
  `getLocalAddress()`
  Gets the local address to which the client's socket is bound.
  `int`
  `getLocalPort()`
  Gets the port number of the open socket on the local host used for the connection.
  `int`
  `getSoTimeout()`
  Deprecated.
  Use `getSoTimeoutDuration()`.
  `Duration`
  `getSoTimeoutDuration()`
  Gets the timeout duration of the currently opened socket.
  `boolean`
  `isOpen()`
  Tests whether the client has a currently open socket.
  `void`
  `open()`
  Opens a DatagramSocket on the local host at the first available port.
  `void`
  `open(int port)`
  Opens a DatagramSocket on the local host at a specified port.
  `void`
  `open(int port, InetAddress localAddress)`
  Opens a DatagramSocket at the specified address on the local host at a specified port.
  `void`
  `setCharset(Charset charset)`
  Sets the charset.
  `void`
  `setDatagramSocketFactory(DatagramSocketFactory factory)`
  Sets the DatagramSocketFactory used by the DatagramSocketClient to open DatagramSockets.
  `void`
  `setDefaultTimeout(int timeout)`
  Deprecated.
  Use `setDefaultTimeout(Duration)`.
  `void`
  `setDefaultTimeout(Duration timeout)`
  Sets the default timeout in to use when opening a socket.
  `void`
  `setSoTimeout(int timeout)`
  Deprecated.
  Use `setSoTimeout(Duration)`.
  `void`
  `setSoTimeout(Duration timeout)`
  Sets the timeout duration of a currently open connection.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### _timeout_

    protected int _timeout_
    The timeout to use after opening a socket.

  - ### _socket_

    protected DatagramSocket _socket_
    The datagram socket used for the connection.

  - ### _isOpen_

    protected boolean _isOpen_
    A status variable indicating if the client's socket is currently open.

  - ### _socketFactory_

    protected DatagramSocketFactory _socketFactory_
    The datagram socket's DatagramSocketFactory.

- ## Constructor Details

  - ### DatagramSocketClient

    public DatagramSocketClient()
    Constructs a new instance. Initializes _socket_ to null, _timeout_ to 0, and _isOpen_ to false.

- ## Method Details

  - ### checkOpen

    protected DatagramSocket checkOpen()
    Gets the non-null DatagramSocket or throws `NullPointerException`.

    This method does not allocate resources.

    Returns:
      the non-null DatagramSocket.
    Since:
      3.10.0

  - ### close

    public void close()
    Closes the DatagramSocket used for the connection. You should call this method after you've finished using the class instance and also before you call `open()` again. _isOpen_ is set to false and _socket_ is set to null.
    Specified by:
      `close` in interface `AutoCloseable`

  - ### getCharset

    public Charset getCharset()
    Gets the charset.
    Returns:
      the charset.
    Since:
      3.3

  - ### getCharsetName

    @Deprecated public String getCharsetName()
    Deprecated.
    Use `getCharset()` instead
    Gets the charset name.
    Returns:
      the charset name.
    Since:
      3.3

  - ### getDefaultTimeout

    public int getDefaultTimeout()
    Gets the default timeout in milliseconds that is used when opening a socket.
    Returns:
      The default timeout in milliseconds that is used when opening a socket.

  - ### getLocalAddress

    public InetAddress getLocalAddress()
    Gets the local address to which the client's socket is bound. If you call this method when the client socket is not open, a NullPointerException is thrown.
    Returns:
      The local address to which the client's socket is bound.

  - ### getLocalPort

    public int getLocalPort()
    Gets the port number of the open socket on the local host used for the connection. If you call this method when the client socket is not open, a NullPointerException is thrown.
    Returns:
      The port number of the open socket on the local host used for the connection.

  - ### getSoTimeout

    @Deprecated public int getSoTimeout() throws SocketException
    Deprecated.
    Use `getSoTimeoutDuration()`.
    Gets the timeout in milliseconds of the currently opened socket. If you call this method when the client socket is not open, a NullPointerException is thrown.
    Returns:
      The timeout in milliseconds of the currently opened socket.
    Throws:
      `SocketException` - if an error getting the timeout.

  - ### getSoTimeoutDuration

    public Duration getSoTimeoutDuration() throws SocketException
    Gets the timeout duration of the currently opened socket. If you call this method when the client socket is not open, a NullPointerException is thrown.
    Returns:
      The timeout in milliseconds of the currently opened socket.
    Throws:
      `SocketException` - if an error getting the timeout.

  - ### isOpen

    public boolean isOpen()
    Tests whether the client has a currently open socket.
    Returns:
      True if the client has a currently open socket, false otherwise.

  - ### open

    public void open() throws SocketException
    Opens a DatagramSocket on the local host at the first available port. Also sets the timeout on the socket to the default timeout set by `setDefaultTimeout()`.

    _isOpen_ is set to true after calling this method and _socket_ is set to the newly opened socket.

    Throws:
      `SocketException` - If the socket could not be opened or the timeout could not be set.

  - ### open

    public void open(int port) throws SocketException
    Opens a DatagramSocket on the local host at a specified port. Also sets the timeout on the socket to the default timeout set by `setDefaultTimeout()`.

    _isOpen_ is set to true after calling this method and _socket_ is set to the newly opened socket.

    Parameters:
      `port` - The port to use for the socket.
    Throws:
      `SocketException` - If the socket could not be opened or the timeout could not be set.

  - ### open

    public void open(int port, InetAddress localAddress) throws SocketException
    Opens a DatagramSocket at the specified address on the local host at a specified port. Also sets the timeout on the socket to the default timeout set by `setDefaultTimeout()`.

    _isOpen_ is set to true after calling this method and _socket_ is set to the newly opened socket.

    Parameters:
      `port` - The port to use for the socket.
      `localAddress` - The local address to use.
    Throws:
      `SocketException` - If the socket could not be opened or the timeout could not be set.

  - ### setCharset

    public void setCharset(Charset charset)
    Sets the charset.
    Parameters:
      `charset` - the charset.
    Since:
      3.3

  - ### setDatagramSocketFactory

    public void setDatagramSocketFactory(DatagramSocketFactory factory)
    Sets the DatagramSocketFactory used by the DatagramSocketClient to open DatagramSockets. If the factory value is null, then a default factory is used (only do this to reset the factory after having previously altered it).
    Parameters:
      `factory` - The new DatagramSocketFactory the DatagramSocketClient should use.

  - ### setDefaultTimeout

    public void setDefaultTimeout(Duration timeout)
    Sets the default timeout in to use when opening a socket. After a call to open, the timeout for the socket is set using this value. This method should be used prior to a call to `open()` and should not be confused with `setSoTimeout()` which operates on the currently open socket. _timeout_ contains the new timeout value.
    Parameters:
      `timeout` - The timeout durations to use for the datagram socket connection.

  - ### setDefaultTimeout

    @Deprecated public void setDefaultTimeout(int timeout)
    Deprecated.
    Use `setDefaultTimeout(Duration)`.
    Sets the default timeout in milliseconds to use when opening a socket. After a call to open, the timeout for the socket is set using this value. This method should be used prior to a call to `open()` and should not be confused with `setSoTimeout()` which operates on the currently open socket. _timeout_ contains the new timeout value.
    Parameters:
      `timeout` - The timeout in milliseconds to use for the datagram socket connection.

  - ### setSoTimeout

    public void setSoTimeout(Duration timeout) throws SocketException
    Sets the timeout duration of a currently open connection. Only call this method after a connection has been opened by `open()`.
    Parameters:
      `timeout` - The timeout in milliseconds to use for the currently open datagram socket connection.
    Throws:
      `SocketException` - if an error setting the timeout.
    Since:
      3.10.0

  - ### setSoTimeout

    @Deprecated public void setSoTimeout(int timeout) throws SocketException
    Deprecated.
    Use `setSoTimeout(Duration)`.
    Sets the timeout in milliseconds of a currently open connection. Only call this method after a connection has been opened by `open()`.
    Parameters:
      `timeout` - The timeout in milliseconds to use for the currently open datagram socket connection.
    Throws:
      `SocketException` - if an error setting the timeout.