Provides object-oriented access to file descriptors via InputStream, Socket, etc., depending on the file descriptor type.

Typical usage:


FileDescriptor fd;

// succeeds if fd refers to an AF_UNIX stream socket
AFUNIXSocket socket = FileDescriptorCast.using(fd).as(AFUNIXSocket.class);

// succeeds if fd refers to an AF_UNIX datagram socket
AFUNIXDatagramChannel channel = FileDescriptorCast.using(fd).as(AFUNIXDatagramChannel.class);

// always succeeds
InputStream in = FileDescriptorCast.using(fd).as(InputStream.class);
OutputStream in = FileDescriptorCast.using(fd).as(OutputStream.class);

Important notes

On some platforms (e.g., Solaris, Illumos) you may need to re-apply a read timeout (e.g., using Socket#setSoTimeout(int)) after obtaining the socket.
You may lose Java port information for AFSocketAddress implementations that do not encode this information directly (such as AFUNIXSocketAddress and AFTIPCSocketAddress).
The "blocking" state of a socket may be forcibly changed to "blocking" when performing the cast, especially when casting to Socket, DatagramSocket or ServerSocket and any of their subclasses where "blocking" is the expected state.
When calling using(FileDescriptor) for a FileDescriptor obtained from another socket or other resource in the same JVM (i.e., not from another process), especially for sockets provided by junixsocket itself, there is a chance that the garbage collector may clean up the original socket at an opportune moment, thereby closing the resource underlying the shared FileDescriptor prematurely.
This is considered an edge-case, and deliberately not handled automatically for performance and portability reasons: We would have to do additional reference counting on all FileDescriptor instances, either through patching FileCleanable or a shared data structure.
The issue can be prevented by keeping a reference to the original object, such as keeping it in an enclosing try-with-resources block or as a member variable, for example. Alternatively, using a "duplicate" file descriptor (via duplicating(FileDescriptor)) circumvents this problem, at the cost of using additional system resources.
As a consequence of the previous point: For using(FileDescriptor): when casting file descriptors that belong to a junixsocket-controlled sockets, the target socket is configured in a way such that garbage collection will not automatically close the target's underlying file descriptor (but still potentially any file descriptors received from other processes via ancillary messages).
The same restrictions as for using(FileDescriptor) apply to unsafeUsing(int) as well.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static interface	FileDescriptorCast.CastingProvider<T>
private abstract static class	FileDescriptorCast.CastingProviderMap
private static interface	FileDescriptorCast.CastingProviderSocketOrChannel<T>
private static class	FileDescriptorCast.LenientFileInputStream

Field Summary

Modifier and Type	Field and Description
private final FileDescriptorCast.CastingProviderMap	cpm
private static final int	FD_ERR
private static final int	FD_IN
private static final AFFunction<FileDescriptor, FileInputStream>	FD_IS_PROVIDER
private static final int	FD_OUT
private final FileDescriptor	fdObj
private static final FileDescriptorCast.CastingProviderMap	GLOBAL_PROVIDERS
private static final FileDescriptorCast.CastingProviderMap	GLOBAL_PROVIDERS_FINAL
private int	localPort
private static final Map<Class<?>, FileDescriptorCast.CastingProviderMap>	PRIMARY_TYPE_PROVIDERS_MAP
private int	remotePort

Constructor Summary

Access	Constructor and Description
private	FileDescriptorCast(FileDescriptor fdObj, FileDescriptorCast.CastingProviderMap cpm)

Method Summary

Modifier and Type	Method and Description
public < The desired type. K> @NonNull K	Returns: s An instance of the desired type. as(Class<K> The class of the desired type. desiredType) Casts this instance to the desired type.
public Set<Class<?>>	Returns: The collection of available types. availableTypes() Returns a collection of available types this instance can be cast to (using `as(Class)`).
public static FileDescriptorCast	Returns: The `FileDescriptorCast` instance. duplicating(FileDescriptor The file descriptor to duplicate. fdObj) Creates a `FileDescriptorCast` using a duplicate of the given file descriptor.
private static int	getFdIfPossible(FileDescriptor fd)
public FileDescriptor	getFileDescriptor() Implements org.newsclub.net.unix.FileDescriptorAccess.getFileDescriptor. Returns the corresponding `FileDescriptor`.
public boolean	Returns: `true` if the cast can be made. isAvailable(Class<?> The class of the desired type. desiredType) Checks if the instance can be cast as the given desired type (using `as(Class)`).
private static <S extends AFSocket<?>> S	reconfigure(boolean isChannel, S socket)
private static <S extends AFServerSocket<?>> S	reconfigure(boolean isChannel, S socket)
private static <S extends AFDatagramSocket<?>> S	reconfigure(boolean isChannel, S socket)
private static < The type. S extends AFSomeSocketChannel> void	reconfigure(boolean The desired cast type (socket=set to blocking, or channel=preserve state). isChannel, S The channel. socketChannel) Reconfigures the Java-side of the socket/socket channel such that its state is compatible with the native socket's state.
private static <S extends AFSomeSocketChannel> void	reconfigureKeepBlockingState(S socketChannel)
private static <S extends AFSomeSocketChannel> void	reconfigureSetBlocking(S socketChannel)
private static void	registerCastingProviders(Class<?> primaryType, FileDescriptorCast.CastingProviderMap cpm)
pack-priv static <A extends AFSocketAddress> void	registerCastingProviders(AFAddressFamilyConfig<A> config)
private static void	registerGenericSocketSupport() Add support for otherwise unsupported sockets.
private static void	triggerInit()
public static FileDescriptorCast	Returns: The `FileDescriptorCast` instance. unsafeUsing(int The system-native file descriptor value. fd) Creates a `FileDescriptorCast` using the given native file descriptor value.
public static FileDescriptorCast	Returns: The `FileDescriptorCast` instance. using(FileDescriptor The file descriptor. fdObj) Creates a `FileDescriptorCast` using the given file descriptor.
public FileDescriptorCast	Returns: This instance. withLocalPort(int The port to assign to (must be >= 0). port) Registers the given port number as the "local port" for this file descriptor.
public FileDescriptorCast	Returns: This instance. withRemotePort(int The port to assign to (must be >= 0). port) Registers the given port number as the "remote port" for this file descriptor.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

cpm	back to summary
private final FileDescriptorCast.CastingProviderMap cpm

FD_ERR	back to summary
private static final int FD_ERR

FD_IN	back to summary
private static final int FD_IN

FD_IS_PROVIDER	back to summary
private static final AFFunction<FileDescriptor, FileInputStream> FD_IS_PROVIDER

FD_OUT	back to summary
private static final int FD_OUT

fdObj	back to summary
private final FileDescriptor fdObj

GLOBAL_PROVIDERS	back to summary
private static final FileDescriptorCast.CastingProviderMap GLOBAL_PROVIDERS

GLOBAL_PROVIDERS_FINAL	back to summary
private static final FileDescriptorCast.CastingProviderMap GLOBAL_PROVIDERS_FINAL

localPort	back to summary
private int localPort

PRIMARY_TYPE_PROVIDERS_MAP	back to summary
private static final Map<Class<?>, FileDescriptorCast.CastingProviderMap> PRIMARY_TYPE_PROVIDERS_MAP

remotePort	back to summary
private int remotePort

Constructor Detail

FileDescriptorCast	back to summary
private FileDescriptorCast(FileDescriptor fdObj, FileDescriptorCast.CastingProviderMap cpm)

Method Detail

as back to summary

as	back to summary
public <K> @NonNull K as(Class<K> desiredType) throws IOException Casts this instance to the desired type. Parameters <K> The desired type. desiredType:Class<K> The class of the desired type. Returns:@NonNull K s An instance of the desired type. Annotations @SuppressWarnings:PMD.ShortMethodName Exceptions IOException: if there was a problem while casting. ClassCastException: if the cast cannot be legally made. See Also `availableTypes()`, `isAvailable(Class)`

public <K> @NonNull K as(Class<K> desiredType) throws IOException

Casts this instance to the desired type.

Parameters

<K>: The desired type.
desiredType:Class<K>: The class of the desired type.

Returns:@NonNull K

s An instance of the desired type.

Annotations

@SuppressWarnings:PMD.ShortMethodName

Exceptions

IOException:: if there was a problem while casting.
ClassCastException:: if the cast cannot be legally made.

availableTypes back to summary

availableTypes	back to summary
public Set<Class<?>> availableTypes() Returns a collection of available types this instance can be cast to (using `as(Class)`). Returns:Set<Class<?>> The collection of available types.

public Set<Class<?>> availableTypes()

Returns a collection of available types this instance can be cast to (using as(Class)).

Returns:Set<Class<?>>: The collection of available types.

duplicating back to summary

duplicating	back to summary
public static FileDescriptorCast duplicating(FileDescriptor fdObj) throws IOException Creates a `FileDescriptorCast` using a duplicate of the given file descriptor. Duplicating a file descriptor is performed at the system-level, which means an additional file descriptor pointing to the same resource as the original is created by the operating system. The advantage of using `duplicating(FileDescriptor)` over `using(FileDescriptor)` is that neither implicit garbage collection nor an explicit call to `Closeable#close()` on a resource owning the original `FileDescriptor` affects the availability of the resource from the target of the cast. Parameters fdObj:FileDescriptor The file descriptor to duplicate. Returns:FileDescriptorCast The `FileDescriptorCast` instance. Exceptions IOException: on error, especially if the given file descriptor is invalid or unsupported, or if duplicating fails or is unsupported.

public static FileDescriptorCast duplicating(FileDescriptor fdObj) throws IOException

Creates a FileDescriptorCast using a duplicate of the given file descriptor.

Duplicating a file descriptor is performed at the system-level, which means an additional file descriptor pointing to the same resource as the original is created by the operating system.

The advantage of using duplicating(FileDescriptor) over using(FileDescriptor) is that neither implicit garbage collection nor an explicit call to Closeable#close() on a resource owning the original FileDescriptor affects the availability of the resource from the target of the cast.

Parameters

fdObj:FileDescriptor: The file descriptor to duplicate.

Returns:FileDescriptorCast

The FileDescriptorCast instance.

Exceptions

IOException:: on error, especially if the given file descriptor is invalid or unsupported, or if duplicating fails or is unsupported.

getFdIfPossible	back to summary
private static int getFdIfPossible(FileDescriptor fd)

getFileDescriptor back to summary

getFileDescriptor	back to summary
public FileDescriptor getFileDescriptor() Implements org.newsclub.net.unix.FileDescriptorAccess.getFileDescriptor. Doc from org.newsclub.net.unix.FileDescriptorAccess.getFileDescriptor. Returns the corresponding `FileDescriptor`. Returns:FileDescriptor The corresponding `FileDescriptor`. Annotations @Override @SuppressFBWarnings:EI_EXPOSE_REP

public FileDescriptor getFileDescriptor()

Implements org.newsclub.net.unix.FileDescriptorAccess.getFileDescriptor.

Doc from org.newsclub.net.unix.FileDescriptorAccess.getFileDescriptor.

Returns the corresponding FileDescriptor.

Returns:FileDescriptor

The corresponding FileDescriptor.

Annotations

@Override
@SuppressFBWarnings:EI_EXPOSE_REP

isAvailable back to summary

isAvailable	back to summary
public boolean isAvailable(Class<?> desiredType) throws IOException Checks if the instance can be cast as the given desired type (using `as(Class)`). Parameters desiredType:Class<?> The class of the desired type. Returns:boolean `true` if the cast can be made. Exceptions IOException: on error. See Also `as(Class)`

public boolean isAvailable(Class<?> desiredType) throws IOException

Checks if the instance can be cast as the given desired type (using as(Class)).

Parameters

desiredType:Class<?>: The class of the desired type.

Returns:boolean

true if the cast can be made.

Exceptions

IOException:: on error.

See Also

as(Class)

reconfigure	back to summary
private static <S extends AFSocket<?>> S reconfigure(boolean isChannel, S socket) throws IOException Annotations @SuppressWarnings:null

reconfigure	back to summary
private static <S extends AFServerSocket<?>> S reconfigure(boolean isChannel, S socket) throws IOException Annotations @SuppressWarnings:null

reconfigure	back to summary
private static <S extends AFDatagramSocket<?>> S reconfigure(boolean isChannel, S socket) throws IOException Annotations @SuppressWarnings:null

reconfigure back to summary

reconfigure	back to summary
private static <S extends AFSomeSocketChannel> void reconfigure(boolean isChannel, S socketChannel) throws IOException Reconfigures the Java-side of the socket/socket channel such that its state is compatible with the native socket's state. This is necessary to properly configure blocking/non-blocking state, as that is cached on the Java side. If `isChannel` is false, then we want to cast to a `Socket`, `DatagramSocket` or `ServerSocket`, which means blocking I/O is desired. If the underlying native socket is configured non-blocking, we need to reset the state to "blocking" accordingly. If `isChannel` is true, then we want to cast to a `SocketChannel`, `DatagramChannel` or `ServerSocketChannel`, in which case the blocking state should be preserved, if possible. It is then up to the user to check blocking state via `AbstractSelectableChannel#isBlocking()` prior to using the socket. Note that on Windows, it may be impossible to query the blocking state from an external socket, so the state is always forcibly set to "blocking". Parameters <S> The type. isChannel:boolean The desired cast type (socket=set to blocking, or channel=preserve state). socketChannel:S The channel. Exceptions IOException: on error.

private static <S extends AFSomeSocketChannel> void reconfigure(boolean isChannel, S socketChannel) throws IOException

Reconfigures the Java-side of the socket/socket channel such that its state is compatible with the native socket's state. This is necessary to properly configure blocking/non-blocking state, as that is cached on the Java side.

If isChannel is false, then we want to cast to a Socket, DatagramSocket or ServerSocket, which means blocking I/O is desired. If the underlying native socket is configured non-blocking, we need to reset the state to "blocking" accordingly.

If isChannel is true, then we want to cast to a SocketChannel, DatagramChannel or ServerSocketChannel, in which case the blocking state should be preserved, if possible. It is then up to the user to check blocking state via AbstractSelectableChannel#isBlocking() prior to using the socket.

Note that on Windows, it may be impossible to query the blocking state from an external socket, so the state is always forcibly set to "blocking".

Parameters

<S>: The type.
isChannel:boolean: The desired cast type (socket=set to blocking, or channel=preserve state).
socketChannel:S: The channel.

Exceptions

IOException:: on error.

reconfigureKeepBlockingState	back to summary
private static <S extends AFSomeSocketChannel> void reconfigureKeepBlockingState(S socketChannel) throws IOException

reconfigureSetBlocking	back to summary
private static <S extends AFSomeSocketChannel> void reconfigureSetBlocking(S socketChannel) throws IOException

registerCastingProviders	back to summary
private static void registerCastingProviders(Class<?> primaryType, FileDescriptorCast.CastingProviderMap cpm)

registerCastingProviders	back to summary
pack-priv static <A extends AFSocketAddress> void registerCastingProviders(AFAddressFamilyConfig<A> config)

registerGenericSocketSupport	back to summary
private static void registerGenericSocketSupport() Add support for otherwise unsupported sockets.

triggerInit	back to summary
private static void triggerInit()

unsafeUsing back to summary

unsafeUsing	back to summary
public static FileDescriptorCast unsafeUsing(int fd) throws IOException Creates a `FileDescriptorCast` using the given native file descriptor value. This method is inherently unsafe as it may make assumptions on the internal system representation of a file descriptor (which differs between Windows and Unix, for example). provide access to resources that are otherwise not accessible Note that attempts are made to reuse `FileDescriptor#in`, `FileDescriptor#out`, and `FileDescriptor#err`, respectively. Parameters fd:int The system-native file descriptor value. Returns:FileDescriptorCast The `FileDescriptorCast` instance. Annotations @Unsafe Exceptions IOException: on error, especially if the given file descriptor is invalid or unsupported, or when "unsafe" operations are unavailable or manually disabled for the current environment.

public static FileDescriptorCast unsafeUsing(int fd) throws IOException

Creates a FileDescriptorCast using the given native file descriptor value.

This method is inherently unsafe as it may

make assumptions on the internal system representation of a file descriptor (which differs between Windows and Unix, for example).
provide access to resources that are otherwise not accessible

Note that attempts are made to reuse FileDescriptor#in, FileDescriptor#out, and FileDescriptor#err, respectively.

Parameters

fd:int: The system-native file descriptor value.

Returns:FileDescriptorCast

The FileDescriptorCast instance.

Annotations

@Unsafe

Exceptions

IOException:: on error, especially if the given file descriptor is invalid or unsupported, or when "unsafe" operations are unavailable or manually disabled for the current environment.

using back to summary

using	back to summary
public static FileDescriptorCast using(FileDescriptor fdObj) throws IOException Creates a `FileDescriptorCast` using the given file descriptor. Note that if any resource that also references this `FileDescriptor` is garbage-collected, the cleanup for that object may close the referenced `FileDescriptor`, thereby resulting in premature connection losses, etc. See `duplicating(FileDescriptor)` for a solution to this problem. Parameters fdObj:FileDescriptor The file descriptor. Returns:FileDescriptorCast The `FileDescriptorCast` instance. Exceptions IOException: on error, especially if the given file descriptor is invalid or unsupported.

public static FileDescriptorCast using(FileDescriptor fdObj) throws IOException

Creates a FileDescriptorCast using the given file descriptor.

Note that if any resource that also references this FileDescriptor is garbage-collected, the cleanup for that object may close the referenced FileDescriptor, thereby resulting in premature connection losses, etc. See duplicating(FileDescriptor) for a solution to this problem.

Parameters

fdObj:FileDescriptor: The file descriptor.

Returns:FileDescriptorCast

The FileDescriptorCast instance.

Exceptions

IOException:: on error, especially if the given file descriptor is invalid or unsupported.

withLocalPort	back to summary
public FileDescriptorCast withLocalPort(int port) Registers the given port number as the "local port" for this file descriptor. Important Note This only changes the state of this instance. The actual file descriptor is not affected. Parameters port:int The port to assign to (must be >= 0). Returns:FileDescriptorCast This instance.

withLocalPort

back to summary

public FileDescriptorCast withLocalPort(int port)

Registers the given port number as the "local port" for this file descriptor.

Important Note

This only changes the state of this instance. The actual file descriptor is not affected.

Parameters

port:int: The port to assign to (must be >= 0).

Returns:FileDescriptorCast

This instance.

withRemotePort	back to summary
public FileDescriptorCast withRemotePort(int port) Registers the given port number as the "remote port" for this file descriptor. Important Note This only changes the state of this instance. The actual file descriptor is not affected. Parameters port:int The port to assign to (must be >= 0). Returns:FileDescriptorCast This instance.

withRemotePort

back to summary

public FileDescriptorCast withRemotePort(int port)

Registers the given port number as the "remote port" for this file descriptor.

Important Note

This only changes the state of this instance. The actual file descriptor is not affected.

Parameters

port:int: The port to assign to (must be >= 0).

Returns:FileDescriptorCast

This instance.

org.newsclub.net.unix back to summary

private Interface FileDescriptorCast.CastingProvider<T>

Annotations

@FunctionalInterface

Method Summary

Modifier and Type	Method and Description
public T	provideAs(FileDescriptorCast fdc, Class<? super T> desiredType)

Method Detail

provideAs	back to summary
public T provideAs(FileDescriptorCast fdc, Class<? super T> desiredType) throws IOException

org.newsclub.net.unix back to summary

private abstract Class FileDescriptorCast.CastingProviderMap

Class Inheritance

extends Object

java.lang.Object
org.newsclub.net.unix.FileDescriptorCast.CastingProviderMap

Field Summary

Modifier and Type	Field and Description
private final Set<Class<?>>	classes
private final Map<Class<?>, FileDescriptorCast.CastingProvider<?>>	providers

Constructor Summary

Access	Constructor and Description
protected	CastingProviderMap()

Method Summary

Modifier and Type	Method and Description
protected final <T> void	addProvider(Class<T> type, FileDescriptorCast.CastingProvider<?> cp)
private void	addProvider0(Class<?> type, FileDescriptorCast.CastingProvider<?> cp)
protected abstract void	addProviders()
protected final void	addProviders(FileDescriptorCast.CastingProviderMap other)
public <T> FileDescriptorCast.CastingProvider<? extends T>	get(Class<T> desiredType)
protected void	registerGenericDatagramSocketProviders()
protected void	registerGenericSocketProviders()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

classes	back to summary
private final Set<Class<?>> classes

providers	back to summary
private final Map<Class<?>, FileDescriptorCast.CastingProvider<?>> providers

Constructor Detail

CastingProviderMap	back to summary
protected CastingProviderMap() Annotations @SuppressWarnings:PMD.ConstructorCallsOverridableMethod

Method Detail

addProvider	back to summary
protected final <T> void addProvider(Class<T> type, FileDescriptorCast.CastingProvider<?> cp)

addProvider0	back to summary
private void addProvider0(Class<?> type, FileDescriptorCast.CastingProvider<?> cp)

addProviders	back to summary
protected abstract void addProviders()

addProviders	back to summary
protected final void addProviders(FileDescriptorCast.CastingProviderMap other)

get	back to summary
public <T> FileDescriptorCast.CastingProvider<? extends T> get(Class<T> desiredType) Annotations @SuppressWarnings:unchecked

registerGenericDatagramSocketProviders	back to summary
protected void registerGenericDatagramSocketProviders() Annotations @SuppressWarnings:null

registerGenericSocketProviders	back to summary
protected void registerGenericSocketProviders() Annotations @SuppressWarnings:null

public final Class FileDescriptorCast

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Interface FileDescriptorCast.CastingProvider<T>

Method Summary

Method Detail

private abstract Class FileDescriptorCast.CastingProviderMap

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Interface FileDescriptorCast.CastingProviderSocketOrChannel<T>

Method Summary

Method Detail

private final Class FileDescriptorCast.LenientFileInputStream

Constructor Summary

Method Summary

Constructor Detail

Method Detail