Merge pull request #8 from apache/SLING-8116
SLING-8116 implement OSGI Converter for default methods
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..0fa18e5
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,22 @@
+<!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~ 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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
+Apache Software Foundation Code of Conduct
+====
+
+Being an Apache project, Apache Sling adheres to the Apache Software Foundation's [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..ac82a1a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
+Contributing
+====
+
+Thanks for choosing to contribute!
+
+You will find all the necessary details about how you can do this at https://sling.apache.org/contributing.html.
diff --git a/pom.xml b/pom.xml
index 0aa7d14..3ed89b7 100644
--- a/pom.xml
+++ b/pom.xml
@@ -28,7 +28,7 @@
</parent>
<artifactId>org.apache.sling.api</artifactId>
- <version>2.18.5-SNAPSHOT</version>
+ <version>2.20.1-SNAPSHOT</version>
<packaging>bundle</packaging>
<name>Apache Sling API</name>
diff --git a/src/main/java/org/apache/sling/api/request/RequestPathInfo.java b/src/main/java/org/apache/sling/api/request/RequestPathInfo.java
index 90dce48..ce07ae3 100644
--- a/src/main/java/org/apache/sling/api/request/RequestPathInfo.java
+++ b/src/main/java/org/apache/sling/api/request/RequestPathInfo.java
@@ -52,11 +52,12 @@
* request URI, the extension is empty.
* <li>{@link #getSuffix() suffix path} - If the request URI contains a slash
* character after the content path and optional selectors and extension, the
- * path starting with the slash upto the end of the request URI is the suffix
+ * path starting with the slash up to the end of the request URI is the suffix
* path.
* </ol>
* <p>
- * Examples: <table summary="">
+ * Examples: <table>
+ * <caption>URI decomposition</caption>
* <tr>
* <th>URI</th>
* <th>Content Path</th>
diff --git a/src/main/java/org/apache/sling/api/resource/AbstractResourceVisitor.java b/src/main/java/org/apache/sling/api/resource/AbstractResourceVisitor.java
index 20f8fc3..e152a5f 100644
--- a/src/main/java/org/apache/sling/api/resource/AbstractResourceVisitor.java
+++ b/src/main/java/org/apache/sling/api/resource/AbstractResourceVisitor.java
@@ -23,11 +23,13 @@
import org.jetbrains.annotations.NotNull;
/**
- * The <code>AbstractResourceVisitor</code> helps in traversing a
- * resource tree by decoupling the actual traversal code
- * from application code. Concrete subclasses should implement
- * the {@link AbstractResourceVisitor#visit(Resource)} method.
+ * This visitor will traverse the given resource and all its children in a breadth-first approach
+ * and call the {@link AbstractResourceVisitor#visit(Resource)} method for each visited resource.
+ * It decouples the actual traversal code from application code.
+ *
+ * Concrete subclasses must implement the {@link AbstractResourceVisitor#visit(Resource)} method.
*
+ * @see <a href="https://en.wikipedia.org/wiki/Breadth-first_search">Breadth-First-Search</a>
* @since 2.2 (Sling API Bundle 2.2.0)
*/
public abstract class AbstractResourceVisitor {
diff --git a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
index c3b476d..8a2b27d 100644
--- a/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
+++ b/src/main/java/org/apache/sling/api/resource/ResourceResolver.java
@@ -57,7 +57,8 @@
* <code>resolve</code> methods and the <code>getResource</code> methods. The
* difference lies in the algorithm applied to find the requested resource and
* in the behavior in case a resource cannot be found:
- * <table summary="">
+ * <table>
+ * <caption>Accessing Resources</caption>
* <tr>
* <th>Method Kind</th>
* <th>Access Algorithm</th>
@@ -198,6 +199,7 @@
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
* @since 2.0.4 (Sling API Bundle 2.0.4)
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
*/
@NotNull Resource resolve(@NotNull HttpServletRequest request, @NotNull String absPath);
@@ -226,6 +228,7 @@
* thrown if an error occurs trying to resolve the resource.
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
*/
@NotNull Resource resolve(@NotNull String absPath);
@@ -253,12 +256,13 @@
* {@link #close() closed}.
* @deprecated as of 2.0.4, use {@link #resolve(HttpServletRequest, String)}
* instead.
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
*/
@Deprecated
@NotNull Resource resolve(@NotNull HttpServletRequest request);
/**
- * Returns a path mapped from the (resource) path applying the reverse
+ * Returns a (request) path mapped from the (resource) path applying the reverse
* mapping used by the {@link #resolve(String)} such that when the path is
* given to the {@link #resolve(String)} method the same resource is
* returned.
@@ -272,13 +276,20 @@
* <p>
* This method is intended as the reverse operation of the
* {@link #resolve(String)} method.
+ * <p>
+ * This method also does percent-encoding before returning the (request) path
+ * (with charset UTF-8). Due to this calling this method multiple times in a nested
+ * fashion might lead to an invalid (request) path which can subsequently not
+ * be resolved via {@link #resolve(String)}.
*
* @param resourcePath The path for which to return a mapped path.
* @return The mapped path.
* @throws IllegalStateException if this resource resolver has already been
* {@link #close() closed}.
*
- * @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
+ * @see ResourceMapper#getMapping(String, HttpServletRequest)
+ * @see <a href="https://tools.ietf.org/html/rfc3986#section-2.1">Percent-Encoding</a>
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
*/
@NotNull String map(@NotNull String resourcePath);
@@ -300,6 +311,11 @@
* {@link #resolve(HttpServletRequest, String)} method. As such the URL
* returned is expected to be an absolute URL including scheme, host, any
* servlet context path and the actual path used to resolve the resource.
+ * <p>
+ * This method also does percent-encoding before returning the URL
+ * (with charset UTF-8). Due to this calling this method multiple times in a nested
+ * fashion might lead to an invalid URL which can subsequently not
+ * be resolved via {@link #resolve(String)}.
*
* @param request The http servlet request object which may be used to apply
* more mapping functionality.
@@ -309,7 +325,9 @@
* {@link #close() closed}.
* @since 2.0.4 (Sling API Bundle 2.0.4)
*
- * @see {@link ResourceMapper#getMapping(String, HttpServletRequest)}
+ * @see ResourceMapper#getMapping(String, HttpServletRequest)
+ * @see <a href="https://tools.ietf.org/html/rfc3986#section-2.1">Percent-Encoding</a>
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
*/
@Nullable String map(@NotNull HttpServletRequest request, @NotNull String resourcePath);
diff --git a/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java b/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
index 53086d5..a302469 100644
--- a/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
+++ b/src/main/java/org/apache/sling/api/resource/mapping/ResourceMapper.java
@@ -96,7 +96,7 @@
@NotNull String getMapping(@NotNull String resourcePath, @NotNull HttpServletRequest request);
/**
- * Retuns all possible mappings for a given <tt>resourcePath</tt> as paths.
+ * Returns all possible mappings for a given {@code resourcePath} as paths.
*
* <p>
* This method differs from the {@link #getMapping(String)} variant
@@ -114,7 +114,7 @@
Collection<String> getAllMappings(@NotNull String resourcePath);
/**
- * Retuns all possible mappings for a given <tt>resourcePath</tt> as URLs.
+ * Returns all possible mappings for a given {@code resourcePath} as URLs.
*
* <p>
* This method differs from the {@link #getMapping(String, HttpServletRequest)} variant
diff --git a/src/main/java/org/apache/sling/api/resource/path/PathBuilder.java b/src/main/java/org/apache/sling/api/resource/path/PathBuilder.java
index f7f3334..72c9950 100644
--- a/src/main/java/org/apache/sling/api/resource/path/PathBuilder.java
+++ b/src/main/java/org/apache/sling/api/resource/path/PathBuilder.java
@@ -19,7 +19,7 @@
package org.apache.sling.api.resource.path;
/**
- * The <tt>PathBuilder</tt> offers a convenient way of creating a valid path from multiple fragments
+ * The {@code PathBuilder} offers a convenient way of creating a valid path from multiple fragments
*
* @since 1.0.0 (Sling API Bundle 2.11.0)
*/
@@ -28,7 +28,7 @@
private final StringBuilder sb = new StringBuilder();
/**
- * Creates a new <tt>PathBuilder</tt> instance
+ * Creates a new {@code PathBuilder} instance
*
* @param path the initial path
*/
@@ -76,4 +76,4 @@
public String toString() {
return sb.toString();
}
-}
\ No newline at end of file
+}
diff --git a/src/main/java/org/apache/sling/api/servlets/ServletResolverConstants.java b/src/main/java/org/apache/sling/api/servlets/ServletResolverConstants.java
index 9ce3d08..b1caca6 100644
--- a/src/main/java/org/apache/sling/api/servlets/ServletResolverConstants.java
+++ b/src/main/java/org/apache/sling/api/servlets/ServletResolverConstants.java
@@ -64,6 +64,17 @@
public static final String SLING_SERVLET_RESOURCE_TYPES = "sling.servlet.resourceTypes";
/**
+ * The name of the service registration property of a servlet registered as
+ * a service containing the resource super type supported by the servlet (value
+ * is "sling.servlet.resourceSuperType").
+ * <p>
+ * The type of this property is a String denoting the resource super type. This
+ * property is ignored if the {@link #SLING_SERVLET_RESOURCE_TYPES} property is
+ * not set. Otherwise this property is optional and ignored if not set.
+ */
+ public static final String SLING_SERVLET_RESOURCE_SUPER_TYPE = "sling.servlet.resourceSuperType";
+
+ /**
* <p>
* The name of the service registration property of a servlet registered as
* a service providing the prefix/index to be used to register this servlet.
diff --git a/src/main/java/org/apache/sling/api/servlets/package-info.java b/src/main/java/org/apache/sling/api/servlets/package-info.java
index b018388..bb2595a 100644
--- a/src/main/java/org/apache/sling/api/servlets/package-info.java
+++ b/src/main/java/org/apache/sling/api/servlets/package-info.java
@@ -17,7 +17,7 @@
* under the License.
*/
-@Version("2.2.1")
+@Version("2.3.0")
package org.apache.sling.api.servlets;
import org.osgi.annotation.versioning.Version;
