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 * <p>
32 * The interface is implemented by a Sling Model. You can adapt from
33 * {@link org.apache.sling.api.SlingHttpServletRequest} or {@link org.apache.sling.api.resource.Resource} to get a
34 * context-specific handler instance.
35 * </p>
36 */
37 @ProviderType
38 public interface UrlHandler {
39
40 /**
41 * Selector that is always added if a Sling-URL contains a suffix (to avoid files and directories with same name in
42 * dispatcher cache)
43 */
44 @NotNull
45 String SELECTOR_SUFFIX = "suffix";
46
47 /**
48 * Builds and optionally externalizes an URL using a builder pattern.
49 * @param path Path to start URL building with
50 * @return URL builder which allows to chain further optional parameters before building the URL string.
51 */
52 @NotNull
53 UrlBuilder get(@NotNull String path);
54
55 /**
56 * Builds and optionally externalizes an URL using a builder pattern.
57 * @param resource Resource, URL building is started with its path
58 * @return URL builder which allows to chain further optional parameters before building the URL string.
59 */
60 @NotNull
61 UrlBuilder get(@NotNull Resource resource);
62
63 /**
64 * Builds and optionally externalizes an URL using a builder pattern.
65 * @param page Page Page, URL building is started with its path
66 * @return URL builder which allows to chain further optional parameters before building the URL string.
67 */
68 @NotNull
69 UrlBuilder get(@NotNull Page page);
70
71 /**
72 * Rewrites given path to current site or context.
73 * The site root path is replaced with the one from current site
74 * This is useful if a link to an internal page points to a page outside the site (e.g. because the page containing
75 * the link was copied from the other site or inherited). When the AEM built-in rewrite logic was not applied the link
76 * would be invalid. This methods rewrites the link path to the current site to try to resolve it there.
77 * @param resource Resource to rewrite path from
78 * @return Rewritten path or null if resource invalid
79 */
80 @Nullable
81 String rewritePathToContext(@NotNull Resource resource);
82
83 /**
84 * Rewrites given path to given site or context.
85 * The site root path is replaced with the one from current site.
86 * This is useful if a link to an internal page points to a page outside the site (e.g. because the page containing
87 * the link was copied from the other site or inherited). When the AEM built-in rewrite logic was not applied the link
88 * would be invalid. This methods rewrites the link path to the current site to try to resolve it there.
89 * @param resource Resource to rewrite path from
90 * @param contextResource Context resource to which the path should be rewritten to
91 * @return Rewritten path or null if resource or context resource is invalid
92 */
93 @Nullable
94 String rewritePathToContext(@NotNull Resource resource, @NotNull Resource contextResource);
95
96 /**
97 * Checks if the given URL is externalized.
98 * <p>
99 * An URL is treated as externalized if:
100 * </p>
101 * <ul>
102 * <li>It starts with a protocol and a colon (e.g. http:, tel:, mailto:, javascript:)</li>
103 * <li>It starts with // or #</li>
104 * </ul>
105 * @param url URL
106 * @return true if the URL is externalized.
107 */
108 boolean isExternalized(@NotNull String url);
109
110 /**
111 * Applies auto-detection of Site URL (author or publish instance) for given Site URL that is
112 * configured in {@link SiteConfig}.
113 * <p>
114 * If this Site URL contains an <code><auto></code> placeholder the Site URL detection is enabled
115 * and the Site URL is replaced with the current hostname (if possible). Otherwise the remaining part of the
116 * Site URL string is returned as fallback.
117 * </p>
118 * <p>
119 * Site URL auto-detection does only work in context of a request - outside request context the placeholders
120 * is removed and the remaining string returned as fallback.
121 * </p>
122 * @param siteUrl Site URL (author or publish) {@link SiteConfig}.
123 * @return Automatic detected Site URL or fallback
124 */
125 String applySiteUrlAutoDetection(@Nullable String siteUrl);
126
127 }