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 java.util.Set;
23
24 import org.apache.sling.api.resource.Resource;
25 import org.jetbrains.annotations.NotNull;
26 import org.jetbrains.annotations.Nullable;
27 import org.osgi.annotation.versioning.ProviderType;
28
29 import com.day.cq.wcm.api.Page;
30
31 /**
32 * Define URL handling requests using builder pattern.
33 */
34 @ProviderType
35 public interface UrlBuilder {
36
37 /**
38 * Set selectors
39 * @param selectors Selector string
40 * @return URL builder
41 */
42 @NotNull
43 UrlBuilder selectors(@Nullable String selectors);
44
45 /**
46 * Set file extension
47 * @param extension file extension
48 * @return URL builder
49 */
50 @NotNull
51 UrlBuilder extension(@Nullable String extension);
52
53 /**
54 * Set suffix
55 * @param suffix Suffix string
56 * @return URL builder
57 */
58 @NotNull
59 UrlBuilder suffix(@Nullable String suffix);
60
61 /**
62 * Set query parameters string
63 * @param queryString Query parameters string (properly url-encoded)
64 * @return URL builder
65 */
66 @NotNull
67 UrlBuilder queryString(@Nullable String queryString);
68
69 /**
70 * Set query parameters string
71 * @param queryString Query parameters string (properly url-encoded)
72 * @param inheritableParameterNames Names of query string parameters that should be inherited from the current request
73 * @return URL builder
74 */
75 @NotNull
76 UrlBuilder queryString(@Nullable String queryString, @NotNull Set<String> inheritableParameterNames);
77
78 /**
79 * Set fragment identifier
80 * @param fragment Fragment identifier
81 * @return URL builder
82 */
83 @NotNull
84 UrlBuilder fragment(@Nullable String fragment);
85
86 /**
87 * Set URL mode for externalizing the URL
88 * @param urlMode URL mode. If null, default URL mode is used.
89 * @return URL builder
90 */
91 @NotNull
92 UrlBuilder urlMode(@Nullable UrlMode urlMode);
93
94 /**
95 * Set Vanity mode for building the URL
96 * @param vanityMode Vanity Mode. Only used when building for a page
97 * @return URL builder
98 */
99 @NotNull
100 UrlBuilder vanityMode(@Nullable VanityMode vanityMode);
101
102 /**
103 * Disable the automatic addition of an additional selector {@link UrlHandler#SELECTOR_SUFFIX}
104 * in case a suffix is present for building the URL. Although recommended as best practice, this can
105 * be omitted if you are sure your URLs are always either include a suffix or never do, so there is no risk
106 * for file name clashes in dispatcher cache.
107 * @param disableSuffixSelector If set to true, no additional suffix selector is added
108 * @return URL builder
109 */
110 @NotNull
111 UrlBuilder disableSuffixSelector(boolean disableSuffixSelector);
112
113 /**
114 * Build URL
115 * @return URL
116 */
117 @Nullable
118 String build();
119
120 /**
121 * Build externalized URL that links to a content page.
122 * This may only be used if a page was given in the {@link UrlHandler#get(Page)} call.
123 * @return URL
124 */
125 @Nullable
126 String buildExternalLinkUrl();
127
128 /**
129 * Build externalized URL that links to a content page.
130 * @param targetPage Target page of internal link (e.g. for checking url configuration and secure mode)
131 * @return URL
132 */
133 @Nullable
134 String buildExternalLinkUrl(@Nullable Page targetPage);
135
136 /**
137 * Build externalized URL that links to a resource (e.g. image, CSS or JavaScript reference).
138 * @return URL
139 */
140 @Nullable
141 String buildExternalResourceUrl();
142
143 /**
144 * Build externalized URL that links to a resource (e.g. image, CSS or JavaScript reference).
145 * @param targetResource Target resource of resource link (e.g. for checking url configuration)
146 * @return URL
147 */
148 @Nullable
149 String buildExternalResourceUrl(@Nullable Resource targetResource);
150
151 }