Exposes configuration properties that customize the creation of all URIs - * built through this factory instance including a base URI, default URI - * variables, and an encoding mode. + *
Uses {@link UriComponentsBuilder} for URI building. * * @author Rossen Stoyanchev * @since 5.0 + * @see UriComponentsBuilder */ public class DefaultUriBuilderFactory implements UriBuilderFactory { @@ -55,26 +54,28 @@ public class DefaultUriBuilderFactory implements UriBuilderFactory { /** * Default constructor without a base URI. + *
The target address must be specified on each UriBuilder. */ public DefaultUriBuilderFactory() { this(UriComponentsBuilder.newInstance()); } /** - * Constructor with a String "base URI". - *
The String given here is used to create a single "base" - * {@code UriComponentsBuilder}. Each time a new URI is prepared via - * {@link #uriString(String)} a new {@code UriComponentsBuilder} is created and - * merged with a clone of the "base" {@code UriComponentsBuilder}. - *
Note that the base URI may contain any or all components of a URI and - * those will apply to every URI. + * Constructor with a base URI. + *
The given URI template is parsed via
+ * {@link UriComponentsBuilder#fromUriString} and then applied as a base URI
+ * to every UriBuilder via {@link UriComponentsBuilder#uriComponents} unless
+ * the UriBuilder itself was created with a URI template that already has a
+ * target address.
+ * @param baseUriTemplate the URI template to use a base URL
*/
- public DefaultUriBuilderFactory(String baseUri) {
- this(UriComponentsBuilder.fromUriString(baseUri));
+ public DefaultUriBuilderFactory(String baseUriTemplate) {
+ this(UriComponentsBuilder.fromUriString(baseUriTemplate));
}
/**
- * Alternate constructor with a {@code UriComponentsBuilder} as the base URI.
+ * Variant of {@link #DefaultUriBuilderFactory(String)} with a
+ * {@code UriComponentsBuilder}.
*/
public DefaultUriBuilderFactory(UriComponentsBuilder baseUri) {
Assert.notNull(baseUri, "'baseUri' is required.");
@@ -83,10 +84,9 @@ public class DefaultUriBuilderFactory implements UriBuilderFactory {
/**
- * Configure default URI variable values to use when expanding a URI with a
- * Map of values. The map supplied when expanding a given URI can override
- * default values.
- * @param defaultUriVariables the default URI variables
+ * Provide default URI variable values to use when expanding URI templates
+ * with a Map of variables.
+ * @param defaultUriVariables default URI variable values
*/
public void setDefaultUriVariables(@Nullable Map A single {@link UriBuilderFactory} may be created once, configured with
- * common properties such as a base URI, and then used to create many URIs.
- *
- * Extends {@link UriTemplateHandler} which has a similar purpose but only
- * provides shortcuts for expanding URI templates, not builder style methods.
+ * Factory to create {@link UriBuilder} instances pre-configured in a specific
+ * way such as sharing a common base URI across all builders.
*
* @author Rossen Stoyanchev
* @since 5.0
@@ -30,17 +25,16 @@ package org.springframework.web.util;
public interface UriBuilderFactory extends UriTemplateHandler {
/**
- * Return a builder initialized with the given URI string.
- * Concrete implementations may apply further initializations such as
- * combining with a pre-configured base URI.
- * @param uriTemplate the URI template to initialize the builder with
- * @return the UriBuilder
+ * Create a builder from the given URI template string.
+ * Implementations may further combine the URI template with a base URI.
+ * @param uriTemplate the URI template to use
+ * @return the builder instance
*/
UriBuilder uriString(String uriTemplate);
/**
- * Return a builder to prepare a new URI.
- * @return the UriBuilder
+ * Create a builder with default settings.
+ * @return the builder instance
*/
UriBuilder builder();
diff --git a/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java b/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java
index 7d4b6d2f6e..6ab0892cd8 100644
--- a/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java
+++ b/spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java
@@ -444,9 +444,12 @@ public class UriComponentsBuilder implements UriBuilder, Cloneable {
}
/**
- * Initialize components of this {@code UriComponentsBuilder} from the
- * components of the given {@link UriComponents}.
- * @param uriComponents the UriComponents instance
+ * Set or append individual URI components of this builder from the values
+ * of the given {@link UriComponents} instance.
+ * For the semantics of each component (i.e. set vs append) check the
+ * builder methods on this class. For example {@link #host(String)} sets
+ * while {@link #path(String)} appends.
+ * @param uriComponents the UriComponents to copy from
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder uriComponents(UriComponents uriComponents) {