content/documentation/extensions/mod_resources.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: Resources

[[Resources]]
== Tamaya Resources (Extension Module)

Tamaya _Resources_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.


=== What functionality this module provides ?

Tamaya _Resources_ defines some additional tools to locate resources in your classpath or file system based on
descriptive ant-styled resource patterns.


=== Compatibility

The module is based on Java 8.


=== Installation

To use this module add the following dependency:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <grooupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-resources</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== Usage

The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class
provides access to a +ResourceResolver+ instance:

[source,java]
-----------------------------------------------
ResourceResolver resolver = ConfigResources.getResourceResolver();
-----------------------------------------------

[source,java]
-----------------------------------------------
public interface ResourceResolver {

    static ResourceResolver getInstance();
    static ResourceResolver getInstance(ClassLoader classLoader);

    Collection<URL> getResources(Collection<String> expressions) {...}
    Collection<URL> getResources(String... expressions) {...}
}
-----------------------------------------------

Hereby the methods allow to resolve expressions to a collection of URLs. In case the expression is also targeting the
current classpath the target +ClassLoader+ to be used can be passed additionally.

The default implementation provides resource resolution mechanism similar to the functionality offered by Spring.
So by default resources can be looked up

* from files
* from the classpath
* optionally ant-styled expressions can be used.


=== Examples

There are numerous ways how a resource pattern can be defined. Following the most important variants
are listed:

[source,listing]
-----------------------------------------------
// explicitly searching the file system
file:myroot/aa?a/*.file
file:myroot/b*/b?/*.file
file:myroot/**/*.file

// explicitly searching the classpath
classpath:myroot/**/*.file
classpath:javax/annotation/*.class
classpath:javax/**/sql/*.class
classpath:javax/annotation/**/R*.class
classpath:javax/annotation/R?so*.class
classpath:META-INF/maven/org.apache.geronimo.specs/**/*

// search both classpath and files
javax/annotation/*.class
javax/**/sql/*.class
javax/annotation/**/R*.class
javax/annotation/R?so*.class
META-INF/maven/org.apache.geronimo.specs/**/*
myroot/**/*.file
myroot/aa?a/*.file
myroot/b*/b?/*.file
-----------------------------------------------

Summarizing the resources module provides useful functionality that helps to locate resources on the file system and
in the classpath. This can be used to implement +PropertySourceProvider+ implementations that are based on
corresponding resource path patterns instead of concrete files.


=== Overall Usage Example

Given the functionality we can easily implement a +PropertySourceProvider+ that reads all files from a classpath
location, hereby traversing down all folders:


[source, java]
-------------------------------------------------------------
public class PathBasedPropertySourceProvider implements PropertySourceProvider {

    @Override
    public Collection<PropertySource> getPropertySources() {
        List<PropertySource> propertySources = new ArrayList<>();
        Collection<URL> resources = ResourceResolver.getInstance().getResources("META-INF/cfg/**/*.properties");
        for(URL url:resources){
            Properties props = new Properties();
            try(InputStream is = url.openStream()){
                props.load(is);
                propertySources.add(new PropertiesBasedPropertySource(url.toString(), props));
            }
            catch(Exception e){
                e.printStackTrace();
            }
        }

        return propertySources;
    }

    private final static class PropertiesBasedPropertySource implements PropertySource {
        private String name;
        private Map<String,String> properties = new HashMap<>();

        public PropertiesBasedPropertySource(String name, Properties props) {
            this.name = name;
            props.forEach((k,v) -> this.properties.put(k.toString(), v.toString()));
        }

        @Override
        public String getName() {
            return name;
        }

        @Override
        public String get(String key) {
            return properties.get(key);
        }

        @Override
        public Map<String, String> getProperties() {
            return properties;
        }
    }
}
-------------------------------------------------------------


=== SPI

The +ResourceResolver+ that is returned is determined by the
current +ServiceContext+. You can replace the default implementation by registering an
alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+.