team.unnamed.creative.base

Interface Readable

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 Readable

Interface for representing data that can be read via a InputStream such as resources, files, bytes in memory, etc. without having them always loaded

Since:

1.0.0

Method Summary

Modifier and Type	Method and Description
default @NotNull Writable	asWritable() Creates a new Writable instance that represents this Readable data.
static @NotNull Readable	bytes(byte[] bytes) Creates a new Readable instance representing the given byte array, which is read via a ByteArrayInputStream when required
static @NotNull Readable	copyInputStream(@NotNull java.io.InputStream inputStream) Creates a new Readable instance that will copy, save and return the given InputStream data.
static @NotNull Readable	file(@NotNull java.io.File file) Creates a new Readable instance that represents the given File, which will be opened every time open() is called
@NotNull java.io.InputStream	open() Opens this readable object with a InputStream, this method can be called anytime, it should be consistent with its data and return it exactly every time.
static @NotNull Readable	path(@NotNull java.nio.file.Path path, java.nio.file.OpenOption... options) Creates a new Readable instance that represents the given Path, which will be opened every time open() is called
default void	readAndWrite(@NotNull java.io.OutputStream output) Opens, reads and writes this Readable information and transfers/writes it to the given OutputStream
default byte[]	readAsByteArray() Opens and reads this Readable instance to a byte array, it is recommended to cache the returned result if you need to re-use it, since this method reads the data every time it is called
default @NotNull java.lang.String	readAsUTF8String() Opens and reads this Readable instance to an UTF-8 string, it is recommended to cache the returned result if you need to re-use it, since this method (may) read the data every time is called
static @NotNull Readable	resource(@NotNull java.lang.ClassLoader loader, @NotNull java.lang.String name) Creates a new Readable instance that represents the named resource at the specified class loader
static @NotNull Readable	resource(@NotNull java.lang.String name) Deprecated. Use resource(ClassLoader, String) instead
static @NotNull Readable	stringUtf8(@NotNull java.lang.String string) Creates a new Readable instance representing the given string, which is read via a ByteArrayInputStream when needed

Method Detail

open

@NotNull
@NotNull java.io.InputStream open()
                                     throws java.io.IOException

Opens this readable object with a InputStream, this method can be called anytime, it should be consistent with its data and return it exactly every time.

Implementations should be state-less and not necessarily thread-safe

Returns:

The input stream to be read

Throws:

java.io.IOException - If opening fails

Since:

1.0.0

readAndWrite

default void readAndWrite(@NotNull
                          @NotNull java.io.OutputStream output)

Opens, reads and writes this Readable information and transfers/writes it to the given OutputStream

Note that this operation won't close the given OutputStream

Parameters:

output - The output stream to transfer

Since:

1.0.0

readAsByteArray

default byte[] readAsByteArray()

Opens and reads this Readable instance to a byte array, it is recommended to cache the returned result if you need to re-use it, since this method reads the data every time it is called

Returns:

The data in a byte array

Since:

1.0.0

readAsUTF8String

@NotNull
default @NotNull java.lang.String readAsUTF8String()
                                                      throws java.io.IOException

Opens and reads this Readable instance to an UTF-8 string, it is recommended to cache the returned result if you need to re-use it, since this method (may) read the data every time is called

Returns:

This readable data, as a string

Throws:

java.io.IOException - If conversion fails

Since:

1.0.0

asWritable

@NotNull
default @NotNull Writable asWritable()

Creates a new Writable instance that represents this Readable data.

The returned writable instance will open the readable everytime it needs to write the data, and will then write it to the output stream.

Returns:

The writable representation

Since:

1.3.0

resource

@NotNull
static @NotNull Readable resource(@NotNull
                                            @NotNull java.lang.ClassLoader loader,
                                            @NotNull
                                            @NotNull java.lang.String name)

Creates a new Readable instance that represents the named resource at the specified class loader

Parameters:

loader - The class loader that holds the resource

name - The full resource name

Returns:

The Readable representation

Since:

1.0.0

resource

@Deprecated
 @ApiStatus.ScheduledForRemoval(inVersion="2.0.0")
 @NotNull
static @NotNull Readable resource(@NotNull
                                                                                                              @NotNull java.lang.String name)

Deprecated. Use resource(ClassLoader, String) instead

Creates a new Readable instance that represents the named resource at the caller class loader.

Parameters:

name - The full resource name

Returns:

The Readable representation

Since:

1.1.0

file

@NotNull
static @NotNull Readable file(@NotNull
                                        @NotNull java.io.File file)

Creates a new Readable instance that represents the given File, which will be opened every time open() is called

Parameters:

file - The wrapped file, must exist

Returns:

The Readable representation for this file

Since:

1.0.0

path

@NotNull
static @NotNull Readable path(@NotNull
                                        @NotNull java.nio.file.Path path,
                                        @NotNull
                                        java.nio.file.OpenOption... options)

Creates a new Readable instance that represents the given Path, which will be opened every time open() is called

Parameters:

path - The file path

options - The options Files.newInputStream(java.nio.file.Path, java.nio.file.OpenOption...)

Returns:

The Readable representation for this path

Since:

1.0.0

copyInputStream

@NotNull
static @NotNull Readable copyInputStream(@NotNull
                                                   @NotNull java.io.InputStream inputStream)

Creates a new Readable instance that will copy, save and return the given InputStream data. In order to preserve the data, it reads the input stream as a byte array when this method is called.

Parameters:

inputStream - The input stream to copy

Returns:

The Readable representation

Since:

1.0.0

bytes

@NotNull
static @NotNull Readable bytes(byte[] bytes)

Creates a new Readable instance representing the given byte array, which is read via a ByteArrayInputStream when required

Parameters:

bytes - The wrapped bytes

Returns:

The Readable representation

Since:

1.0.0

stringUtf8

@NotNull
static @NotNull Readable stringUtf8(@NotNull
                                              @NotNull java.lang.String string)

Creates a new Readable instance representing the given string, which is read via a ByteArrayInputStream when needed

Parameters:

string - The wrapped string

Returns:

The representation

Since:

1.0.0