You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by cz...@apache.org on 2019/06/23 15:07:46 UTC
[sling-org-apache-sling-feature] 01/02: Javadoc updates
This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-feature.git
commit cd2637df37d6f114891635e280518102d61fb85f
Author: Carsten Ziegeler <cz...@apache.org>
AuthorDate: Sun Jun 23 16:56:22 2019 +0200
Javadoc updates
---
.../sling/feature/builder/BuilderContext.java | 31 ++++++++++++++--------
.../apache/sling/feature/builder/BuilderUtil.java | 6 ++---
.../apache/sling/feature/builder/MergeHandler.java | 10 +++++--
.../sling/feature/builder/PostProcessHandler.java | 6 ++++-
4 files changed, 35 insertions(+), 18 deletions(-)
diff --git a/src/main/java/org/apache/sling/feature/builder/BuilderContext.java b/src/main/java/org/apache/sling/feature/builder/BuilderContext.java
index 8fb53a7..17e9286 100644
--- a/src/main/java/org/apache/sling/feature/builder/BuilderContext.java
+++ b/src/main/java/org/apache/sling/feature/builder/BuilderContext.java
@@ -64,6 +64,9 @@ public class BuilderContext {
/** Used in override rule to match all coordinates */
public static final String COORDINATE_MATCH_ALL = "*";
+ /** Configuration key for configuration for all handlers */
+ static final String CONFIGURATION_ALL_HANDLERS_KEY = "all";
+
/** The required feature provider */
private final FeatureProvider provider;
@@ -79,9 +82,9 @@ public class BuilderContext {
/**
- * Create a new context
+ * Create a new context.
*
- * @param provider A provider providing the included features
+ * @param provider A provider providing the prototype features
* @throws IllegalArgumentException If feature provider is {@code null}
*/
public BuilderContext(final FeatureProvider provider) {
@@ -92,9 +95,11 @@ public class BuilderContext {
}
/**
- * Set the artifact provider
+ * Set the artifact provider. While the artifact provider is not required by the
+ * general assembly and merging algorithms, handlers for extensions might need
+ * it.
*
- * @param ap An ArtifactProvider to resolve artifact IDs to files
+ * @param ap An ArtifactProvider to resolve artifact IDs to URLs
* @return The builder context
*/
public BuilderContext setArtifactProvider(final ArtifactProvider ap) {
@@ -103,7 +108,7 @@ public class BuilderContext {
}
/**
- * Add overrides for the variables
+ * Add overrides for the variables.
*
* @param vars The overrides
* @return The builder context
@@ -114,7 +119,7 @@ public class BuilderContext {
}
/**
- * Add overrides for the framework properties
+ * Add overrides for the framework properties.
*
* @param props The overrides
* @return The builder context
@@ -125,7 +130,7 @@ public class BuilderContext {
}
/**
- * Add overrides for artifact clashes
+ * Add overrides for artifact clashes.
*
* @param overrides The overrides
* @return The builder context
@@ -140,7 +145,7 @@ public class BuilderContext {
}
/**
- * Add an override for artifact clashes
+ * Add an override for artifact clashes.
*
* @param override The override
* @return The builder context
@@ -153,7 +158,7 @@ public class BuilderContext {
/**
* Add merge extensions
*
- * @param extensions A list of merge extensions
+ * @param extensions A list of merge extensions.
* @return The builder context
*/
public BuilderContext addMergeExtensions(final MergeHandler... extensions) {
@@ -173,10 +178,14 @@ public class BuilderContext {
}
/**
- * Set a handler configuration
+ * Set a handler configuration. A configuration can be set for both
+ * {@link MergeHandler}s and {@link PostProcessHandler}s. The name of a handler
+ * is the simple class name of the class implementing the handler. To pass the
+ * same configuration to all handlers, use the
+ * {@link #CONFIGURATION_ALL_HANDLERS_KEY} name.
*
* @param name The name of the handler
- * @param cfg The configuration for the handler
+ * @param cfg The configuration for the handler
* @return The builder context
*/
public BuilderContext setHandlerConfiguration(final String name, final Map<String,String> cfg) {
diff --git a/src/main/java/org/apache/sling/feature/builder/BuilderUtil.java b/src/main/java/org/apache/sling/feature/builder/BuilderUtil.java
index 72a7fb6..f58d2b9 100644
--- a/src/main/java/org/apache/sling/feature/builder/BuilderUtil.java
+++ b/src/main/java/org/apache/sling/feature/builder/BuilderUtil.java
@@ -60,9 +60,6 @@ class BuilderUtil {
/** Used in override rule to have it apply to all artifacts. */
static final String CATCHALL_OVERRIDE = "*:*:";
- /** Configuration key for configuration for all handlers */
- static final String ALL_HANDLERS_KEY = "all";
-
static boolean contains(String key, Iterable<Map.Entry<String, String>> iterable) {
if (iterable != null) {
for (Map.Entry<String, String> entry : iterable) {
@@ -571,7 +568,8 @@ class BuilderUtil {
private Map<String,String> getHandlerConfiguration(BuilderContext bc, Object handler) {
final Map<String,String> result = new HashMap<>();
- Map<String, String> overall = bc.getHandlerConfigurations().get(ALL_HANDLERS_KEY);
+ Map<String, String> overall = bc.getHandlerConfigurations()
+ .get(BuilderContext.CONFIGURATION_ALL_HANDLERS_KEY);
if (overall != null)
result.putAll(overall);
final String name = getHandlerName(handler);
diff --git a/src/main/java/org/apache/sling/feature/builder/MergeHandler.java b/src/main/java/org/apache/sling/feature/builder/MergeHandler.java
index c62b426..9c92e13 100644
--- a/src/main/java/org/apache/sling/feature/builder/MergeHandler.java
+++ b/src/main/java/org/apache/sling/feature/builder/MergeHandler.java
@@ -21,12 +21,18 @@ import org.apache.sling.feature.Feature;
import org.osgi.annotation.versioning.ConsumerType;
/**
- * A feature merge handler can merge a feature of a particular type.
+ * A merge handler can merge an extension of a particular type. The handlers are
+ * passed in to the {@link FeatureBuilder} via
+ * {@link BuilderContext#addMergeExtensions(MergeHandler...)}. When the feature
+ * builder is merging features, the first handler that returns {@code true} for
+ * an extension in {@link #canMerge(Extension)} merges the extension. Further
+ * handlers are not tested anymore.
*/
@ConsumerType
public interface MergeHandler {
/**
- * Checks whether this merger can merge extensions with that name
+ * Checks whether this merger can merge the given extension.
+ *
* @param extension The extension
* @return {@code true} if merger can handle this
*/
diff --git a/src/main/java/org/apache/sling/feature/builder/PostProcessHandler.java b/src/main/java/org/apache/sling/feature/builder/PostProcessHandler.java
index 7717ff0..08f8aad 100644
--- a/src/main/java/org/apache/sling/feature/builder/PostProcessHandler.java
+++ b/src/main/java/org/apache/sling/feature/builder/PostProcessHandler.java
@@ -21,7 +21,11 @@ import org.apache.sling.feature.Feature;
import org.osgi.annotation.versioning.ConsumerType;
/**
- * A Post Process Handler processes features after a merge operation.
+ * A Post Process Handler processes features after a merge operation. The
+ * handlers are passed in to the {@link FeatureBuilder} via
+ * {@link BuilderContext#addPostProcessExtensions(PostProcessHandler...)}. Once
+ * all extensions are merged, all post processor handlers are called for each
+ * extension in the target feature.
*/
@ConsumerType
public interface PostProcessHandler {