This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-resourceresolver.git
commit 081a2b95fdad64e789f4c4a5cc7eabec50d375de Author: Robert Munteanu <[email protected]> AuthorDate: Thu Aug 20 18:59:18 2020 +0200 SLING-9676 - Improve Javadoc for MapEntriesHandler --- .../resourceresolver/impl/mapping/MapEntries.java | 7 --- .../impl/mapping/MapEntriesHandler.java | 65 +++++++++++++++++----- .../resourceresolver/impl/mapping/MapEntry.java | 10 +++- 3 files changed, 59 insertions(+), 23 deletions(-) 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 @@ public class MapEntries implements 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 @@ public class MapEntries implements 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.Iterator; 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 @@ public interface MapEntriesHandler { } }; - Map<String, String> getAliasMap(String parentPath); + /** + * Returns all alias entries that for children of the specified <tt>parentPath</tt> + * + * <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); /** - * 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. + * 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 */ - Iterator<MapEntry> getResolveMapsIterator(String requestPath); + @NotNull Iterator<MapEntry> getResolveMapsIterator(@NotNull String requestPath); - Collection<MapEntry> getMapMaps(); + /** + * 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(); /** - * This is for the web console plugin + * 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 */ - List<MapEntry> getResolveMaps(); + @NotNull List<MapEntry> getResolveMaps(); - /* - * Returns vanity path information + /** + * Returns vanity paths mappings * - * <p>Maps resources paths to a list of vanity paths.</p> + * <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 @@ import org.slf4j.LoggerFactory; /** * 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 @@ public class MapEntry implements Comparable<MapEntry> { 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()) {
