Module org.newsclub.net.unix

Package org.newsclub.net.unix

Class AFSocketAddress

java.lang.Object

java.net.SocketAddress

java.net.InetSocketAddress

org.newsclub.net.unix.AFSocketAddress

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AFGenericSocketAddress, AFSYSTEMSocketAddress, AFTIPCSocketAddress, AFUNIXSocketAddress, AFVSOCKSocketAddress

@Immutable
public abstract class AFSocketAddress
extends InetSocketAddress

Some SocketAddress that is supported by junixsocket, such as AFUNIXSocketAddress.

Author:

Christian Kohlschütter

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static interface	AFSocketAddress.AFSocketAddressConstructor<T extends AFSocketAddress>	A reference to the constructor of an AFSocketAddress subclass.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AFSocketAddress(int port, byte[] socketAddress, ByteBuffer nativeAddress, AFAddressFamily<?> af)	Creates a new socket address.

Method Summary

Modifier and Type	Method	Description
boolean	covers(AFSocketAddress other)	Checks if the given address could cover another address.
final AFAddressFamily<?>	getAddressFamily()	Returns the corresponding AFAddressFamily.
protected final byte[]	getBytes()	Returns the (non-native) byte-level representation of this address.
abstract File	getFile()	Returns the File corresponding with this address, if possible.
protected final InetAddress	getInetAddress()	Wraps this address as an InetAddress.
protected static final InetAddress	getInetAddress(FileDescriptor fdesc, boolean peerName, AFAddressFamily<?> af)	Wraps the socket name/peer name of a file descriptor as an InetAddress.
protected final InetAddress	getInetAddress(AFAddressFamily<?> af)	Wraps an address as an InetAddress.
protected static final <A extends AFSocketAddress> @Nullable A	getSocketAddress(FileDescriptor fdesc, boolean requestPeerName, int port, AFAddressFamily<A> af)	Gets the socket name/peer name of a file descriptor as an AFSocketAddress.
abstract boolean	hasFilename()	Checks if the address can be resolved to a File.
protected static final boolean	isSupportedAddress(InetAddress addr, AFAddressFamily<?> af)	Checks if the given address is supported by this address family.
protected static boolean	isUseDeserializationForInit()	Checks if AFSocketAddress instantiation should be performed via deserialization.
AFServerSocket<?>	newBoundServerSocket()	Creates a new server socket bound to this address.
AFSocket<?>	newConnectedSocket()	Creates a new socket connected to this address.
protected static <A extends AFSocketAddress> A	newDeserializedAFSocketAddress(int port, byte[] socketAddress, ByteBuffer nativeAddress, AFAddressFamily<A> af, AFSocketAddress.AFSocketAddressConstructor<A> constructor)	Returns a new AFSocketAddress instance via deserialization.
AFServerSocket<?>	newForceBoundServerSocket()	Creates a new server socket force-bound to this address (i.e., any additional call to ServerSocket.bind(SocketAddress) will ignore the passed address and use this one instead.
static AFSocketAddress	of(URI u)	Tries to parse the given URI and return a corresponding AFSocketAddress for it.
static AFSocketAddress	of(URI u, int overridePort)	Tries to parse the given URI and return a corresponding AFSocketAddress for it.
protected static int	parseUnsignedInt(String s, int radix)	Parses the string argument as an unsigned integer in the radix specified by the second argument.
protected static final <A extends AFSocketAddress> A	resolveAddress(byte[] socketAddress, int port, AFAddressFamily<A> af)	Resolves a junixsocket-specific byte-array representation of an AFSocketAddress to an actual AFSocketAddress instance, possibly reusing a cached instance.
@Nullable String	toSocatAddressString(AFSocketType socketType, AFSocketProtocol socketProtocol)	Returns a address string that can be used with socat's SOCKET-CONNECT, SOCKET-LISTEN, SOCKET-DATAGRAM, etc., address types, or null if the address type is not natively supported by this platform.
URI	toURI(String scheme, URI template)	Tries to create a URI based on this AFSocketAddress.
protected static final <A extends AFSocketAddress> @NonNull A	unwrap(String hostname, int port, AFAddressFamily<A> af)	Returns an AFSocketAddress given a special InetAddress hostname that encodes the byte sequence of an AF_UNIX etc.
protected static final <A extends AFSocketAddress> @NonNull A	unwrap(InetAddress address, int port, AFAddressFamily<A> af)	Returns an AFSocketAddress given a special InetAddress that encodes the byte sequence of an AF_UNIX etc.
final InetAddress	wrapAddress()	Returns a "special" InetAddress that contains information about this AFSocketAddress.
final void	writeNativeAddressTo(ByteBuffer buf)	Writes the native (system-level) representation of this address to the given buffer.

Methods inherited from class java.net.InetSocketAddress

createUnresolved, equals, getAddress, getHostName, getHostString, getPort, hashCode, isUnresolved, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

AFSocketAddress

protected AFSocketAddress(int port,
 byte[] socketAddress,
 ByteBuffer nativeAddress,
 AFAddressFamily<?> af)
                   throws SocketException

Creates a new socket address.

Parameters:

port - The port.

socketAddress - The socket address in junixsocket-specific byte-array representation.

nativeAddress - The socket address in system-native representation.

af - The address family.

Throws:

SocketException - on error.

Method Details

newDeserializedAFSocketAddress

protected static <A extends AFSocketAddress> A newDeserializedAFSocketAddress(int port,
 byte[] socketAddress,
 ByteBuffer nativeAddress,
 AFAddressFamily<A> af,
 AFSocketAddress.AFSocketAddressConstructor<A> constructor)
                                                                       throws SocketException

Returns a new AFSocketAddress instance via deserialization. This is a trick to workaround certain environments that do not allow the construction of InetSocketAddress instances without trying DNS resolution.

Type Parameters:

A - The subclass (must be a direct subclass of AFSocketAddress).

Parameters:

port - The port to use.

socketAddress - The junixsocket representation of the socket address.

nativeAddress - The system-native representation of the socket address, or null.

af - The address family, corresponding to the subclass

constructor - The constructor to use as fallback

Returns:

The new instance.

Throws:

SocketException - on error.

isUseDeserializationForInit

protected static boolean isUseDeserializationForInit()

Checks if AFSocketAddress instantiation should be performed via deserialization.

Returns:

true if so.

See Also:

• newDeserializedAFSocketAddress(int, byte[], ByteBuffer, AFAddressFamily, AFSocketAddressConstructor)

hasFilename

public abstract boolean hasFilename()

Checks if the address can be resolved to a File.

Returns:

true if the address has a filename.

getFile

public abstract File getFile()
                      throws FileNotFoundException

Returns the File corresponding with this address, if possible. A FileNotFoundException is thrown if there is no filename associated with the address, which applies to addresses in the abstract namespace, for example.

Returns:

The filename.

Throws:

FileNotFoundException - if the address is not associated with a filename.

getAddressFamily

public final AFAddressFamily<?> getAddressFamily()

Returns the corresponding AFAddressFamily.

Returns:

The address family instance.

getInetAddress

protected static final InetAddress getInetAddress(FileDescriptor fdesc,
 boolean peerName,
 AFAddressFamily<?> af)

Wraps the socket name/peer name of a file descriptor as an InetAddress.

Parameters:

fdesc - The file descriptor.

peerName - If true, the remote peer name (instead of the local name) is retrieved.

af - The address family.

Returns:

The InetAddress.

getSocketAddress

protected static final <A extends AFSocketAddress>
@Nullable A getSocketAddress(FileDescriptor fdesc,
 boolean requestPeerName,
 int port,
 AFAddressFamily<A> af)

Gets the socket name/peer name of a file descriptor as an AFSocketAddress.

Type Parameters:

A - The corresponding address type.

Parameters:

fdesc - The file descriptor.

requestPeerName - If true, the remote peer name (instead of the local name) is retrieved.

port - The port.

af - The address family.

Returns:

The InetAddress.

getBytes

protected final byte[] getBytes()

Returns the (non-native) byte-level representation of this address.

Returns:

The byte array.

wrapAddress

public final InetAddress wrapAddress()

Returns a "special" InetAddress that contains information about this AFSocketAddress. IMPORTANT: This InetAddress does not properly compare (using InetAddress.equals(Object) and InetAddress.hashCode()). It should be used exclusively to circumvent existing APIs like DatagramSocket that only accept/return InetAddress and not arbitrary SocketAddress types.

Returns:

The "special" InetAddress.

resolveAddress

protected static final <A extends AFSocketAddress>
A resolveAddress(byte[] socketAddress,
 int port,
 AFAddressFamily<A> af)
          throws SocketException

Resolves a junixsocket-specific byte-array representation of an AFSocketAddress to an actual AFSocketAddress instance, possibly reusing a cached instance.

Type Parameters:

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

Parameters:

socketAddress - The socket address in junixsocket-specific byte-array representation.

port - The port.

af - The address family.

Returns:

The instance.

Throws:

SocketException - on error.

getInetAddress

protected final InetAddress getInetAddress(AFAddressFamily<?> af)

Wraps an address as an InetAddress.

Parameters:

af - The address family.

Returns:

The InetAddress.

getInetAddress

protected final InetAddress getInetAddress()

Wraps this address as an InetAddress.

Returns:

The InetAddress.

unwrap

protected static final <A extends AFSocketAddress>
@NonNull A unwrap(InetAddress address,
 int port,
 AFAddressFamily<A> af)
           throws SocketException

Returns an AFSocketAddress given a special InetAddress that encodes the byte sequence of an AF_UNIX etc. socket address, like those returned by wrapAddress().

Type Parameters:

A - The corresponding address type.

Parameters:

address - The "special" InetAddress.

port - The port (use 0 for "none").

af - The address family.

Returns:

The AFSocketAddress instance.

Throws:

SocketException - if the operation fails, for example when an unsupported address is specified.

unwrap

protected static final <A extends AFSocketAddress>
@NonNull A unwrap(String hostname,
 int port,
 AFAddressFamily<A> af)
           throws SocketException

Returns an AFSocketAddress given a special InetAddress hostname that encodes the byte sequence of an AF_UNIX etc. socket address, like those returned by wrapAddress().

Type Parameters:

A - The corresponding address type.

Parameters:

hostname - The "special" hostname, as provided by InetAddress.getHostName().

port - The port (use 0 for "none").

af - The address family.

Returns:

The AFSocketAddress instance.

Throws:

SocketException - if the operation fails, for example when an unsupported address is specified.

isSupportedAddress

protected static final boolean isSupportedAddress(InetAddress addr,
 AFAddressFamily<?> af)

Checks if the given address is supported by this address family.

Parameters:

addr - The address.

af - The address family.

Returns:

true if supported.

writeNativeAddressTo

public final void writeNativeAddressTo(ByteBuffer buf)
                                throws IOException

Writes the native (system-level) representation of this address to the given buffer. The position of the target buffer will be at the end (i.e., after) the written data.

Parameters:

buf - The target buffer.

Throws:

IOException - on error.

newConnectedSocket

public AFSocket<?> newConnectedSocket()
                               throws IOException

Creates a new socket connected to this address.

Returns:

The socket instance.

Throws:

IOException - on error.

newBoundServerSocket

public AFServerSocket<?> newBoundServerSocket()
                                       throws IOException

Creates a new server socket bound to this address.

Returns:

The server socket instance.

Throws:

IOException - on error.

newForceBoundServerSocket

public AFServerSocket<?> newForceBoundServerSocket()
                                            throws IOException

Creates a new server socket force-bound to this address (i.e., any additional call to ServerSocket.bind(SocketAddress) will ignore the passed address and use this one instead.

Returns:

The server socket instance.

Throws:

IOException - on error.

of

public static AFSocketAddress of(URI u)
                          throws SocketException

Tries to parse the given URI and return a corresponding AFSocketAddress for it. NOTE: Only certain URI schemes are supported, such as unix:// (for AFUNIXSocketAddress) and tipc:// for AFTIPCSocketAddress.

Parameters:

u - The URI.

Returns:

The address.

Throws:

SocketException - on error.

See Also:

• AFAddressFamily.uriSchemes()

of

public static AFSocketAddress of(URI u,
 int overridePort)
                          throws SocketException

Tries to parse the given URI and return a corresponding AFSocketAddress for it. NOTE: Only certain URI schemes are supported, such as unix:// (for AFUNIXSocketAddress) and tipc:// for AFTIPCSocketAddress.

Parameters:

u - The URI.

overridePort - The port to forcibly use, or -1 for "don't override".

Returns:

The address.

Throws:

SocketException - on error.

See Also:

• AFAddressFamily.uriSchemes()

toURI

public URI toURI(String scheme,
 URI template)
          throws IOException

Tries to create a URI based on this AFSocketAddress.

Parameters:

scheme - The target scheme.

template - An optional template to reuse certain parameters (e.g., the "path" component for an http request), or null.

Returns:

The URI.

Throws:

IOException - on error.

toSocatAddressString

public @Nullable String toSocatAddressString(AFSocketType socketType,
 AFSocketProtocol socketProtocol)
                                      throws IOException

Returns a address string that can be used with socat's SOCKET-CONNECT, SOCKET-LISTEN, SOCKET-DATAGRAM, etc., address types, or null if the address type is not natively supported by this platform. This call is mostly suited for debugging purposes. The resulting string is specific to the platform the code is executed on, and thus may be different among platforms.

Parameters:

socketType - The socket type, or null to omit from string.

socketProtocol - The socket protocol, or null to omit from string.

Returns:

The string (such as 1:0:x2f746d702f796f).

Throws:

IOException - on error (a SocketException is thrown if the native address cannot be accessed).

covers

public boolean covers(AFSocketAddress other)

Checks if the given address could cover another address. By default, this is only true if both addresses are regarded equal using InetSocketAddress.equals(Object). However, implementations may support "wildcard" addresses, and this method would compare a wildcard address against some non-wildcard address, for example.

Parameters:

other - The other address that could be covered by this address.

Returns:

true if the other address could be covered.

parseUnsignedInt

protected static int parseUnsignedInt(String s,
 int radix)
                               throws NumberFormatException

Parses the string argument as an unsigned integer in the radix specified by the second argument. Works like Integer.parseUnsignedInt(String, int); added to allow execution on Java 1.7.

Parameters:

s - The string.

radix - The radix.

Returns:

The integer.

Throws:

NumberFormatException - on parse error.