This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-caconfig-api.git
commit 2c0f4039f27391c7c91c441627780c7b152e124b Author: Stefan Seifert <[email protected]> AuthorDate: Thu Dec 22 09:52:16 2016 +0000 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 --- README.txt | 25 ++++++ pom.xml | 70 +++++++++++++++++ .../sling/caconfig/ConfigurationBuilder.java | 90 ++++++++++++++++++++++ .../caconfig/ConfigurationResolveException.java | 38 +++++++++ .../sling/caconfig/ConfigurationResolver.java | 46 +++++++++++ .../sling/caconfig/annotation/Configuration.java | 58 ++++++++++++++ .../apache/sling/caconfig/annotation/Property.java | 53 +++++++++++++ .../sling/caconfig/annotation/package-info.java | 23 ++++++ .../org/apache/sling/caconfig/package-info.java | 23 ++++++ .../resource/ConfigurationResourceResolver.java | 77 ++++++++++++++++++ .../sling/caconfig/resource/package-info.java | 24 ++++++ 11 files changed, 527 insertions(+) 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. + */ [email protected]("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. + */ [email protected]("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. + */ [email protected]("1.0.0") +package org.apache.sling.caconfig.resource;
