kwin commented on a change in pull request #23: URL: https://github.com/apache/sling-org-apache-sling-api/pull/23#discussion_r492506145
########## File path: src/main/java/org/apache/sling/api/uri/SlingUri.java ########## @@ -0,0 +1,233 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.api.uri; + +import java.net.URI; +import java.util.Map; +import java.util.function.Consumer; + +import org.apache.sling.api.request.RequestPathInfo; +import org.apache.sling.api.resource.Resource; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; +import org.osgi.annotation.versioning.ProviderType; + +/** + * Represents an immutable URI in the same way as java.net.URI but is extended with Sling-specific URI parts (e.g. selectors). A SlingUri + * usually points to a resource but alternatively, can also contain an opaque URI like {@code mailto:} or {@code javascript:}. Use + * {@link SlingUri#adjust(Consumer)} or {@link SlingUriBuilder} to create new or modified Sling URIs. + * + * @since 1.0.0 (Sling API Bundle 2.23.0) + */ +@ProviderType +public interface SlingUri extends RequestPathInfo { + + /** + * Returns the @{link URI}. + * + * @return the URI + */ + @NotNull + URI toUri(); + + /** + * Returns the URI as String. + * + * @return the URI string + */ + @NotNull + String toString(); + + /** + * Returns the scheme. + * + * @return the scheme or null if not set + */ + @Nullable + String getScheme(); + + /** + * Returns the user info. + * + * @return the user info of the SlingUri or null if not set + */ + @Nullable + String getUserInfo(); + + /** + * Returns the host. + * + * @return returns the host of the SlingUri or null if not set + */ + @Nullable + String getHost(); + + /** + * Returns the port. + * + * @return returns the port of the SlingUri or -1 if not set + */ + int getPort(); + + /** + * Returns the resource path. + * + * @return returns the resource path or null if the URI does not contain a path. + */ + @Override + @Nullable + String getResourcePath(); + + /** + * Returns the selector string. + * + * @return returns the selector string or null if the URI does not contain selector(s) + */ + @Override + @Nullable + String getSelectorString(); + + /** + * Returns the selectors array. + * + * @return the selectors array (empty if the URI does not contain selector(s)) + */ + @Override + String[] getSelectors(); Review comment: null annotation missing ########## File path: src/main/java/org/apache/sling/api/uri/SlingUri.java ########## @@ -0,0 +1,233 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.api.uri; + +import java.net.URI; +import java.util.Map; +import java.util.function.Consumer; + +import org.apache.sling.api.request.RequestPathInfo; +import org.apache.sling.api.resource.Resource; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; +import org.osgi.annotation.versioning.ProviderType; + +/** + * Represents an immutable URI in the same way as java.net.URI but is extended with Sling-specific URI parts (e.g. selectors). A SlingUri + * usually points to a resource but alternatively, can also contain an opaque URI like {@code mailto:} or {@code javascript:}. Use + * {@link SlingUri#adjust(Consumer)} or {@link SlingUriBuilder} to create new or modified Sling URIs. + * + * @since 1.0.0 (Sling API Bundle 2.23.0) + */ +@ProviderType +public interface SlingUri extends RequestPathInfo { + + /** + * Returns the @{link URI}. + * + * @return the URI + */ + @NotNull + URI toUri(); + + /** + * Returns the URI as String. + * + * @return the URI string + */ + @NotNull + String toString(); + + /** + * Returns the scheme. + * + * @return the scheme or null if not set + */ + @Nullable + String getScheme(); + + /** + * Returns the user info. + * + * @return the user info of the SlingUri or null if not set + */ + @Nullable + String getUserInfo(); + + /** + * Returns the host. + * + * @return returns the host of the SlingUri or null if not set + */ + @Nullable + String getHost(); + + /** + * Returns the port. + * + * @return returns the port of the SlingUri or -1 if not set + */ + int getPort(); + + /** + * Returns the resource path. + * + * @return returns the resource path or null if the URI does not contain a path. + */ + @Override + @Nullable + String getResourcePath(); + + /** + * Returns the selector string. + * + * @return returns the selector string or null if the URI does not contain selector(s) + */ + @Override + @Nullable + String getSelectorString(); + + /** + * Returns the selectors array. + * + * @return the selectors array (empty if the URI does not contain selector(s)) + */ + @Override + String[] getSelectors(); + + /** + * Returns the extension. + * + * @return the extension or null if the URI does not contain an extension + */ + @Override + @Nullable + String getExtension(); + + /** + * Returns the path parameters. + * + * @return the path parameters or an empty Map if the URI does not contain any + */ + Map<String, String> getPathParameters(); + + /** + * Returns the suffix part of the URI + * + * @return the suffix string or null if the URI does not contain a suffix + */ + @Override + @Nullable + String getSuffix(); + + /** + * Returns the joint path of resource path, selectors, extension and suffix. + * + * @return the path or null if no path is set + */ + @Nullable + String getPath(); + + /** + * Returns the query. + * + * @return the query part of the URI or null if the URI does not contain a query + */ + @Nullable + String getQuery(); + + /** + * Returns the fragment. + * + * @return the fragment or null if the URI does not contain a fragment + */ + @Nullable + String getFragment(); + + /** + * Returns the scheme-specific part of the URI, compare with Javadoc of class + * <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/URI.html";>URI</a>. Review comment: as Sling API is compliant with Java 8, please link Java 8 javadocs. You can use the link tag to let javadoc generate the link from the FQCN automatically. ########## File path: src/main/java/org/apache/sling/api/uri/SlingUriBuilder.java ########## @@ -0,0 +1,1024 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.api.uri; + +import java.net.URI; +import java.net.URISyntaxException; +import java.util.Arrays; +import java.util.Collections; +import java.util.Iterator; +import java.util.LinkedHashMap; +import java.util.LinkedList; +import java.util.List; +import java.util.Map; +import java.util.NoSuchElementException; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +import org.apache.sling.api.SlingHttpServletRequest; +import org.apache.sling.api.request.RequestPathInfo; +import org.apache.sling.api.resource.Resource; +import org.apache.sling.api.resource.ResourceResolver; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; +import org.osgi.annotation.versioning.ProviderType; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * Builder for SlingUris. + * <p> + * Example: + * + * <pre> + * SlingUri testUri = SlingUriBuilder.create() + * .setResourcePath("/test/to/path") + * .setSelectors(new String[] { "sel1", "sel2" }) + * .setExtension("html") + * .setSuffix("/suffix/path") + * .setQuery("par1=val1&par2=val2") + * .build(); + * </pre> + * <p> + * + * @since 1.0.0 (Sling API Bundle 2.23.0) + */ +@ProviderType +public class SlingUriBuilder { + private static final Logger LOG = LoggerFactory.getLogger(SlingUriBuilder.class); + + private static final String HTTPS_SCHEME = "https"; + private static final int HTTPS_DEFAULT_PORT = 443; + private static final String HTTP_SCHEME = "http"; + private static final int HTTP_DEFAULT_PORT = 80; + + static final char CHAR_HASH = '#'; + static final char CHAR_QM = '?'; + static final char CHAR_AT = '@'; + static final char CHAR_SEMICOLON = ';'; + static final char CHAR_EQUALS = '='; + static final char CHAR_SINGLEQUOTE = '\''; + static final String CHAR_COLON = ":"; + static final String CHAR_DOT = "."; + static final String CHAR_SLASH = "/"; + static final String SELECTOR_DOT_REGEX = "\\.(?!\\.?/)"; // (?!\\.?/) to avoid matching ./ and ../ + static final String PATH_PARAMETERS_REGEX = ";([a-zA-z0-9]+)=(?:\\'([^']*)\\'|([^/]+))"; + + /** + * Creates a builder without any URI parameters set. + * + * @return a SlingUriBuilder + */ + public static SlingUriBuilder create() { Review comment: Null annotations missing on all methods ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
