Updated to support URIs following URI-based conneg preprocessing. UriBuilder#extension is now floating until build time rather than being tied to current final path segment at call time.
svn path=/trunk/; revision=351
diff --git a/src/jsr311-api/src/javax/ws/rs/core/UriBuilder.java b/src/jsr311-api/src/javax/ws/rs/core/UriBuilder.java
index f0408b5..6c63df8 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/UriBuilder.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/UriBuilder.java
@@ -320,18 +320,39 @@
public abstract UriBuilder path(Method... methods) throws IllegalArgumentException;
/**
- * Set the extension of the current final path segment to the supplied value
- * appending an initial "." if necessary. The extension is everything
- * following the first "." in the current final path segment of the URI
- * excluding any matrix parameters that might be present after the extension
- * @param extension the extension, a null value will unset an existing
- * extension including a trailing "." if necessary
+ * Set the extension that will be appended to the final path segment at
+ * build time. An initial "." will be appended if necessary. If the final
+ * path segment already contains an extension, it will be retained and the
+ * supplied extension will be appended to it as a new extension. E.g.:
+ *
+ * <ul>
+ * <li><code>UriBuilder.fromPath("foo").extension("bar").build()</code>
+ * returns "foo.bar".</li>
+ * <li><code>UriBuilder.fromPath("foo.baz").extension("bar").build()</code>
+ * returns "foo.baz.bar".</li>
+ * <li><code>UriBuilder.fromPath("foo").extension("bar").path(baz).build()</code>
+ * returns "foo/baz.bar".</li>
+ * </ul>
+ *
+ * <p>Note that the extension will be appended to the path component,
+ * matrix and query parameters will follow any appended extension.</p>
+ *
+ * @param extension the extension to append at build time, a null value
+ * will result in no extension being appended.
* @return the updated UriBuilder
- * @see UriInfo#getPathExtension
*/
public abstract UriBuilder extension(String extension);
/**
+ * Get the current value of the extension that will be appended to the
+ * final path segment at build time.
+ * @return the extension that will be appended to the final path segment at
+ * build time
+ * @see #extension(java.lang.String)
+ */
+ public abstract String getExtension();
+
+ /**
* Set the matrix parameters of the current final segment of the current URI path.
* This method will overwrite any existing matrix parameters on the current final
* segment of the current URI path. Note that the matrix parameters
diff --git a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
index e2c18c2..05d47f5 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
@@ -30,7 +30,16 @@
* <p>All methods except {@link #getBaseUri} and
* {@link #getBaseUriBuilder} throw <code>java.lang.IllegalStateException</code>
* if called outside the scope of a request (e.g. from a provider constructor).</p>
+ *
+ * <p>Note that the URIs obtained from the methods of this interface provide
+ * access to request URIs after URI-based content negotiation preprocessing. E.g.
+ * if the request URI is "foo.xml" and {@link ApplicationConfig#getMediaTypeMappings()}
+ * includes a mapping for "xml", then {@link #getPath()} will return "foo", not
+ * "foo.xml". The removed "xml" extension is available via {@link #getConnegExtension}.</p>
+ *
* @see Context
+ * @see ApplicationConfig#getLanguageMappings()
+ * @see ApplicationConfig#getMediaTypeMappings()
*/
public interface UriInfo {
@@ -94,29 +103,16 @@
public URI getRequestUri();
/**
- * Get the absolute request URI in the form of a UriBuilder.
+ * Get the absolute request URI in the form of a UriBuilder. The returned
+ * builder will have its extension initialized with
+ * <code>extension(getConnegExtension())</code>.
* @return a UriBuilder initialized with the absolute request URI
* @throws java.lang.IllegalStateException if called outside the scope of a request
+ * @see UriBuilder#extension(java.lang.String)
*/
public UriBuilder getRequestUriBuilder();
/**
- * Get the absolute platonic request URI in the form of a UriBuilder. The
- * platonic request URI is the request URI minus any extensions that were
- * removed during request pre-processing for the purposes of URI-based
- * content negotiation. E.g. if the request URI was:
- * <pre>http://example.com/resource.xml</pre>
- * <p>and an applications implementation of
- * {@link ApplicationConfig#getMediaTypeMappings} returned a map
- * that included "xml" as a key then the platonic request URI would be:</p>
- * <pre>http://example.com/resource</pre>
- *
- * @return a UriBuilder initialized with the absolute platonic request URI
- * @throws java.lang.IllegalStateException if called outside the scope of a request
- */
- public UriBuilder getPlatonicRequestUriBuilder();
-
- /**
* Get the absolute path of the request. This includes everything preceding
* the path (host, port etc) but excludes query parameters and fragment.
* This is a shortcut for
@@ -128,10 +124,12 @@
/**
* Get the absolute path of the request in the form of a UriBuilder.
- * This includes everything preceding
- * the path (host, port etc) but excludes query parameters and fragment.
+ * This includes everything preceding the path (host, port etc) but excludes
+ * query parameters and fragment. The returned builder will have its
+ * extension initialized with <code>extension(getConnegExtension())</code>.
* @return a UriBuilder initialized with the absolute path of the request
* @throws java.lang.IllegalStateException if called outside the scope of a request
+ * @see UriBuilder#extension(java.lang.String)
*/
public UriBuilder getAbsolutePathBuilder();
@@ -143,25 +141,25 @@
public URI getBaseUri();
/**
- * Get the base URI of the application in the form of a UriBuilder.
+ * Get the base URI of the application in the form of a UriBuilder. If
+ * called within the scope of a request, the builder will have its extension
+ * initialized with <code>extension(getConnegExtension())</code>.
* @return a UriBuilder initialized with the base URI of the application.
+ * @see UriBuilder#extension(java.lang.String)
*/
public UriBuilder getBaseUriBuilder();
/**
- * Get the request URI extension, this includes everything following the
- * first "." in the final path segment of the URI excluding any matrix
- * parameters that might be present after the extension). The returned
- * string includes any extensions removed during request pre-processing for
- * the purposes of URI-based content negotiation. E.g. if the request URI was:
- * <pre>http://example.com/resource.xml.en</pre>
- * <p>this method would return "xml.en" even if an applications
- * implementation of
- * {@link ApplicationConfig#getMediaTypeMappings} returned a map
- * that included "xml" as a key
- * @return the request URI extension or null if there isn't one
+ * Get the request URI extension that was removed during URI-based content
+ * negotiation preprocessing. The extension does not include the leading "."
+ * nor any matrix parameters that might be present after the extension.
+ * E.g. if the request URI is "foo.xml" and
+ * {@link ApplicationConfig#getMediaTypeMappings()} includes a mapping for
+ * "xml", then this method will return "xml".
+ * @return the URI extension that was removed during URI-based content
+ * negotiation preprocessing or null if nothing was removed
*/
- public String getPathExtension();
+ public String getConnegExtension();
/**
* Get the values of any embedded URI template parameters.
