Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@tamaya.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: anatole@apache.org
To: commits@tamaya.incubator.apache.org
Date: Tue, 03 Mar 2015 16:38:35 -0000
Message-Id: <d60ee9318123455c9ad5cb24306d11d6@git.apache.org>
Subject: [1/3] incubator-tamaya git commit: Added documentation for the
 resources module.

Repository: incubator-tamaya
Updated Branches:
  refs/heads/master a375f26f2 -> 566988f87


Added documentation for the resources module.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/a77b0895
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/a77b0895
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/a77b0895

Branch: refs/heads/master
Commit: a77b0895043563b4a9ce136012b1f98d8457b7fd
Parents: a375f26
Author: anatole <anatole@apache.org>
Authored: Tue Mar 3 17:28:56 2015 +0100
Committer: anatole <anatole@apache.org>
Committed: Tue Mar 3 17:28:56 2015 +0100

----------------------------------------------------------------------
 docs/mod_resources.adoc | 175 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 175 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/a77b0895/docs/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/docs/mod_resources.adoc b/docs/mod_resources.adoc
new file mode 100644
index 0000000..5ded965
--- /dev/null
+++ b/docs/mod_resources.adoc
@@ -0,0 +1,175 @@
+Apache Tamaya -- Extension: Resources
+==================================
+:name: Tamaya
+:rootpackage: org.apache.tamaya.ext.resources
+:title: Apache Tamaya Extension: Resources
+:revnumber: 0.1.1
+:revremark: Incubator
+:revdate: March 2015
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <anatole@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:iconsdir: {imagesdir}/icons
+:toc:
+:toc-placement: manual
+:icons:
+:encoding: UTF-8
+:numbered:
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[Core]]
+== Tamaya Resources (Extension Module)
+=== Overview
+
+Tamaya Resources is an extension module. Refer to the link::modules.html[extensions documentation] for further details
+about modules.
+
+Tamaya Resources defines some additional tools to locate resources in your classpath or file system based on descriptive
+ant-styled resource patterns. To use this module add the following dependency:
+
+[source, listing]
+-----------------------------------------------
+<dependency>
+  <grooupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-resources</artifactId>
+  <version>CURRENT_VERSION</version>
+</dependency>
+-----------------------------------------------
+
+
+The module's main entry point is the singleton class +org.apache.tamaya.resource.Resources+. This class provides
+access to a +ResourceResolver+ instance:
+
+[source,java]
+-----------------------------------------------
+public interface ResourceResolver {
+    default Collection<URL> getResources(Collection<String> expressions) {...}
+    default Collection<URL> getResources(String... expressions) {...}
+    default Collection<URL> getResources(ClassLoader classLoader, String... expressions){...}
+    Collection<URL> getResources(ClassLoader classLoader, Collection<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.
+
+
+=== Valid Expression 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 = Resources.getResourceResolver().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;
+        }
+    }
+
+}
+-------------------------------------------------------------
+