Package global.namespace.fun.io.api

Interface Socket<T extends java.lang.AutoCloseable>

Type Parameters:

T - the type of the auto-closeable resource.

All Superinterfaces:

XSupplier<T>

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface Socket<T extends java.lang.AutoCloseable>
extends XSupplier<T>

A socket is a reusable object for safe and simple automatic resource management. It loans auto-closeable resources of type <T> to consumers or functions and ensures that the resource gets automatically closed when the consumer or function terminates. It can also transform resources by applying a function while ensuring that the resource gets closed if the function fails with an exception.

The canonical way to create a socket is to use a lambda expression. The following example creates a socket which provides write access for appending bytes to the file test.txt:

 File file = new File("test.txt");
 Socket<FileOutputStream> foss = () -> new FileOutputStream(file, true);
 

The canonical way to use a socket is to provide a lambda expression for a consumer or function to its accept(XConsumer) or apply(XFunction) methods. The following example uses the preceding socket to append "Hello world!" to the file test.txt:

 foss.accept(fos -> new PrintStream(fos).println("Hello world!"));
 

A socket can also get transformed in a fail-safe way by calling its map(XFunction) or flatMap(XFunction) methods. The following example first transforms the preceding file output stream socket into a print stream socket and then appends "Hello world!" to the file test.txt again:

 Socket<PrintStream> pss = foss.map(PrintStream::new);
 pss.accept(ps -> ps.println("Hello world!"));
 

The preceding example can be simplified as follows:

 foss.map(PrintStream::new).accept(ps -> ps.println("Hello world!"));
 

Because sockets are reusable foss and pss can be saved for subsequent use, including transformation: On any use, a new FileOutputStream and a new PrintStream gets created. The file output stream gets automatically closed in all examples, preventing the application from leaking file descriptors. Only the last two examples will close the print stream however. With a print stream this is not a problem, but more complex decorators may buffer data or write some additional bytes when closing, making it mandatory to close them, too. Because of this, transforming a socket is generally preferable over decorating the given resource in a consumer or function.

The following example safely transforms a file output stream socket for writing "Hello world!" to the compressed text file "test.txt.gz". It then safely transforms a file input stream socket for reading the message back and printing it to standard output:

 File file = new File("test.txt.gz");

 Socket<OutputStream> foss = () -> new FileOutputStream(file);
 foss    .map(GZIPOutputStream::new)
         .map(PrintStream::new)
         .accept(ps -> ps.println("Hello world!"));

 Socket<InputStream> fiss = () -> new FileInputStream(file);
 fiss    .map(GZIPInputStream::new)
         .map(InputStreamReader::new)
         .map(BufferedReader::new)
         .accept(br -> System.out.println(br.readLine()));
 

Should any transformation fail, e.g. because the file system is full or the file's content is not in GZIP format, then the sockets will properly close the previously created output or input stream and no resources will be leaked.

See Also:

Transformation

Method Summary

Modifier and Type	Method	Description
default void	accept(XConsumer<? super T> consumer)	Loans a resource to the given consumer.
default <U> U	apply(XFunction<? super T,? extends U> function)	Loans a resource to the given function and returns its value.
default <U extends java.lang.AutoCloseable> Socket<U>	flatMap(XFunction<? super T,? extends Socket<? extends U>> function)	Returns a socket which applies the given function to the resources loaned by this socket and gets its result.
T	get()	Deprecated. This method should not be used by clients because it would defeat the purpose of this interface.
default <U extends java.lang.AutoCloseable> Socket<U>	map(XFunction<? super T,? extends U> function)	Returns a socket which applies the given function to the resources loaned by this socket.

Method Detail

get

@Deprecated
T get()
throws java.lang.Exception

Deprecated. This method should not be used by clients because it would defeat the purpose of this interface.

Returns a resource for direct access by the caller. An implementation must either return a new auto-closeable resource upon each call or ignore any calls to its AutoCloseable.close() method.

Specified by:

get in interface XSupplier<T extends java.lang.AutoCloseable>

Throws:

java.lang.Exception

accept

default void accept(XConsumer<? super T> consumer)
             throws java.lang.Exception

Loans a resource to the given consumer. The resource is obtained from a call to get() and will be closed upon return from this method.

Throws:

java.lang.Exception

apply

default <U> U apply(XFunction<? super T,? extends U> function)
             throws java.lang.Exception

Loans a resource to the given function and returns its value. The resource is obtained from a call to get() and will be closed upon return from this method.

It is an error to return the loaned resource from the given function or any other object which holds on to it. Use the map(XFunction) or flatMap(XFunction) methods instead if you need to transform the resource.

Throws:

java.lang.Exception

map

default <U extends java.lang.AutoCloseable> Socket<U> map(XFunction<? super T,? extends U> function)

Returns a socket which applies the given function to the resources loaned by this socket. If the given function fails then the resource gets closed before this method terminates, which makes the transformation fail-safe.

flatMap

default <U extends java.lang.AutoCloseable> Socket<U> flatMap(XFunction<? super T,? extends Socket<? extends U>> function)

Returns a socket which applies the given function to the resources loaned by this socket and gets its result.

See Also:

map(XFunction)