001 /*
002 * The contents of this file are subject to the terms
003 * of the Common Development and Distribution License
004 * (the "License"). You may not use this file except
005 * in compliance with the License.
006 *
007 * You can obtain a copy of the license at
008 * http://www.opensource.org/licenses/cddl1.php
009 * See the License for the specific language governing
010 * permissions and limitations under the License.
011 */
012
013 /*
014 * UriInfo.java
015 *
016 * Created on April 13, 2007, 2:55 PM
017 *
018 */
019
020 package javax.ws.rs.core;
021
022 import java.net.URI;
023 import java.util.List;
024
025 /**
026 * An injectable interface that provides access to application and request
027 * URI information. Relative URIs are relative to the base URI of the
028 * application, see {@link #getBaseUri}.
029 *
030 * <p>All methods throw <code>java.lang.IllegalStateException</code>
031 * if called outside the scope of a request (e.g. from a provider constructor).</p>
032 *
033 * @see Context
034 */
035 public interface UriInfo {
036
037 /**
038 * Get the path of the current request relative to the base URI as
039 * a string. All sequences of escaped octets are decoded, equivalent to
040 * <code>getPath(true)</code>.
041 *
042 * @return the relative URI path
043 * @throws java.lang.IllegalStateException if called outside the scope of a request
044 */
045 public String getPath();
046
047 /**
048 * Get the path of the current request relative to the base URI as
049 * a string.
050 *
051 * @param decode controls whether sequences of escaped octets are decoded
052 * (true) or not (false).
053 * @return the relative URI path
054 * @throws java.lang.IllegalStateException if called outside the scope of a request
055 */
056 public String getPath(boolean decode);
057
058 /**
059 * Get the path of the current request relative to the base URI as a
060 * list of {@link PathSegment}. This method is useful when the
061 * path needs to be parsed, particularly when matrix parameters may be
062 * present in the path. All sequences of escaped octets in path segments
063 * and matrix parameter values are decoded,
064 * equivalent to <code>getPathSegments(true)</code>.
065 * @return an unmodifiable list of {@link PathSegment}. The matrix parameter
066 * map of each path segment is also unmodifiable.
067 * @throws java.lang.IllegalStateException if called outside the scope of a request
068 * @see PathSegment
069 * @see <a href="http://www.w3.org/DesignIssues/MatrixURIs.html">Matrix URIs</a>
070 */
071 public List<PathSegment> getPathSegments();
072
073 /**
074 * Get the path of the current request relative to the base URI as a
075 * list of {@link PathSegment}. This method is useful when the
076 * path needs to be parsed, particularly when matrix parameters may be
077 * present in the path.
078 * @param decode controls whether sequences of escaped octets in path segments
079 * and matrix parameter values are decoded (true) or not (false).
080 * @return an unmodifiable list of {@link PathSegment}. The matrix parameter
081 * map of each path segment is also unmodifiable.
082 * @throws java.lang.IllegalStateException if called outside the scope of a request
083 * @see PathSegment
084 * @see <a href="http://www.w3.org/DesignIssues/MatrixURIs.html">Matrix URIs</a>
085 */
086 public List<PathSegment> getPathSegments(boolean decode);
087
088 /**
089 * Get the absolute request URI including any query parameters.
090 * @return the absolute request URI
091 * @throws java.lang.IllegalStateException if called outside the scope of a request
092 */
093 public URI getRequestUri();
094
095 /**
096 * Get the absolute request URI in the form of a UriBuilder.
097 * @return a UriBuilder initialized with the absolute request URI
098 * @throws java.lang.IllegalStateException if called outside the scope of a request
099 */
100 public UriBuilder getRequestUriBuilder();
101
102 /**
103 * Get the absolute path of the request. This includes everything preceding
104 * the path (host, port etc) but excludes query parameters.
105 * This is a shortcut for
106 * <code>uriInfo.getBase().resolve(uriInfo.getPath()).</code>
107 * @return the absolute path of the request
108 * @throws java.lang.IllegalStateException if called outside the scope of a request
109 */
110 public URI getAbsolutePath();
111
112 /**
113 * Get the absolute path of the request in the form of a UriBuilder.
114 * This includes everything preceding the path (host, port etc) but excludes
115 * query parameters.
116 * @return a UriBuilder initialized with the absolute path of the request
117 * @throws java.lang.IllegalStateException if called outside the scope of a request
118 */
119 public UriBuilder getAbsolutePathBuilder();
120
121 /**
122 * Get the base URI of the application. URIs of root resource classes
123 * are all relative to this base URI.
124 * @return the base URI of the application
125 */
126 public URI getBaseUri();
127
128 /**
129 * Get the base URI of the application in the form of a UriBuilder.
130 * @return a UriBuilder initialized with the base URI of the application.
131 */
132 public UriBuilder getBaseUriBuilder();
133
134 /**
135 * Get the values of any embedded URI template parameters.
136 * All sequences of escaped octets are decoded,
137 * equivalent to <code>getPathParameters(true)</code>.
138 * @return an unmodifiable map of parameter names and values
139 * @throws java.lang.IllegalStateException if called outside the scope of a request
140 * @see javax.ws.rs.Path
141 * @see javax.ws.rs.PathParam
142 */
143 public MultivaluedMap<String, String> getPathParameters();
144
145 /**
146 * Get the values of any embedded URI template parameters.
147 *
148 * @param decode controls whether sequences of escaped octets are decoded
149 * (true) or not (false).
150 * @return an unmodifiable map of parameter names and values
151 * @throws java.lang.IllegalStateException if called outside the scope of a request
152 * @see javax.ws.rs.Path
153 * @see javax.ws.rs.PathParam
154 */
155 public MultivaluedMap<String, String> getPathParameters(boolean decode);
156
157 /**
158 * Get the URI query parameters of the current request.
159 * The map keys are the names of the query parameters with any
160 * escaped characters decoded.
161 * All sequences of escaped octets in parameter values are decoded,
162 * equivalent to <code>getQueryParameters(true)</code>.
163 * @return an unmodifiable map of query parameter names and values
164 * @throws java.lang.IllegalStateException if called outside the scope of a request
165 */
166 public MultivaluedMap<String, String> getQueryParameters();
167
168 /**
169 * Get the URI query parameters of the current request.
170 * The map keys are the names of the query parameters with any
171 * escaped characters decoded.
172 * @param decode controls whether sequences of escaped octets in parameter
173 * values are decoded (true) or not (false).
174 * @return an unmodifiable map of query parameter names and values
175 * @throws java.lang.IllegalStateException if called outside the scope of a request
176 */
177 public MultivaluedMap<String, String> getQueryParameters(boolean decode);
178
179 /**
180 * Get a read-only list of URIs for matched resources. Each entry is a
181 * relative URI that matched a resource class, a
182 * sub-resource method or a sub-resource locator. All sequences of escaped
183 * octets are decoded, equivalent to {@code getMatchedURIs(true)}.
184 * Entries do not include query parameters but do include matrix parameters
185 * if present in the request URI. Entries are ordered in reverse request
186 * URI matching order, with the current resource URI first. E.g. given the
187 * following resource classes:
188 *
189 * <pre>@Path("foo")
190 *public class FooResource {
191 * @GET
192 * public String getFoo() {...}
193 *
194 * @Path("bar")
195 * public BarResource getBarResource() {...}
196 *}
197 *
198 *public class BarResource {
199 * @GET
200 * public String getBar() {...}
201 *}
202 * </pre>
203 *
204 * <p>The values returned by this method based on request uri and where
205 * the method is called from are:</p>
206 *
207 * <table border="1">
208 * <tr>
209 * <th>Request</th>
210 * <th>Called from</th>
211 * <th>Value(s)</th>
212 * </tr>
213 * <tr>
214 * <td>GET /foo</td>
215 * <td>FooResource.getFoo</td>
216 * <td>foo</td>
217 * </tr>
218 * <tr>
219 * <td>GET /foo/bar</td>
220 * <td>FooResource.getBarResource</td>
221 * <td>foo/bar, foo</td>
222 * </tr>
223 * <tr>
224 * <td>GET /foo/bar</td>
225 * <td>BarResource.getBar</td>
226 * <td>foo/bar, foo</td>
227 * </tr>
228 * </table>
229 *
230 *
231 * @return a read-only list of URI paths for matched resources.
232 */
233 public List<String> getMatchedURIs();
234
235 /**
236 * Get a read-only list of URIs for matched resources. Each entry is a
237 * relative URI that matched a resource class, a sub-resource
238 * method or a sub-resource locator. Entries do not include query
239 * parameters but do include matrix parameters if present in the request URI.
240 * Entries are ordered in reverse request URI matching order, with the
241 * current resource URI first. See {@link #getMatchedURIs()} for an
242 * example.
243 *
244 * @param decode controls whether sequences of escaped octets are decoded
245 * (true) or not (false).
246 * @return a read-only list of URI paths for matched resources.
247 */
248 public List<String> getMatchedURIs(boolean decode);
249
250 /**
251 * Get a read-only list of the currently matched resource class instances.
252 * Each entry is a resource class instance that matched the request URI
253 * either directly or via a sub-resource method or a sub-resource locator.
254 * Entries are ordered according to reverse request URI matching order,
255 * with the current resource first. E.g. given the following resource
256 * classes:
257 *
258 * <pre>@Path("foo")
259 *public class FooResource {
260 * @GET
261 * public String getFoo() {...}
262 *
263 * @Path("bar")
264 * public BarResource getBarResource() {...}
265 *}
266 *
267 *public class BarResource {
268 * @GET
269 * public String getBar() {...}
270 *}
271 * </pre>
272 *
273 * <p>The values returned by this method based on request uri and where
274 * the method is called from are:</p>
275 *
276 * <table border="1">
277 * <tr>
278 * <th>Request</th>
279 * <th>Called from</th>
280 * <th>Value(s)</th>
281 * </tr>
282 * <tr>
283 * <td>GET /foo</td>
284 * <td>FooResource.getFoo</td>
285 * <td>FooResource</td>
286 * </tr>
287 * <tr>
288 * <td>GET /foo/bar</td>
289 * <td>FooResource.getBarResource</td>
290 * <td>FooResource</td>
291 * </tr>
292 * <tr>
293 * <td>GET /foo/bar</td>
294 * <td>BarResource.getBar</td>
295 * <td>BarResource, FooResource</td>
296 * </tr>
297 * </table>
298 *
299 * @return a read-only list of matched resource class instances.
300 */
301 public List<Object> getMatchedResources();
302 }