Package io.helidon.common.configurable

Interface Resource

public interface Resource

A representation of a resource that can be loaded from URL (create(URI)), classpath (create(String)), filesystem (create(Path), content in config (create(Config, String), input stream(create(String, InputStream), or direct value (create(String, byte[]), create(String, String). The resource bytes can then be accessed by various methods, depending on the type required - either you can access bytes (bytes(), stream()) or String (string(), string(Charset)). This class is not thread safe. If you want to use it across multiple threads, there is an option: call cacheBytes() before accessing it by other threads. Note that this stores all the bytes in memory, so use with care!!!

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Resource.Source Source of a Resource.

Method Summary

Modifier and Type	Method and Description
byte[]	bytes() Get bytes of this resource.
void	cacheBytes() Caches the resource bytes in memory, so they can be repeatedly accessed.
static Optional<Resource>	create(Config config, String keyPrefix) Loads the resource from appropriate location based on configuration and a key prefix.
static Resource	create(Path fsPath) Load resource from file system.
static Resource	create(String resourcePath) Load resource from classpath.
static Resource	create(String description, byte[] bytes) Load resource from binary content.
static Resource	create(String description, InputStream inputStream) Load resource from binary content from an input stream, using Resource.Source.UNKNOWN type.
static Resource	create(String description, String string) Load resource from text content (e.g.
static Resource	create(URI uri) Load resource from URI provided.
static Resource	create(URI uri, Proxy proxy) Load resource from URI provided with an explicit proxy server.
String	location() Location (or description) of this resource, depends on original source.
Resource.Source	sourceType() Type of this resource, depends on the original source.
InputStream	stream() Get an input stream to this resource.
String	string() Get string content of this resource.
String	string(Charset charset) Get string content of this resource.

Method Detail

create

static Resource create(URI uri)

Load resource from URI provided. Note that the loading is lazy - this method opens the stream, but byte are ready only once you call bytes() and other content retrieval-methods.

Parameters:

uri - Resource location

Returns:

resource instance

create

static Resource create(URI uri,
                       Proxy proxy)

Load resource from URI provided with an explicit proxy server. Note that the loading is lazy - this method opens the stream, but byte are ready only once you call bytes() and other content retrieval-methods.

Parameters:

uri - Resource location

proxy - HTTP proxy to use when accessing the URI

Returns:

resource instance

create

static Resource create(String resourcePath)

Load resource from classpath. Note that the loading is lazy - this method opens the stream, but byte are ready only once you call bytes() and other content retrieval-methods.

Parameters:

resourcePath - classpath path

Returns:

resource instance

create

static Resource create(Path fsPath)

Load resource from file system. Note that the loading is lazy - this method opens the stream, but byte are ready only once you call bytes() and other content retrieval-methods.

Parameters:

fsPath - path of file system

Returns:

resource instance

create

static Resource create(String description,
                       byte[] bytes)

Load resource from binary content.

Parameters:

description - description of this resource (e.g. "keystore")

bytes - raw bytes of this resource

Returns:

resource instance

create

static Resource create(String description,
                       String string)

Load resource from text content (e.g. this must not be base64 - use create(String, byte[]) for binary).

Parameters:

description - description of this resource (e.g. "JWK-private")

string - string content of this resource, will be transformed to bytes using UTF-8 encoding

Returns:

resource instance

create

static Resource create(String description,
                       InputStream inputStream)

Load resource from binary content from an input stream, using Resource.Source.UNKNOWN type.

Parameters:

description - description of this resource (e.g. "keystore")

inputStream - input stream to raw bytes of this resource

Returns:

resource instance

create

static Optional<Resource> create(Config config,
                                 String keyPrefix)

Loads the resource from appropriate location based on configuration and a key prefix. Keys supported (in this order):

• prefix-path: File system path
• prefix-resource-path: Class-path resource
• prefix-url: URL to resource
• prefix-content: actual content (base64 encoded bytes)
• prefix-content-plain: actual content (string)
• prefix-use-proxy: set to false not to go through a proxy; will only use proxy if it is defined used "proxy-host" and optional "proxy-port" (defaults to 80); ignored unless URL is used

Parameters:

config - configuration

keyPrefix - prefix of keys that may contain the location of resource

Returns:

a resource ready to load from one of the locations or empty if neither is defined

stream

InputStream stream()

Get an input stream to this resource. If this method is called first, you actually get "THE" stream to the resource and there will be no buffering done. Once this happens, you cannot call any other method on this instance. If you create the resource with byte content (e.g. from string), the content will be pre-buffered. If you first call another method (such as bytes(), or explicitly buffer this resource cacheBytes(), you will get a new input stream to the buffered bytes and may call this method multiple times.

Returns:

input stream ready to read bytes

Throws:

IllegalStateException - in case the stream was already provided in previous call and was not buffered

bytes

byte[] bytes()

Get bytes of this resource. Buffers the resource bytes in memory.

Returns:

bytes of this resource

Throws:

IllegalStateException - in case the stream was already provided in previous call and was not buffered

string

String string()

Get string content of this resource. Buffers the resource bytes in memory.

Returns:

string content of this instance, using UTF-8 encoding to decode bytes

Throws:

IllegalStateException - in case the stream was already provided in previous call and was not buffered

string

String string(Charset charset)

Get string content of this resource. Buffers the resource bytes in memory.

Parameters:

charset - Character set (encoding) to use to decode bytes

Returns:

string content of this instance, using your encoding to decode bytes

Throws:

IllegalStateException - in case the stream was already provided in previous call and was not buffered

sourceType

Resource.Source sourceType()

Type of this resource, depends on the original source.

Returns:

type

location

String location()

Location (or description) of this resource, depends on original source. Depending on source, this may be:

• FILE - absolute path to the file
• CLASSPATH - resource path
• URL - string of the URI
• CONTENT - either config key or description provided to method create(String, String)
• BINARY_CONTENT - either config key or description provided to create(String, byte[])
• UNKNOWN - whatever description was provided to create(String, InputStream)

Returns:

location of this resource (or other description of where it comes from)

cacheBytes

void cacheBytes()

Caches the resource bytes in memory, so they can be repeatedly accessed. Be VERY careful with all methods that cache the bytes, as this may cause a memory issue!