Package io.helidon.common.configurable

Interface Resource

public interface Resource

A representation of a resource that can be loaded from URL (from(URI)), classpath (from(String)), filesystem (from(Path), fromPath(String)), content in config (from(Config, String), input stream(from(InputStream, String), or direct value (fromContent(String, byte[]), fromContent(String, String). The resource bytes can then be accessed by various methods, depending on the type required - either you can access bytes (getBytes(), getStream()) or String (getString(), getString(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
void	cacheBytes() Caches the resource bytes in memory, so they can be repeatedly accessed.
static java.util.Optional<Resource>	from(Config config, java.lang.String keyPrefix) Loads the resource from appropriate location based on configuration and a key prefix.
static Resource	from(java.io.InputStream inputStream, java.lang.String description) Load resource from binary content from an input stream, using Resource.Source.UNKNOWN type.
static Resource	from(java.nio.file.Path fsPath) Load resource from file system.
static Resource	from(java.lang.String resourcePath) Load resource from classpath.
static Resource	from(java.net.URI uri) Load resource from URI provided.
static Resource	from(java.net.URI uri, java.net.Proxy proxy) Load resource from URI provided with an explicit proxy server.
static Resource	fromContent(java.lang.String description, byte[] bytes) Load resource from binary content.
static Resource	fromContent(java.lang.String description, java.lang.String string) Load resource from text content (e.g.
static Resource	fromPath(java.lang.String fsPath) Helper method for from(Path) so you do not have to create the path yourself.
byte[]	getBytes() Get bytes of this resource.
java.lang.String	getLocation() Location (or description) of this resource, depends on original source.
Resource.Source	getSourceType() Type of this resource, depends on the original source.
java.io.InputStream	getStream() Get an input stream to this resource.
java.lang.String	getString() Get string content of this resource.
java.lang.String	getString(java.nio.charset.Charset charset) Get string content of this resource.

Method Detail

from

static Resource from(java.net.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 getBytes() and other content retrieval-methods.

Parameters:

uri - Resource location

Returns:

resource instance

from

static Resource from(java.net.URI uri,
                     java.net.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 getBytes() and other content retrieval-methods.

Parameters:

uri - Resource location

proxy - HTTP proxy to use when accessing the URI

Returns:

resource instance

from

static Resource from(java.lang.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 getBytes() and other content retrieval-methods.

Parameters:

resourcePath - classpath path

Returns:

resource instance

from

static Resource from(java.nio.file.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 getBytes() and other content retrieval-methods.

Parameters:

fsPath - path of file system

Returns:

resource instance

fromPath

static Resource fromPath(java.lang.String fsPath)

Helper method for from(Path) so you do not have to create the path yourself.

Parameters:

fsPath - String path to file system

Returns:

resource instance

fromContent

static Resource fromContent(java.lang.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

fromContent

static Resource fromContent(java.lang.String description,
                            java.lang.String string)

Load resource from text content (e.g. this must not be base64 - use fromContent(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

from

static Resource from(java.io.InputStream inputStream,
                     java.lang.String description)

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

Parameters:

inputStream - input stream to raw bytes of this resource

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

Returns:

resource instance

from

static java.util.Optional<Resource> from(Config config,
                                         java.lang.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

getStream

java.io.InputStream getStream()

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 getBytes(), 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:

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

getBytes

byte[] getBytes()

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

Returns:

bytes of this resource

Throws:

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

getString

java.lang.String getString()

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:

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

getString

java.lang.String getString(java.nio.charset.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:

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

getSourceType

Resource.Source getSourceType()

Type of this resource, depends on the original source.

Returns:

type

getLocation

java.lang.String getLocation()

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 fromContent(String, String)
• BINARY_CONTENT - either config key or description provided to fromContent(String, byte[])
• UNKNOWN - whatever description was provided to from(InputStream, String)

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!