Module org.newsclub.net.unix

Package org.newsclub.net.unix

Class AFSocket<A extends AFSocketAddress>

java.lang.Object

java.net.Socket

org.newsclub.net.unix.AFSocket<A>

Type Parameters:

A - The concrete AFSocketAddress that is supported by this type.

All Implemented Interfaces:

Closeable, AutoCloseable, AFSocketExtensions, AFSomeSocket, AFSomeSocketThing, FileDescriptorAccess

Direct Known Subclasses:

AFSYSTEMSocket, AFTIPCSocket, AFUNIXSocket, AFVSOCKSocket

public abstract class AFSocket<A extends AFSocketAddress>
extends Socket
implements AFSomeSocket, AFSocketExtensions

junixsocket's base implementation of a Socket.

Author:

Christian Kohlschütter

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	AFSocket.Constructor<A extends AFSocketAddress>	The reference to the constructor of an AFSocket subclass.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AFSocket(AFSocketImpl<A> impl, AFSocketAddressFromHostname<A> afh)	Creates a new AFSocket instance.

Method Summary

Modifier and Type	Method	Description
final void	addCloseable(Closeable closeable)	Registers a Closeable that should be closed when this socket is closed.
final void	bind(SocketAddress bindpoint)	Not supported, since it's not necessary for client sockets.
boolean	checkConnectionClosed()	Probes the status of the socket connection.
final void	close()
final void	connect(SocketAddress endpoint)
final void	connect(SocketAddress endpoint, int timeout)
final AFSocket<A>	connectHook(SocketAddressFilter hook)	Sets the hook for any subsequent call to connect(SocketAddress) or connect(SocketAddress, int) to be the given function.
static final <A extends AFSocketAddress> AFSocket<?>	connectTo(@NonNull A addr)	Creates a new AFSocket and connects it to the given AFSocketAddress using the default implementation suited for that address type.
protected static final <A extends AFSocketAddress> @NonNull AFSocket<A>	connectTo(AFSocket.Constructor<A> constr, A addr)	Creates a new AFSocket and connects it to the given AFSocketAddress.
final void	ensureAncillaryReceiveBufferSize(int minSize)	Ensures a minimum ancillary receive buffer size.
static void	ensureSupported()	Checks if AFSockets are supported by the current Java VM.
static final void	ensureUnsafeSupported()	Checks if the current environment (system platform, native library, etc.) supports "unsafe" operations (as controlled via the AFSocketCapability.CAPABILITY_UNSAFE capability).
final AFSocket<A>	forceConnectAddress(SocketAddress endpoint)	Forces the address to be used for any subsequent call to connect(SocketAddress) to be the given one, regardless of what'll be passed there.
final int	getAncillaryReceiveBufferSize()	Returns the size of the receive buffer for ancillary messages (in bytes).
AFSocketChannel<A>	getChannel()
final FileDescriptor	getFileDescriptor()	Returns the corresponding FileDescriptor.
protected final AFSocketImplExtensions<A>	getImplExtensions()	Returns the internal helper instance for address-specific extensions.
final AFInputStream	getInputStream()
static final String	getLoadedLibrary()	Returns an identifier of the loaded native library, or null if the library hasn't been loaded yet.
final A	getLocalSocketAddress()	Returns the socket's local socket address, or null if unavailable or if there was a problem retrieving it.
final AFOutputStream	getOutputStream()
final A	getRemoteSocketAddress()	Returns the socket's remote socket address, or null if unavailable/not connected, or if there was a problem retrieving it.
static final String	getVersion()	Returns the version of the junixsocket library, as a string, for debugging purposes.
final boolean	isBound()
final boolean	isClosed()
final boolean	isConnected()
static boolean	isRunningOnAndroid()	Checks if we're running on Android (as far as junixsocket is concerned).
static boolean	isSupported()	Returns true iff AFSockets are supported by the current Java VM.
protected abstract AFSocketChannel<A>	newChannel()	Creates a new AFSocketChannel for this socket.
protected static final <A extends AFSocketAddress> AFSocket<A>	newInstance(AFSocket.Constructor<A> constr, AFSocketFactory<A> factory)	Creates a new, unbound AFSocket.
final void	removeCloseable(Closeable closeable)	Unregisters a previously registered Closeable.
final void	setAncillaryReceiveBufferSize(int size)	Sets the size of the receive buffer for ancillary messages (in bytes).
void	setShutdownOnClose(boolean enabled)	Configures whether the socket should be shutdown upon Closeable.close(), which is the default.
protected final Class<? extends AFSocketAddress>	socketAddressClass()	Returns the AFSocketAddress type supported by this socket.
static final boolean	supports(AFSocketCapability capability)	Checks if the current environment (system platform, native library, etc.) supports a given junixsocket capability.
static final boolean	supports(AFUNIXSocketCapability capability)	Deprecated.
final String	toString()

Methods inherited from class java.net.Socket

getInetAddress, getKeepAlive, getLocalAddress, getLocalPort, getOOBInline, getOption, getPort, getReceiveBufferSize, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setOption, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, supportedOptions

Methods inherited from class java.lang.Object

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

Constructor Details

AFSocket

protected AFSocket(AFSocketImpl<A> impl,
 AFSocketAddressFromHostname<A> afh)
            throws SocketException

Creates a new AFSocket instance.

Parameters:

impl - The corresponding SocketImpl class.

afh - The conversion helper to get a socket address from an encoded hostname.

Throws:

SocketException - on error.

Method Details

socketAddressClass

protected final Class<? extends AFSocketAddress> socketAddressClass()

Returns the AFSocketAddress type supported by this socket.

Returns:

The supported AFSocketAddress.

newChannel

protected abstract AFSocketChannel<A> newChannel()

Creates a new AFSocketChannel for this socket.

Returns:

The new instance.

newInstance

protected static final <A extends AFSocketAddress>
AFSocket<A> newInstance(AFSocket.Constructor<A> constr,
 AFSocketFactory<A> factory)
                 throws SocketException

Creates a new, unbound AFSocket. This "default" implementation is a bit "lenient" with respect to the specification. In particular, we may ignore calls to Socket.getTcpNoDelay() and Socket.setTcpNoDelay(boolean).

Type Parameters:

A - The corresponding address type.

Parameters:

constr - The implementation's AFSocket constructor

factory - The corresponding socket factory, or null.

Returns:

A new, unbound socket.

Throws:

SocketException - if the operation fails.

connectTo

protected static final <A extends AFSocketAddress>
@NonNull AFSocket<A> connectTo(AFSocket.Constructor<A> constr,
 A addr)
                        throws IOException

Creates a new AFSocket and connects it to the given AFSocketAddress.

Type Parameters:

A - The corresponding address type.

Parameters:

constr - The implementation's AFSocket constructor

addr - The address to connect to.

Returns:

A new, connected socket.

Throws:

IOException - if the operation fails.

connectTo

public static final <A extends AFSocketAddress>
AFSocket<?> connectTo(@NonNull A addr)
               throws IOException

Creates a new AFSocket and connects it to the given AFSocketAddress using the default implementation suited for that address type.

Type Parameters:

A - The corresponding address type.

Parameters:

addr - The address to connect to.

Returns:

A new, connected socket.

Throws:

IOException - if the operation fails.

bind

public final void bind(SocketAddress bindpoint)
                throws IOException

Not supported, since it's not necessary for client sockets.

Overrides:

bind in class Socket

Throws:

IOException

See Also:

• AFServerSocket

isBound

public final boolean isBound()

Overrides:

isBound in class Socket

isConnected

public final boolean isConnected()

Overrides:

isConnected in class Socket

connect

public final void connect(SocketAddress endpoint)
                   throws IOException

Overrides:

connect in class Socket

Throws:

IOException

connect

public final void connect(SocketAddress endpoint,
 int timeout)
                   throws IOException

Overrides:

connect in class Socket

Throws:

IOException

toString

public final String toString()

Overrides:

toString in class Socket

isSupported

public static boolean isSupported()

Returns true iff AFSockets are supported by the current Java VM. To support AFSockets, a custom JNI library must be loaded that is supplied with junixsocket.

Returns:

true iff supported.

ensureSupported

public static void ensureSupported()
                            throws UnsupportedOperationException

Checks if AFSockets are supported by the current Java VM. If not, an UnsupportedOperationException is thrown.

Throws:

UnsupportedOperationException - if not supported.

getVersion

public static final String getVersion()

Returns the version of the junixsocket library, as a string, for debugging purposes. NOTE: Do not rely on the format of the version identifier, use socket capabilities instead.

Returns:

String The version identifier, or null if it could not be determined.

See Also:

• supports(AFSocketCapability)

getLoadedLibrary

public static final String getLoadedLibrary()

Returns an identifier of the loaded native library, or null if the library hasn't been loaded yet. The identifier is useful mainly for debugging purposes.

Returns:

The identifier of the loaded junixsocket-native library, or null.

isClosed

public final boolean isClosed()

Overrides:

isClosed in class Socket

getAncillaryReceiveBufferSize

public final int getAncillaryReceiveBufferSize()

Description copied from interface: AFSocketExtensions

Returns the size of the receive buffer for ancillary messages (in bytes).

Specified by:

getAncillaryReceiveBufferSize in interface AFSocketExtensions

Returns:

The size.

setAncillaryReceiveBufferSize

public final void setAncillaryReceiveBufferSize(int size)

Description copied from interface: AFSocketExtensions

Sets the size of the receive buffer for ancillary messages (in bytes). To disable handling ancillary messages, set it to 0 (default).

Specified by:

setAncillaryReceiveBufferSize in interface AFSocketExtensions

Parameters:

size - The size.

ensureAncillaryReceiveBufferSize

public final void ensureAncillaryReceiveBufferSize(int minSize)

Description copied from interface: AFSocketExtensions

Ensures a minimum ancillary receive buffer size.

Specified by:

ensureAncillaryReceiveBufferSize in interface AFSocketExtensions

Parameters:

minSize - The minimum size (in bytes).

supports

@Deprecated
public static final boolean supports(AFUNIXSocketCapability capability)

Deprecated.

Checks if the current environment (system platform, native library, etc.) supports a given junixsocket capability. Deprecated. Please use supports(AFSocketCapability) instead. NOTE: The result may or may not be cached from a previous call or from a check upon initialization.

Parameters:

capability - The capability.

Returns:

true if supported.

See Also:

• supports(AFSocketCapability)

supports

public static final boolean supports(AFSocketCapability capability)

Checks if the current environment (system platform, native library, etc.) supports a given junixsocket capability. NOTE: The result may or may not be cached from a previous call or from a check upon initialization.

Parameters:

capability - The capability.

Returns:

true if supported.

ensureUnsafeSupported

public static final void ensureUnsafeSupported()
                                        throws IOException

Checks if the current environment (system platform, native library, etc.) supports "unsafe" operations (as controlled via the AFSocketCapability.CAPABILITY_UNSAFE capability). If supported, the method returns normally. If not supported, an IOException is thrown.

Throws:

IOException - if "unsafe" operations are not supported.

See Also:

• Unsafe

close

public final void close()
                 throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class Socket

Throws:

IOException

addCloseable

public final void addCloseable(Closeable closeable)

Registers a Closeable that should be closed when this socket is closed.

Parameters:

closeable - The closeable.

removeCloseable

public final void removeCloseable(Closeable closeable)

Unregisters a previously registered Closeable.

Parameters:

closeable - The closeable.

getChannel

public AFSocketChannel<A> getChannel()

Overrides:

getChannel in class Socket

getRemoteSocketAddress

public final A getRemoteSocketAddress()

Description copied from interface: AFSomeSocket

Returns the socket's remote socket address, or null if unavailable/not connected, or if there was a problem retrieving it.

Specified by:

getRemoteSocketAddress in interface AFSomeSocket

Overrides:

getRemoteSocketAddress in class Socket

Returns:

The remote socket address, or null.

getLocalSocketAddress

public final A getLocalSocketAddress()

Description copied from interface: AFSomeSocketThing

Returns the socket's local socket address, or null if unavailable or if there was a problem retrieving it.

Specified by:

getLocalSocketAddress in interface AFSomeSocketThing

Overrides:

getLocalSocketAddress in class Socket

Returns:

The local socket address, or null.

getFileDescriptor

public final FileDescriptor getFileDescriptor()
                                       throws IOException

Description copied from interface: FileDescriptorAccess

Returns the corresponding FileDescriptor.

Specified by:

getFileDescriptor in interface FileDescriptorAccess

Returns:

The corresponding FileDescriptor.

Throws:

IOException - on error.

getInputStream

public final AFInputStream getInputStream()
                                   throws IOException

Overrides:

getInputStream in class Socket

Throws:

IOException

getOutputStream

public final AFOutputStream getOutputStream()
                                     throws IOException

Overrides:

getOutputStream in class Socket

Throws:

IOException

getImplExtensions

protected final AFSocketImplExtensions<A> getImplExtensions()

Returns the internal helper instance for address-specific extensions.

Returns:

The helper instance.

Throws:

UnsupportedOperationException - if such extensions are not supported for this address type.

forceConnectAddress

public final AFSocket<A> forceConnectAddress(SocketAddress endpoint)

Forces the address to be used for any subsequent call to connect(SocketAddress) to be the given one, regardless of what'll be passed there.

Parameters:

endpoint - The forced endpoint address.

Returns:

This instance.

connectHook

public final AFSocket<A> connectHook(SocketAddressFilter hook)

Sets the hook for any subsequent call to connect(SocketAddress) or connect(SocketAddress, int) to be the given function. The function can monitor events or even alter the target address.

Parameters:

hook - The function that gets called for each connect call.

Returns:

This instance.

checkConnectionClosed

public boolean checkConnectionClosed()
                              throws IOException

Probes the status of the socket connection. This usually involves checking for isConnected(), and if assumed connected, also sending a zero-length message to the remote.

Returns:

true if the connection is known to be closed, false if the connection is open/not closed or the condition is unknown.

Throws:

IOException - on an unexpected error.

isRunningOnAndroid

public static boolean isRunningOnAndroid()

Checks if we're running on Android (as far as junixsocket is concerned).

Returns:

true if running on Android.

setShutdownOnClose

public void setShutdownOnClose(boolean enabled)

Description copied from interface: AFSomeSocketThing

Configures whether the socket should be shutdown upon Closeable.close(), which is the default.

Specified by:

setShutdownOnClose in interface AFSomeSocketThing

Parameters:

enabled - true if enabled.