1 /*
2 * #%L
3 * wcm.io
4 * %%
5 * Copyright (C) 2014 wcm.io
6 * %%
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * #L%
19 */
20 package io.wcm.handler.url;
21
22 import org.apache.sling.api.resource.Resource;
23 import org.jetbrains.annotations.NotNull;
24 import org.jetbrains.annotations.Nullable;
25 import org.osgi.annotation.versioning.ProviderType;
26
27 import com.day.cq.wcm.api.Page;
28
29 /**
30 * Rewrites and builds URLs for links to content pages and resources.
31 *
32 * <p>
33 * The interface is implemented by a Sling Model. You can adapt from
34 * {@link org.apache.sling.api.SlingHttpServletRequest} or {@link org.apache.sling.api.resource.Resource} to get a
35 * context-specific handler instance.
36 * </p>
37 */
38 @ProviderType
39 public interface UrlHandler {
40
41 /**
42 * Selector that is always added if a Sling-URL contains a suffix (to avoid files and directories with same name in
43 * dispatcher cache)
44 */
45 @NotNull
46 String SELECTOR_SUFFIX = "suffix";
47
48 /**
49 * Builds and optionally externalizes an URL using a builder pattern.
50 * @param path Path to start URL building with
51 * @return URL builder which allows to chain further optional parameters before building the URL string.
52 */
53 @NotNull
54 UrlBuilder get(@NotNull String path);
55
56 /**
57 * Builds and optionally externalizes an URL using a builder pattern.
58 * @param resource Resource, URL building is started with its path
59 * @return URL builder which allows to chain further optional parameters before building the URL string.
60 */
61 @NotNull
62 UrlBuilder get(@NotNull Resource resource);
63
64 /**
65 * Builds and optionally externalizes an URL using a builder pattern.
66 * @param page Page Page, URL building is started with its path
67 * @return URL builder which allows to chain further optional parameters before building the URL string.
68 */
69 @NotNull
70 UrlBuilder get(@NotNull Page page);
71
72 /**
73 * Rewrites given path to current site or context.
74 * The site root path is replaced with the one from current site
75 * This is useful if a link to an internal page points to a page outside the site (e.g. because the page containing
76 * the link was copied from the other site or inherited). When the AEM built-in rewrite logic was not applied the link
77 * would be invalid. This methods rewrites the link path to the current site to try to resolve it there.
78 * @param resource Resource to rewrite path from
79 * @return Rewritten path or null if resource invalid
80 */
81 @Nullable
82 String rewritePathToContext(@NotNull Resource resource);
83
84 /**
85 * Rewrites given path to given site or context.
86 * The site root path is replaced with the one from current site.
87 * This is useful if a link to an internal page points to a page outside the site (e.g. because the page containing
88 * the link was copied from the other site or inherited). When the AEM built-in rewrite logic was not applied the link
89 * would be invalid. This methods rewrites the link path to the current site to try to resolve it there.
90 * @param resource Resource to rewrite path from
91 * @param contextResource Context resource to which the path should be rewritten to
92 * @return Rewritten path or null if resource or context resource is invalid
93 */
94 @Nullable
95 String rewritePathToContext(@NotNull Resource resource, @NotNull Resource contextResource);
96
97 /**
98 * Checks if the given URL is externalized.
99 *
100 * <p>
101 * An URL is treated as externalized if:
102 * </p>
103 *
104 * <ul>
105 * <li>It starts with a protocol and a colon (e.g. http:, tel:, mailto:, javascript:)</li>
106 * <li>It starts with // or #</li>
107 * </ul>
108 * @param url URL
109 * @return true if the URL is externalized.
110 */
111 boolean isExternalized(@NotNull String url);
112
113 /**
114 * Applies auto-detection of Site URL (author or publish instance) for given Site URL that is
115 * configured in {@link SiteConfig}.
116 *
117 * <p>
118 * If this Site URL contains an <code><auto></code> placeholder the Site URL detection is enabled
119 * and the Site URL is replaced with the current hostname (if possible). Otherwise the remaining part of the
120 * Site URL string is returned as fallback.
121 * </p>
122 *
123 * <p>
124 * Site URL auto-detection does only work in context of a request - outside request context the placeholders
125 * is removed and the remaining string returned as fallback.
126 * </p>
127 *
128 * @param siteUrl Site URL (author or publish) {@link SiteConfig}.
129 * @return Automatic detected Site URL or fallback
130 */
131 String applySiteUrlAutoDetection(@Nullable String siteUrl);
132
133 }