SLING-6427 Move Sling Context-Aware Config out of contrib
- move in svn
- update all SCM URLs
- update jenkins build jobs

git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1775601 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..2cf6174
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,25 @@
+Apache Sling Context-Aware Configuration API
+
+
+Getting Started
+===============
+
+This component uses a Maven 3 (http://maven.apache.org/) build
+environment. It requires a Java 7 JDK (or higher) and Maven (http://maven.apache.org/)
+3.3.9 or later. We recommend to use the latest Maven version.
+
+If you have Maven 3 installed, you can compile and
+package the jar using the following command:
+
+    mvn package
+
+See the Maven 3 documentation for other build features.
+
+The latest source code for this component is available in the
+Subversion (http://subversion.tigris.org/) source repository of
+the Apache Software Foundation. If you have Subversion installed,
+you can checkout the latest source using the following command:
+
+    svn checkout https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/contextaware-config/api
+
+See the Subversion documentation for other source control features.
diff --git a/pom.xml b/pom.xml
new file mode 100644
index 0000000..3e24abd
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.apache.sling</groupId>
+        <artifactId>sling</artifactId>
+        <version>29</version>
+        <relativePath />
+    </parent>
+    
+    <artifactId>org.apache.sling.caconfig.api</artifactId>
+    <packaging>bundle</packaging>
+    <version>1.1.1-SNAPSHOT</version>
+    <name>Apache Sling Context-Aware Configuration API</name>
+    <description>Apache Sling Context-Aware Configuration API</description>
+
+    <scm>
+        <connection>scm:svn:http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/caconfig/api</connection>
+        <developerConnection>scm:svn:https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/caconfig/api</developerConnection>
+        <url>http://svn.apache.org/viewvc/sling/trunk/bundles/extensions/caconfig/api</url>
+    </scm>
+    
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.felix</groupId>
+                <artifactId>maven-bundle-plugin</artifactId>
+                <extensions>true</extensions>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.google.code.findbugs</groupId>
+            <artifactId>jsr305</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.sling</groupId>
+            <artifactId>org.apache.sling.api</artifactId>
+            <version>2.9.0</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+</project>
diff --git a/src/main/java/org/apache/sling/caconfig/ConfigurationBuilder.java b/src/main/java/org/apache/sling/caconfig/ConfigurationBuilder.java
new file mode 100644
index 0000000..be06432
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/ConfigurationBuilder.java
@@ -0,0 +1,90 @@
+/*
+ * 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.
+ */
+package org.apache.sling.caconfig;
+
+import java.util.Collection;
+
+import javax.annotation.Nonnull;
+
+import org.apache.sling.api.resource.ValueMap;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Defines how the configuration should be mapped and returned.
+ */
+@ProviderType
+public interface ConfigurationBuilder {
+
+    /**
+     * Define configuration name.
+     * Optional for the {@link #as(Class)} and {@link #asCollection(Class)} methods, mandatory for the others. 
+     * @param configName Relative path
+     * @return Configuration builder
+     */
+    @Nonnull ConfigurationBuilder name(@Nonnull String configName);
+
+    /**
+     * Get configuration as singleton resource and its properties mapped to the given annotation class.
+     * Configuration name is optional - if not given via {@link #name(String)} method it is derived
+     * from the annotation interface class name.
+     * @param clazz Annotation interface class
+     * @param <T> Annotation class type
+     * @return Configuration object. Contains only the default values if content resource or configuration cannot be found.
+     */
+    @Nonnull <T> T as(@Nonnull Class<T> clazz);
+
+    /**
+     * Get collection of configuration resources with their properties mapped to the given annotation class.
+     * Configuration name is optional - if not given via {@link #name(String)} method it is derived
+     * from the annotation interface class name.
+     * @param clazz Annotation interface class
+     * @param <T> Annotation class type
+     * @return Collection of configuration objects. Is empty if content resource or configuration cannot be found.
+     */
+    @Nonnull <T> Collection<T> asCollection(@Nonnull Class<T> clazz);
+
+    /**
+     * Get configuration as singleton resource and return its properties as value map.
+     * @return Value map. Map is empty if content resource or configuration cannot be found.
+     */
+    @Nonnull ValueMap asValueMap();
+
+    /**
+     * Get collection of configuration resources with their properties mapped to the given annotation class.
+     * @return Collection of value map. Is empty if content resource or configuration cannot be found.
+     */
+    @Nonnull Collection<ValueMap> asValueMapCollection();
+
+    /**
+     * Get configuration as singleton configuration resource and adapt it to the given class.
+     * @param clazz Class that can be adapted from a {@link org.apache.sling.api.resource.Resource}
+     * @param <T> Annotation class type
+     * @return Object instance or null if content resource or configuration cannot be found or if the adaption was not possible.
+     */
+    <T> T asAdaptable(@Nonnull Class<T> clazz);
+
+    /**
+     * Get collection of configuration resources and adapt them to the given class.
+     * @param clazz Class that can be adapted from a {@link org.apache.sling.api.resource.Resource}
+     * @param <T> Annotation class type
+     * @return Collection of object instances. Is empty if content resource or configuration cannot be found or if the adaption was not possible.
+     */
+    @Nonnull <T> Collection<T> asAdaptableCollection(@Nonnull Class<T> clazz);
+
+}
diff --git a/src/main/java/org/apache/sling/caconfig/ConfigurationResolveException.java b/src/main/java/org/apache/sling/caconfig/ConfigurationResolveException.java
new file mode 100644
index 0000000..ae4a650
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/ConfigurationResolveException.java
@@ -0,0 +1,38 @@
+/*
+ * 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.
+ */
+package org.apache.sling.caconfig;
+
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Is thrown when configuration cannot be resolved.
+ */
+@ProviderType
+public final class ConfigurationResolveException extends RuntimeException {
+    private static final long serialVersionUID = 1L;
+
+    public ConfigurationResolveException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public ConfigurationResolveException(String message) {
+        super(message);
+    }
+
+}
diff --git a/src/main/java/org/apache/sling/caconfig/ConfigurationResolver.java b/src/main/java/org/apache/sling/caconfig/ConfigurationResolver.java
new file mode 100644
index 0000000..885daf4
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/ConfigurationResolver.java
@@ -0,0 +1,46 @@
+/*
+ * 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.
+ */
+package org.apache.sling.caconfig;
+
+import javax.annotation.Nonnull;
+
+import org.apache.sling.api.resource.Resource;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Getting context-aware configurations for a given resource context.
+ * Context-specific configuration may be different for different parts of the resource
+ * hierarchy, and configuration parameter inheritance may take place.
+ *
+ * This service builds on top of the {@link org.apache.sling.caconfig.resource.ConfigurationResourceResolver}
+ * and uses that service to resolve configuration resources. These resources
+ * can then be converted into application specific configuration objects
+ * using the {@link ConfigurationBuilder}.
+ */
+@ProviderType
+public interface ConfigurationResolver {
+
+    /**
+     * Get configuration for given resource.
+     * @param resource Context resource
+     * @return Configuration builder
+     */
+    @Nonnull ConfigurationBuilder get(@Nonnull Resource resource);
+
+}
diff --git a/src/main/java/org/apache/sling/caconfig/annotation/Configuration.java b/src/main/java/org/apache/sling/caconfig/annotation/Configuration.java
new file mode 100644
index 0000000..c5aa8f8
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/annotation/Configuration.java
@@ -0,0 +1,58 @@
+/*
+ * 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.
+ */
+package org.apache.sling.caconfig.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks an annotation class to be useable with Sling context-aware configuration. 
+ */
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Configuration {
+
+    /**
+     * @return Allows to overwrite the configuration name. If not set the class name of the annotation is used.
+     */
+    String name() default "";
+    
+    /**
+     * @return Label for the resource (e.g. for configuration editor GUIs).
+     */
+    String label() default "";
+    
+    /**
+     * @return Description for the resource (e.g. for configuration editor GUIs).
+     */
+    String description() default "";
+    
+    /**
+     * @return Further properties e.g. for configuration editor GUIs.
+     */
+    String[] property() default {};
+    
+    /**
+     * @return Indicates that this definition should be used for configuration collections.
+     */
+    boolean collection() default false;
+
+}
diff --git a/src/main/java/org/apache/sling/caconfig/annotation/Property.java b/src/main/java/org/apache/sling/caconfig/annotation/Property.java
new file mode 100644
index 0000000..579c751
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/annotation/Property.java
@@ -0,0 +1,53 @@
+/*
+ * 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.
+ */
+package org.apache.sling.caconfig.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Adds further metadata for properties of context-aware configuration annotation classes.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Property {
+
+    /**
+     * @return Label for the property (e.g. for configuration editor GUIs).
+     */
+    String label() default "";
+    
+    /**
+     * @return Description for the property (e.g. for configuration editor GUIs).
+     */
+    String description() default "";
+    
+    /**
+     * @return Further properties e.g. for configuration editor GUIs.
+     */
+    String[] property() default {};
+    
+    /**
+     * @return Number to control property order in configuration editor.
+     */
+    int order() default 0;
+    
+}
diff --git a/src/main/java/org/apache/sling/caconfig/annotation/package-info.java b/src/main/java/org/apache/sling/caconfig/annotation/package-info.java
new file mode 100644
index 0000000..d4ef2b2
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/annotation/package-info.java
@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+/**
+ * Annotations for context-aware configurations.
+ */
+@org.osgi.annotation.versioning.Version("1.1.0")
+package org.apache.sling.caconfig.annotation;
diff --git a/src/main/java/org/apache/sling/caconfig/package-info.java b/src/main/java/org/apache/sling/caconfig/package-info.java
new file mode 100644
index 0000000..5a7580a
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/package-info.java
@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+/**
+ * API for accessing context-aware configuration.
+ */
+@org.osgi.annotation.versioning.Version("1.0.0")
+package org.apache.sling.caconfig;
diff --git a/src/main/java/org/apache/sling/caconfig/resource/ConfigurationResourceResolver.java b/src/main/java/org/apache/sling/caconfig/resource/ConfigurationResourceResolver.java
new file mode 100644
index 0000000..12f13c3
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/resource/ConfigurationResourceResolver.java
@@ -0,0 +1,77 @@
+/*
+ * 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.
+ */
+package org.apache.sling.caconfig.resource;
+
+import java.util.Collection;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
+import org.apache.sling.api.resource.Resource;
+import org.osgi.annotation.versioning.ProviderType;
+
+/**
+ * Getting context-aware configuration resources for a given resource context.
+ * This is a low-level interface for supporting advanced use cases. If you just want to fetch
+ * some configuration parameters {@link org.apache.sling.caconfig.ConfigurationResolver}
+ * is the right place.
+ */
+@ProviderType
+public interface ConfigurationResourceResolver {
+
+    /**
+     * Get a context-aware singleton configuration resource defined by the given configuration name.
+     *
+     * @param resource Context resource to fetch configuration for
+     * @param bucketName Configuration "bucket" name. Each high-level configuration resolver should store 
+     *     it's configuration data grouped in a child resource of the configuration resource. This is what
+     *     we call a "bucket", and the resource name is specified with this parameter.
+     * @param configName Configuration name or relative path.
+     * @return Configuration resource or {@code null}.
+     */
+    @CheckForNull Resource getResource(@Nonnull Resource resource, @Nonnull String bucketName, @Nonnull String configName);
+
+    /**
+     * Get a collection of context-aware configuration resources defined by the given configuration name.
+     * @param resource Context resource to fetch configuration for
+     * @param bucketName Configuration "bucket" name. Each high-level configuration resolver should store 
+     *     it's configuration data grouped in a child resource of the configuration resource. This is what
+     *     we call a "bucket", and the resource name is specified with this parameter.
+     * @param configName Configuration name or relative path.
+     * @return Collection of configuration resources, the collection might be empty.
+     */
+    @Nonnull Collection<Resource> getResourceCollection(@Nonnull Resource resource, @Nonnull String bucketName, @Nonnull String configName);
+
+    /**
+     * Get the inner-most context path (deepest path) returned by {@link #getAllContextPaths(Resource)}.
+     * @param resource Context resource to fetch configuration for
+     * @return Context path or null
+     */
+    String getContextPath(@Nonnull Resource resource);
+
+    /**
+     * Get all context paths for which context-aware configurations could be defined.
+     * The context paths are always ancestors of the resource path, or the resource path itself.
+     * Which ancestors are allowed for context-aware configuration depends on configuration.
+     * @param resource Context resource to fetch configuration for
+     * @return List of context paths
+     */
+    @Nonnull Collection<String> getAllContextPaths(@Nonnull Resource resource);
+
+}
diff --git a/src/main/java/org/apache/sling/caconfig/resource/package-info.java b/src/main/java/org/apache/sling/caconfig/resource/package-info.java
new file mode 100644
index 0000000..ef04a94
--- /dev/null
+++ b/src/main/java/org/apache/sling/caconfig/resource/package-info.java
@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+/**
+ * API for accessing context-aware configuration resources.
+ * This is a low-level API.
+ */
+@org.osgi.annotation.versioning.Version("1.0.0")
+package org.apache.sling.caconfig.resource;