GitHub-Spring
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

SPR-8803 Add UriComponentsBuilder methods to replace path/query.

pull/7/head
Rossen Stoyanchev 15 years ago
parent
8889284517
commit
d3f4c69f00
6 changed files with 338 additions and 179 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      build-spring-framework/resources/changelog.txt
  2. 396
      org.springframework.web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java
  3. 46
      org.springframework.web/src/test/java/org/springframework/web/util/UriComponentsBuilderTests.java
  4. 4
      spring-framework-reference/src/mvc.xml
  5. 20
      spring-framework-reference/src/new-in-3.1.xml
  6. 50
      spring-framework-reference/src/remoting.xml

1
build-spring-framework/resources/changelog.txt
Unescape View File

@ -21,6 +21,7 @@ Changes in version 3.1 RC2 (2011-11-15) @@ -21,6 +21,7 @@ Changes in version 3.1 RC2 (2011-11-15)
* The Form input tag allows type values other than "text" such as HTML5-specific types.
* The Form hidden tag supports "disabled" attribute
* Add ignoreDefaultModelOnRedirect attribute to <mvc:annotation-driven/>
* Add methods to UriComponentsBuilder for replacing the path or the query.
Changes in version 3.1 RC1 (2011-10-11)
---------------------------------------

396
org.springframework.web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java
Unescape View File

@ -44,6 +44,7 @@ import org.springframework.util.StringUtils; @@ -44,6 +44,7 @@ import org.springframework.util.StringUtils;
* </ol>
*
* @author Arjen Poutsma
* @author Rossen Stoyanchev
* @see #newInstance()
* @see #fromPath(String)
* @see #fromUri(URI)
@ -78,20 +79,20 @@ public class UriComponentsBuilder { @@ -78,20 +79,20 @@ public class UriComponentsBuilder {
"^" + HTTP_PATTERN + "(//(" + USERINFO_PATTERN + "@)?" + HOST_PATTERN + "(:" + PORT_PATTERN + ")?" + ")?" +
PATH_PATTERN + "(\\?" + LAST_PATTERN + ")?");
private String scheme;
private String scheme;
private String userInfo;
private String userInfo;
private String host;
private String host;
private int port = -1;
private int port = -1;
private PathComponentBuilder pathBuilder = NULL_PATH_COMPONENT_BUILDER;
private final MultiValueMap<String, String> queryParams = new LinkedMultiValueMap<String, String>();
private String fragment;
private String fragment;
/**
* Default constructor. Protected to prevent direct instantiation.
@ -101,42 +102,42 @@ public class UriComponentsBuilder { @@ -101,42 +102,42 @@ public class UriComponentsBuilder {
* @see #fromUri(URI)
*/
protected UriComponentsBuilder() {
}
}
// Factory methods
/**
* Returns a new, empty builder.
*
* @return the new {@code UriComponentsBuilder}
*/
public static UriComponentsBuilder newInstance() {
return new UriComponentsBuilder();
}
/**
* Returns a builder that is initialized with the given path.
*
* @param path the path to initialize with
* @return the new {@code UriComponentsBuilder}
*/
public static UriComponentsBuilder fromPath(String path) {
UriComponentsBuilder builder = new UriComponentsBuilder();
builder.path(path);
return builder;
}
/**
* Returns a builder that is initialized with the given {@code URI}.
*
* @param uri the URI to initialize with
* @return the new {@code UriComponentsBuilder}
*/
public static UriComponentsBuilder fromUri(URI uri) {
UriComponentsBuilder builder = new UriComponentsBuilder();
builder.uri(uri);
return builder;
}
/**
* Returns a new, empty builder.
*
* @return the new {@code UriComponentsBuilder}
*/
public static UriComponentsBuilder newInstance() {
return new UriComponentsBuilder();
}
/**
* Returns a builder that is initialized with the given path.
*
* @param path the path to initialize with
* @return the new {@code UriComponentsBuilder}
*/
public static UriComponentsBuilder fromPath(String path) {
UriComponentsBuilder builder = new UriComponentsBuilder();
builder.path(path);
return builder;
}
/**
* Returns a builder that is initialized with the given {@code URI}.
*
* @param uri the URI to initialize with
* @return the new {@code UriComponentsBuilder}
*/
public static UriComponentsBuilder fromUri(URI uri) {
UriComponentsBuilder builder = new UriComponentsBuilder();
builder.uri(uri);
return builder;
}
/**
* Returns a builder that is initialized with the given URI string.
@ -201,132 +202,145 @@ public class UriComponentsBuilder { @@ -201,132 +202,145 @@ public class UriComponentsBuilder {
// build methods
/**
* Builds a {@code UriComponents} instance from the various components contained in this builder.
*
* @return the URI components
*/
public UriComponents build() {
/**
* Builds a {@code UriComponents} instance from the various components contained in this builder.
*
* @return the URI components
*/
public UriComponents build() {
return build(false);
}
/**
* Builds a {@code UriComponents} instance from the various components contained in this builder.
*
/**
* Builds a {@code UriComponents} instance from the various components contained in this builder.
*
* @param encoded whether all the components set in this builder are encoded ({@code true}) or not ({@code false}).
* @return the URI components
*/
public UriComponents build(boolean encoded) {
*/
public UriComponents build(boolean encoded) {
return new UriComponents(scheme, userInfo, host, port, pathBuilder.build(), queryParams, fragment, encoded, true);
}
}
// URI components methods
/**
* Initializes all components of this URI builder with the components of the given URI.
*
* @param uri the URI
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder uri(URI uri) {
Assert.notNull(uri, "'uri' must not be null");
Assert.isTrue(!uri.isOpaque(), "Opaque URI [" + uri + "] not supported");
this.scheme = uri.getScheme();
if (uri.getUserInfo() != null) {
this.userInfo = uri.getUserInfo();
}
if (uri.getHost() != null) {
this.host = uri.getHost();
}
if (uri.getPort() != -1) {
this.port = uri.getPort();
}
if (StringUtils.hasLength(uri.getPath())) {
/**
* Initializes all components of this URI builder with the components of the given URI.
*
* @param uri the URI
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder uri(URI uri) {
Assert.notNull(uri, "'uri' must not be null");
Assert.isTrue(!uri.isOpaque(), "Opaque URI [" + uri + "] not supported");
this.scheme = uri.getScheme();
if (uri.getUserInfo() != null) {
this.userInfo = uri.getUserInfo();
}
if (uri.getHost() != null) {
this.host = uri.getHost();
}
if (uri.getPort() != -1) {
this.port = uri.getPort();
}
if (StringUtils.hasLength(uri.getPath())) {
this.pathBuilder = new FullPathComponentBuilder(uri.getPath());
}
if (StringUtils.hasLength(uri.getQuery())) {
}
if (StringUtils.hasLength(uri.getQuery())) {
this.queryParams.clear();
query(uri.getQuery());
}
if (uri.getFragment() != null) {
this.fragment = uri.getFragment();
}
return this;
}
/**
* Sets the URI scheme. The given scheme may contain URI template variables, and may also be {@code null} to clear the
* scheme of this builder.
*
* @param scheme the URI scheme
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder scheme(String scheme) {
this.scheme = scheme;
return this;
}
/**
* Sets the URI user info. The given user info may contain URI template variables, and may also be {@code null} to
* clear the user info of this builder.
*
* @param userInfo the URI user info
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder userInfo(String userInfo) {
this.userInfo = userInfo;
return this;
}
/**
* Sets the URI host. The given host may contain URI template variables, and may also be {@code null} to clear the host
* of this builder.
*
* @param host the URI host
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder host(String host) {
this.host = host;
return this;
}
/**
* Sets the URI port. Passing {@code -1} will clear the port of this builder.
*
* @param port the URI port
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder port(int port) {
Assert.isTrue(port >= -1, "'port' must not be < -1");
this.port = port;
return this;
}
}
if (uri.getFragment() != null) {
this.fragment = uri.getFragment();
}
return this;
}
/**
* Sets the URI scheme. The given scheme may contain URI template variables, and may also be {@code null} to clear the
* scheme of this builder.
*
* @param scheme the URI scheme
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder scheme(String scheme) {
this.scheme = scheme;
return this;
}
/**
* Sets the URI user info. The given user info may contain URI template variables, and may also be {@code null} to
* clear the user info of this builder.
*
* @param userInfo the URI user info
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder userInfo(String userInfo) {
this.userInfo = userInfo;
return this;
}
/**
* Sets the URI host. The given host may contain URI template variables, and may also be {@code null} to clear the host
* of this builder.
*
* @param host the URI host
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder host(String host) {
this.host = host;
return this;
}
/**
* Sets the URI port. Passing {@code -1} will clear the port of this builder.
*
* @param port the URI port
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder port(int port) {
Assert.isTrue(port >= -1, "'port' must not be < -1");
this.port = port;
return this;
}
/**
* Appends the given path to the existing path of this builder. The given path may contain URI template variables.
*
* @param path the URI path
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder path(String path) {
* Appends the given path to the existing path of this builder. The given path may contain URI template variables.
*
* @param path the URI path
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder path(String path) {
if (path != null) {
this.pathBuilder = this.pathBuilder.appendPath(path);
} else {
}
else {
this.pathBuilder = NULL_PATH_COMPONENT_BUILDER;
}
return this;
}
/**
* Appends the given path segments to the existing path of this builder. Each given path segments may contain URI
* template variables.
*
* @param pathSegments the URI path segments
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder pathSegment(String... pathSegments) throws IllegalArgumentException {
}
/**
* Sets the path of this builder overriding all existing path and path segment values.
*
* @param path the URI path; a {@code null} value results in an empty path.
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder replacePath(String path) {
this.pathBuilder = NULL_PATH_COMPONENT_BUILDER;
path(path);
return this;
}
/**
* Appends the given path segments to the existing path of this builder. Each given path segments may contain URI
* template variables.
*
* @param pathSegments the URI path segments
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder pathSegment(String... pathSegments) throws IllegalArgumentException {
Assert.notNull(pathSegments, "'segments' must not be null");
this.pathBuilder = this.pathBuilder.appendPathSegments(pathSegments);
return this;
@ -335,7 +349,7 @@ public class UriComponentsBuilder { @@ -335,7 +349,7 @@ public class UriComponentsBuilder {
/**
* Appends the given query to the existing query of this builder. The given query may contain URI template variables.
*
* @param query the URI path
* @param query the query string
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder query(String query) {
@ -348,52 +362,78 @@ public class UriComponentsBuilder { @@ -348,52 +362,78 @@ public class UriComponentsBuilder {
}
}
else {
queryParams.clear();
this.queryParams.clear();
}
return this;
}
/**
* Sets the query of this builder overriding all existing query parameters.
*
* @param query the query string; a {@code null} value removes all query parameters.
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder replaceQuery(String query) {
this.queryParams.clear();
query(query);
return this;
}
/**
* Appends the given query parameter to the existing query parameters. The given name or any of the values may contain
* URI template variables. If no values are given, the resulting URI will contain the query parameter name only (i.e.
* {@code ?foo} instead of {@code ?foo=bar}.
*
* @param name the query parameter name
* @param values the query parameter values
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder queryParam(String name, Object... values) {
/**
* Appends the given query parameter to the existing query parameters. The given name or any of the values may contain
* URI template variables. If no values are given, the resulting URI will contain the query parameter name only (i.e.
* {@code ?foo} instead of {@code ?foo=bar}.
*
* @param name the query parameter name
* @param values the query parameter values
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder queryParam(String name, Object... values) {
Assert.notNull(name, "'name' must not be null");
if (!ObjectUtils.isEmpty(values)) {
for (Object value : values) {
String valueAsString = value != null ? value.toString() : null;
queryParams.add(name, valueAsString);
this.queryParams.add(name, valueAsString);
}
}
else {
queryParams.add(name, null);
this.queryParams.add(name, null);
}
return this;
}
/**
* Sets the URI fragment. The given fragment may contain URI template variables, and may also be {@code null} to clear
* the fragment of this builder.
*
* @param fragment the URI fragment
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder fragment(String fragment) {
if (fragment != null) {
Assert.hasLength(fragment, "'fragment' must not be empty");
this.fragment = fragment;
}
else {
this.fragment = null;
}
return this;
}
/**
* Sets the query parameter values overriding all existing query values for the same parameter.
* If no values are given, the resulting URI will contain the query parameter name only.
*
* @param name the query parameter name
* @param values the query parameter values
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder replaceQueryParam(String name, Object... values) {
Assert.notNull(name, "'name' must not be null");
this.queryParams.remove(name);
queryParam(name, values);
return this;
}
/**
* Sets the URI fragment. The given fragment may contain URI template variables, and may also be {@code null} to clear
* the fragment of this builder.
*
* @param fragment the URI fragment
* @return this UriComponentsBuilder
*/
public UriComponentsBuilder fragment(String fragment) {
if (fragment != null) {
Assert.hasLength(fragment, "'fragment' must not be empty");
this.fragment = fragment;
}
else {
this.fragment = null;
}
return this;
}
/**
* Represents a builder for {@link org.springframework.web.util.UriComponents.PathComponent}
@ -403,7 +443,7 @@ public class UriComponentsBuilder { @@ -403,7 +443,7 @@ public class UriComponentsBuilder {
UriComponents.PathComponent build();
PathComponentBuilder appendPath(String path);
PathComponentBuilder appendPathSegments(String... pathSegments);
}

46
org.springframework.web/src/test/java/org/springframework/web/util/UriComponentsBuilderTests.java
Unescape View File

@ -174,6 +174,36 @@ public class UriComponentsBuilderTests { @@ -174,6 +174,36 @@ public class UriComponentsBuilderTests {
assertEquals(Arrays.asList("foo"), result.getPathSegments());
}
@Test
public void replacePath() {
UriComponentsBuilder builder = UriComponentsBuilder.fromUriString("http://www.ietf.org/rfc/rfc2396.txt");
builder.replacePath("/rfc/rfc3986.txt");
UriComponents result = builder.build();
assertEquals("http://www.ietf.org/rfc/rfc3986.txt", result.toUriString());
builder = UriComponentsBuilder.fromUriString("http://www.ietf.org/rfc/rfc2396.txt");
builder.replacePath(null);
result = builder.build();
assertEquals("http://www.ietf.org", result.toUriString());
}
@Test
public void replaceQuery() {
UriComponentsBuilder builder = UriComponentsBuilder.fromUriString("http://example.com/foo?foo=bar&baz=qux");
builder.replaceQuery("baz=42");
UriComponents result = builder.build();
assertEquals("http://example.com/foo?baz=42", result.toUriString());
builder = UriComponentsBuilder.fromUriString("http://example.com/foo?foo=bar&baz=qux");
builder.replaceQuery(null);
result = builder.build();
assertEquals("http://example.com/foo", result.toUriString());
}
@Test
public void queryParams() throws URISyntaxException {
UriComponentsBuilder builder = UriComponentsBuilder.newInstance();
@ -197,4 +227,20 @@ public class UriComponentsBuilderTests { @@ -197,4 +227,20 @@ public class UriComponentsBuilderTests {
assertEquals(expectedQueryParams, result.getQueryParams());
}
@Test
public void replaceQueryParam() {
UriComponentsBuilder builder = UriComponentsBuilder.newInstance().queryParam("baz", "qux", 42);
builder.replaceQueryParam("baz", "xuq", 24);
UriComponents result = builder.build();
assertEquals("baz=xuq&baz=24", result.getQuery());
builder = UriComponentsBuilder.newInstance().queryParam("baz", "qux", 42);
builder.replaceQueryParam("baz");
result = builder.build();
assertEquals("baz", result.getQuery());
}
}

4
spring-framework-reference/src/mvc.xml
Unescape View File

@ -1792,7 +1792,9 @@ public class EditPetForm { @@ -1792,7 +1792,9 @@ public class EditPetForm {
so no attributes should be passed on to
<classname>RedirectView</classname>. Both the MVC namespace and the
MVC Java config (via <interfacename>@EnableWebMvc</interfacename>)
automatically set this flag to <literal>true</literal>.</para>
keep this flag set to <literal>false</literal> in order to maintain
backwards compatibility. However, for new applications we recommend
setting it to <literal>true</literal></para>
<para>The <interfacename>RedirectAttributes</interfacename> interface
can also be used to add flash attributes. Unlike other redirect

20
spring-framework-reference/src/new-in-3.1.xml
Unescape View File

@ -467,5 +467,25 @@ @@ -467,5 +467,25 @@
linkend="mvc-multipart-forms-non-browsers" /> and <xref
linkend="mvc-multipart" />.</para>
</section>
<section>
<title><classname>UriComponentsBuilder</classname> and <classname>UriComponents</classname></title>
<para>A new <classname>UriComponents</classname> class has been added,
which is an immutable container of URI components providing
access to all contained URI components.
A nenw <classname>UriComponentsBuilder</classname> class is also
provided to help create <classname>UriComponents</classname> instances.
Together the two classes give fine-grained control over all
aspects of preparing a URI including construction, expansion
from URI template variables, and encoding.</para>
<para>In most cases the new classes can be used as a more flexible
alternative to the existing <classname>UriTemplate</classname>
especially since <classname>UriTemplate</classname> relies on those
same classes internally.
</para>
</section>
</section>
</chapter>

50
spring-framework-reference/src/remoting.xml
Unescape View File

@ -1434,6 +1434,56 @@ URI location = template.postForLocation(uri, booking, "1"); @@ -1434,6 +1434,56 @@ URI location = template.postForLocation(uri, booking, "1");
information on using the execute method and the meaning of its other
method arguments.</para>
<section>
<title>Working with the URI</title>
<para>For each of the main HTTP methods, the <classname>RestTemplate</classname>
provides variants that either take a String URI or <classname>java.net.URI</classname>
as the first argument.
</para>
<para>The String URI variants accept template arguments as a
String variable length argument or as a <classname>Map&lt;String,String&gt;</classname>.
They also assume the URL String is not encoded and needs to be encoded.
For example the following:
</para>
<programlisting language="java">restTemplate.getForObject("http://example.com/hotel list", String.class);</programlisting>
<para>will perform a GET on <filename>http://example.com/hotel%20list</filename>.
That means if the input URL String is already encoded, it will be encoded twice --
i.e. <filename>http://example.com/hotel%20list</filename> will become
<filename>http://example.com/hotel%2520list</filename>.
If this is not the intended effect, use the
<classname>java.net.URI</classname> method variant, which assumes
the URL is already encoded is also generally useful if you want
to reuse a single (fully expanded) <classname>URI</classname>
multiple times.</para>
<para>The <classname>UriComponentsBuilder</classname> class can be used
to build and encode the <classname>URI</classname> including support
for URI templates. For example you can start with a URL String:
</para>
<programlisting language="java">UriComponents uriComponents =
UriComponentsBuilder.fromUriString("http://example.com/hotels/{hotel}/bookings/{booking}").build()
.expand("42", "21")
.encode();
URI uri = uriComponents.toUri();</programlisting>
<para>Or specify each URI component indiviudally:</para>
<programlisting language="java">UriComponents uriComponents =
UriComponentsBuilder.newInstance()
.scheme("http").host("example.com").path("/hotels/{hotel}/bookings/{booking}").build()
.expand("42", "21")
.encode();
URI uri = uriComponents.toUri();</programlisting>
</section>
<section>
<title>Dealing with request and response headers</title>

Write Preview
Loading…
Cancel
Save