Package org.apache.commons.net

Class DatagramSocketClient

java.lang.Object

org.apache.commons.net.DatagramSocketClient

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

CharGenUDPClient, DaytimeUDPClient, DiscardUDPClient, NTPUDPClient, TFTP, TimeUDPClient

public abstract class DatagramSocketClient
extends java.lang.Object
implements java.lang.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 java.net.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.
private java.nio.charset.Charset	charset	Charset to use for byte IO.
private static DatagramSocketFactory	DEFAULT_SOCKET_FACTORY	The default DatagramSocketFactory shared by all DatagramSocketClient instances.

Constructor Summary

Constructors

Constructor	Description
DatagramSocketClient()	Constructs a new instance.

Method Summary

Modifier and Type	Method	Description
protected java.net.DatagramSocket	checkOpen()	Gets the non-null DatagramSocket or throws NullPointerException.
void	close()	Closes the DatagramSocket used for the connection.
java.nio.charset.Charset	getCharset()	Gets the charset.
java.lang.String	getCharsetName()	Deprecated. Use getCharset() instead
int	getDefaultTimeout()	Deprecated. Use getDefaultTimeoutDuration().
java.time.Duration	getDefaultTimeoutDuration()	Gets the default timeout duration that is used when opening a socket.
java.net.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().
java.time.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, java.net.InetAddress localAddress)	Opens a DatagramSocket at the specified address on the local host at a specified port.
void	setCharset(java.nio.charset.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(java.time.Duration timeout)	Sets the default timeout in to use when opening a socket.
void	setSoTimeout(int timeout)	Deprecated. Use setSoTimeout(Duration).
void	setSoTimeout(java.time.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 Detail

DEFAULT_SOCKET_FACTORY

private static final DatagramSocketFactory DEFAULT_SOCKET_FACTORY

The default DatagramSocketFactory shared by all DatagramSocketClient instances.

charset

private java.nio.charset.Charset charset

Charset to use for byte IO.

_timeout_

protected int _timeout_

The timeout to use after opening a socket.

_socket_

protected java.net.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 Detail

DatagramSocketClient

public DatagramSocketClient()

Constructs a new instance. Initializes _socket_ to null, _timeout_ to 0, and _isOpen_ to false.

Method Detail

checkOpen

protected java.net.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 java.lang.AutoCloseable

getCharset

public java.nio.charset.Charset getCharset()

Gets the charset.

Returns:

the charset.

Since:

3.3

getCharsetName

@Deprecated
public java.lang.String getCharsetName()

Deprecated.

Use getCharset() instead

Gets the charset name.

Returns:

the charset name.

Since:

3.3

getDefaultTimeout

@Deprecated
public int getDefaultTimeout()

Deprecated.

Use getDefaultTimeoutDuration().

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.

getDefaultTimeoutDuration

public java.time.Duration getDefaultTimeoutDuration()

Gets the default timeout duration that is used when opening a socket.

Returns:

The default timeout duration that is used when opening a socket.

Since:

3.13.0

getLocalAddress

public java.net.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 java.net.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:

java.net.SocketException - if an error getting the timeout.

getSoTimeoutDuration

public java.time.Duration getSoTimeoutDuration()
                                        throws java.net.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:

java.net.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 java.net.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:

java.net.SocketException - If the socket could not be opened or the timeout could not be set.

open

public void open(int port)
          throws java.net.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:

java.net.SocketException - If the socket could not be opened or the timeout could not be set.

open

public void open(int port,
                 java.net.InetAddress localAddress)
          throws java.net.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:

java.net.SocketException - If the socket could not be opened or the timeout could not be set.

setCharset

public void setCharset(java.nio.charset.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(java.time.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(java.time.Duration timeout)
                  throws java.net.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:

java.net.SocketException - if an error setting the timeout.

Since:

3.10.0

setSoTimeout

@Deprecated
public void setSoTimeout(int timeout)
                  throws java.net.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:

java.net.SocketException - if an error setting the timeout.