SLING-9676 - Improve Javadoc for MapEntriesHandler
diff --git a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java
index f7052e3..ee6cf34 100644
--- a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java
+++ b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntries.java
@@ -589,9 +589,6 @@
this.eventAdmin = null;
}
- /**
- * This is for the web console plugin
- */
@Override
public List<MapEntry> getResolveMaps() {
final List<MapEntry> entries = new ArrayList<>();
@@ -602,10 +599,6 @@
return Collections.unmodifiableList(entries);
}
- /**
- * Calculate the resolve maps. As the entries have to be sorted by pattern
- * length, we have to create a new list containing all relevant entries.
- */
@Override
public Iterator<MapEntry> getResolveMapsIterator(final String requestPath) {
String key = null;
diff --git a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java
index b162eb5..0087075 100644
--- a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java
+++ b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntriesHandler.java
@@ -24,9 +24,20 @@
import java.util.List;
import java.util.Map;
+import org.apache.sling.api.resource.ResourceResolver;
+import org.apache.sling.api.resource.mapping.ResourceMapper;
+import org.jetbrains.annotations.NotNull;
+
/**
- * Interface for MapEntries to only expose the public methods
- * used during resource resolving
+ * Exposes low-level methods used for resource resolving and mapping
+ *
+ * <p>This interface is intended for bundle internal use and its main goal is to
+ * prevent accidental modifications of the internal state by only exposing
+ * accessor methods.</p>
+ *
+ * @see ResourceMapper
+ * @see ResourceResolver#map(String)
+ * @see ResourceResolver#map(javax.servlet.http.HttpServletRequest, String)
*/
public interface MapEntriesHandler {
@@ -58,27 +69,55 @@
}
};
- Map<String, String> getAliasMap(String parentPath);
-
/**
- * Calculate the resolve maps. As the entries have to be sorted by pattern
- * length, we have to create a new list containing all relevant entries.
- */
- Iterator<MapEntry> getResolveMapsIterator(String requestPath);
-
- Collection<MapEntry> getMapMaps();
-
- /**
- * This is for the web console plugin
- */
- List<MapEntry> getResolveMaps();
-
- /*
- * Returns vanity path information
+ * Returns all alias entries that for children of the specified <tt>parentPath</tt>
*
- * <p>Maps resources paths to a list of vanity paths.</p>
+ * <p>The returned map has resource names as keys and aliases as values.</p>
+ *
+ * @param parentPath the parent path
+ * @return a map of all child alias entries, possibly empty
+ */
+ @NotNull Map<String, String> getAliasMap(@NotNull String parentPath);
+
+ /**
+ * Creates an iterator over the possibly applicable mapping entries for resolving a resource
+ *
+ * <p>This method uses the request path to filter out any unapplicable mapping entries and
+ * is therefore preferrable over {@link #getResolveMaps()}.</p>
+ *
+ * <p>The iterator will iterate over the mapping entries in the order of the pattern length.</p>
+ *
+ * @return the map entry iterator
+ */
+ @NotNull Iterator<MapEntry> getResolveMapsIterator(@NotNull String requestPath);
+
+ /**
+ * Return a flat listing of map entries used for mapping resources to URLs
+ *
+ * <p>This method returns information about all mapping rules. Note that vanity paths are excluded.</p>
+ *
+ * @return an unmodifiable collection of map entries
+ */
+ @NotNull Collection<MapEntry> getMapMaps();
+
+ /**
+ * Creates a flat listing of all the map entries used for resolving URLs to resources
+ *
+ * <p>This method returns information about all resolve rules, such as vanity paths, mapping entries,
+ * virtual URLs and URL mappings.</p>
+ *
+ * <p>This list is computed on-demand and therefore should not be used in performance-critical code.</p>
+ *
+ * @return an unmodifiable, sorted, list of resolution map entries
+ */
+ @NotNull List<MapEntry> getResolveMaps();
+
+ /**
+ * Returns vanity paths mappings
+ *
+ * <p>The keys in the map are resource paths and the values are the vanity mappings.</p>
*
* @return an unmodifiable list of vanity path mappings
*/
- Map<String, List<String>> getVanityPathMappings();
+ @NotNull Map<String, List<String>> getVanityPathMappings();
}
diff --git a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java
index 2fc2b56..af139bb 100644
--- a/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java
+++ b/src/main/java/org/apache/sling/resourceresolver/impl/mapping/MapEntry.java
@@ -33,9 +33,8 @@
/**
* The <code>MapEntry</code> class represents a mapping entry in the mapping
* configuration tree at <code>/etc/map</code>.
- * <p>
*
- * @see "http://cwiki.apache.org/SLING/flexible-resource-resolution.html"
+ * @see <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>
*/
public class MapEntry implements Comparable<MapEntry> {
@@ -268,7 +267,12 @@
this.order = order;
}
- // Returns the replacement or null if the value does not match
+ /**
+ * Replaces the specified value according to the rules of this entry
+ *
+ * @param value the value to replace
+ * @return a replaced value of <code>null</code> if the value does not match
+ */
public String[] replace(final String value) {
final Matcher m = urlPattern.matcher(value);
if (m.find()) {
