Module io.inverno.mod.base
Package io.inverno.mod.base.resource

Interface Resource

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
AsyncResource
All Known Implementing Classes:
AbstractAsyncResource, AbstractResource, ClasspathResource, FileResource, JarResource, ModuleResource, NativeResource, PathResource, URLResource, ZipResource
public interface Resource extends AutoCloseable

A resource represents an abstraction of an actual resource like a file, an entry in a zip/jar file, a on the classpath...

Resource data can be read using a ReadableByteChannel assuming the resource is readable: 


 try (Resource resource = new FileResource("/path/to/file")) {
     String content = resource.openReadableByteChannel()
         .map(channel -> {
             try (ByteArrayOutputStream out = new ByteArrayOutputStream()) {
                 ByteBuffer buffer = ByteBuffer.allocate(256);
                 while (channel.read(buffer) > 0) {
                     out.write(buffer.array(), 0, buffer.position());
                     buffer.clear();
                 }
                 return new String(out.toByteArray(), Charsets.UTF_8);
             }
             finally {
                 channel.close();
             }
         })
         .orElseThrow(() -> new IllegalStateException("Resource is not readable"));
 }

Resource data can also be read in a reactive way: 


 try(Resource resource = new FileResource("/path/to/resource")) {
     String content = Flux.from(resource.read())
         .map(chunk -> {
             try {
                 return chunk.toString(Charsets.UTF_8);
             }
             finally {
                 chunk.release();
             }
         })
         .collect(Collectors.joining())
         .block();
 }

Data can be written to a resource using a WritableByteChannel assuming the resource is writable: 


 try (Resource resource = new FileResource("/path/to/file")) {
     resource.openWritableByteChannel()
         .ifPresentOrElse(
             channel -> {
                 try {
                     ByteBuffer buffer = ByteBuffer.wrap("Hello world".getBytes(Charsets.UTF_8));
                     channel.write(buffer);
                 }
                 finally {
                     channel.close();
                 }
             },
             () -> {
                 throw new IllegalStateException("Resource is not writable");
             }
         );
 }

Data can also be written to a resource in a reactive way: 


 try (Resource resource = new FileResource("/path/to/resource")) {
     int nbBytes = Flux.from(resource.write(Flux.just(Unpooled.unreleasableBuffer(Unpooled.wrappedBuffer("Hello world".getBytes(Charsets.UTF_8))))))
         .collect(Collectors.summingInt(i -> i)).block();
     System.out.println(nbBytes + " bytes written");
 }
Since:
1.0
Author:
Jeremy Kuhn

  • Method Details

    • getURI

      URI getURI()

      Returns the resource URI.

      Returns:
      the resource URI

    • getFilename

      String getFilename() throws ResourceException

      Returns the resource file name.

      Returns:
      the resource file name
      Throws:
      ResourceException - if there was an error resolving the resource file name

    • getMediaType

      String getMediaType() throws ResourceException

      Returns the resource media type.

      Returns:
      the resource media type or null if it couldn't be determined
      Throws:
      ResourceException - if there was an error resolving the resource media type

    • isFile

      Optional<Boolean> isFile() throws ResourceException

      Determines whether this resource represents a file.

      A file resource is a resource that can be accessed through a FileChannel.

      Returns:
      an optional returning true if the resource is a file, false otherwise or an empty optional if it couldn't be determined
      Throws:
      ResourceException - if there was an error determining whether the resource is a file

    • exists

      Optional<Boolean> exists() throws ResourceException

      Determines whether the resource exists.

      Returns:
      an optional returning true if the resource exists, false otherwise or an empty optional if existence couldn't be determined
      Throws:
      ResourceException - if there was an error determining resource existence

    • lastModified

      Optional<FileTime> lastModified() throws ResourceException

      Returns the resource last modified time stamp.

      Returns:
      an optional returning the resource last modified time stamp or an empty optional if it couldn't be determined
      Throws:
      ResourceException - if there was an error resolving resource last modified time stamp

    • size

      Optional<Long> size() throws ResourceException

      Returns the resource content size.

      Returns:
      an optional returning the resource content size or an empty optional if it couldn't be determined
      Throws:
      ResourceException - if there was an error resolving resource content size

    • openReadableByteChannel

      Optional<ReadableByteChannel> openReadableByteChannel() throws ResourceException

      Opens a readable byte channel to the resource.

      The caller is responsible for closing the channel to prevent resource leak.

      Returns:
      an optional returning a readable byte channel or an empty optional if the resource is not readable
      Throws:
      ResourceException - if there was an error opening the readable byte channel

    • openWritableByteChannel

      default Optional<WritableByteChannel> openWritableByteChannel() throws ResourceException

      Opens a writable byte channel to the resource.

      The caller is responsible for closing the channel to prevent resource leak.

      Returns:
      an optional returning a writable byte channel or an empty optional if the resource is not writable
      Throws:
      ResourceException - if there was an error opening the writable byte channel

    • openWritableByteChannel

      default Optional<WritableByteChannel> openWritableByteChannel(boolean append) throws ResourceException

      Opens a writable byte channel to the resource that will append or not content to an existing resource.

      The caller is responsible for closing the channel to prevent resource leak.

      Parameters:
      append - true to append content to an existing resource
      Returns:
      an optional returning a writable byte channel or an empty optional if the resource is not writable
      Throws:
      ResourceException - if there was an error opening the writable byte channel

    • openWritableByteChannel

      Optional<WritableByteChannel> openWritableByteChannel(boolean append, boolean createParents) throws ResourceException

      Opens a writable byte channel to the resource that will append or not content to an existing resource and create or not missing parent directories.

      The caller is responsible for closing the channel to prevent resource leak.

      Parameters:
      append - true to append content to an existing resource
      createParents - true to create missing parent directories
      Returns:
      an optional returning a writable byte channel or an empty optional if the resource is not writable
      Throws:
      ResourceException - if there was an error opening the writable byte channel

    • read

      Publisher<ByteBuf> read() throws NotReadableResourceException, ResourceException

      Reads the resource in a reactive way.

      Returns:
      a stream of ByteBuf
      Throws:
      NotReadableResourceException - if the resource is not readable
      ResourceException - if there was an error reading the resource

    • write

      default Publisher<Integer> write(Publisher<ByteBuf> data) throws NotWritableResourceException, ResourceException

      Writes content to the resource in a reactive way.

      Parameters:
      data - the stream of data to write
      Returns:
      a stream of integer emitting number of bytes written
      Throws:
      NotWritableResourceException - if the resource is not writable
      ResourceException - if there was an error writing to the resource

    • write

      default Publisher<Integer> write(Publisher<ByteBuf> data, boolean append) throws NotWritableResourceException, ResourceException

      Writes content to the resource in a reactive way appending or not content to an existing resource.

      Parameters:
      data - the stream of data to write
      append - true to append content to an existing resource
      Returns:
      a stream of integer emitting number of bytes written
      Throws:
      NotWritableResourceException - if the resource is not writable
      ResourceException - if there was an error writing to the resource

    • write

      Publisher<Integer> write(Publisher<ByteBuf> data, boolean append, boolean createParents) throws ResourceException

      Writes content to the resource in a reactive way appending or not content to an existing resource and create or not missing parent directories.

      Parameters:
      data - the stream of data to write
      append - true to append content to an existing resource
      createParents - true to create missing parent directories
      Returns:
      a stream of integer emitting number of bytes written
      Throws:
      ResourceException - if there was an error writing to the resource

    • delete

      boolean delete() throws ResourceException

      Deletes the resource.

      Returns:
      true if the resource had been deleted, false otherwise
      Throws:
      ResourceException - if there was an error deleting to the resource

    • resolve

      Resource resolve(Path path) throws ResourceException

      Resolves the specified URI against the resource URI as defined by Path.resolve(Path).

      Parameters:
      path - the path to resolve
      Returns:
      a new resource resulting from the resolution of the specified path against the resource
      Throws:
      ResourceException - if there was an error resolving the resource

    • resolve

      default Resource resolve(String path) throws ResourceException

      Resolves the specified path against the resource URI as defined by Path.resolve(String).

      Parameters:
      path - the path to resolve
      Returns:
      a new resource resulting from the resolution of the specified path against the resource
      Throws:
      ResourceException - if there was an error resolving the resource

    • close

      void close()
      Specified by:
      close in interface AutoCloseable