Java tutorial
/* * 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.wicket.request; import java.nio.charset.Charset; import java.util.Locale; import org.apache.wicket.request.parameter.CombinedRequestParametersAdapter; import org.apache.wicket.request.parameter.EmptyRequestParameters; import org.apache.wicket.request.parameter.UrlRequestParametersAdapter; /** * Request object. * * @author Matej Knopp */ public abstract class Request { /** * Returns the URL for this request. URL is relative to Wicket filter path. * * @return Url instance */ public abstract Url getUrl(); /** * Returns the url against which the client, usually the browser, will resolve relative urls in * the rendered markup. If the client is a browser this is the url in the browser's address bar. * * <p> * Under normal circumstances the client and request ({@link #getUrl()}) urls are the same. * Handling an Ajax request, however, is a good example of when they may be different. * Technologies such as XHR are free to request whatever url they wish <strong>without * modifying</strong> the client url; however, any produced urls will be evaluated by the client * against the client url - not against the request url. * </p> * <p> * Lets take a simple example: <br> * * Suppose we are on a client detail page. This page contains an Ajax link which opens a list of * client's orders. Each order has a link that goes to the order detail page. * * The client detail page is located at * * <pre> * /detail/customer/15 * </pre> * * and the order detail page is located at * * <pre> * /order/22 * </pre> * * The Ajax link which renders the detail section is located at * * <pre> * /detail/wicket?page 3 * </pre> * * Lets run through the execution and see what happens when the XHR request is processed: * * <pre> * request 1: /details/customer/15 * client url: details/customer/15 (the url in the browser's address bar) * request url: details/customer/15 * Wicket renders relative Ajax details anchor as ../../wicket/page?3 * * ../../wicket/page?3 resolved against current client url details/customer/15 yields: * request 2: /wicket/page?3 * client url: customer/15 (unchanged since XHRs requests dont change it) * request url: wicket/ajax/page?3 * * now Wicket has to render a relative url to /details/order/22. If Wicket renders * it against the request url it will be: ../order/22, and later evaluated on the * client will result in /customer/order/22 which is incorrect. * </pre> * * This is why implementations of {@link Request} must track the client url, so that relative * urls can be rendered against the same url they will be evaluated against on the client - * which is not always the same as the request url. For example, Wicket's Ajax implementation * always sends the current client url in a header along with the XHR request so that Wicket can * correctly render relative urls against it. * </p> * * @return client url */ public abstract Url getClientUrl(); /** * In case this request has been created using {@link #cloneWithUrl(Url)}, this method should * return the original URL. * * @return original URL */ public Url getOriginalUrl() { return getUrl(); } /** * @return POST request parameters for this request. */ public IRequestParameters getPostParameters() { return EmptyRequestParameters.INSTANCE; } /** * @return GET request parameters for this request. */ public IRequestParameters getQueryParameters() { return new UrlRequestParametersAdapter(getUrl()); } /** * @return all request parameters for this request (both POST and GET parameters) */ public IRequestParameters getRequestParameters() { return new CombinedRequestParametersAdapter(getPostParameters(), getQueryParameters()); } /** * Returns locale for this request. * * @return locale */ public abstract Locale getLocale(); /** * Returns request with specified URL and same POST parameters as this request. * * @param url * Url instance * @return request with specified URL. */ public Request cloneWithUrl(final Url url) { return new Request() { @Override public Url getUrl() { return url; } @Override public Url getOriginalUrl() { return Request.this.getOriginalUrl(); } @Override public Locale getLocale() { return Request.this.getLocale(); } @Override public IRequestParameters getPostParameters() { return Request.this.getPostParameters(); } @Override public Charset getCharset() { return Request.this.getCharset(); } @Override public Url getClientUrl() { return Request.this.getClientUrl(); } @Override public Object getContainerRequest() { return Request.this.getContainerRequest(); } }; } /** * Returns prefix from Wicket Filter mapping to context path. This method does not take the * actual URL into account. * <p> * For example if Wicket filter is mapped to hello/* this method should return ../ regardless of * actual URL (after Wicket filter) * * @return prefix to context path for this request. * */ public String getPrefixToContextPath() { return ""; } /** * Returns the context path or an empty string if the application is running under root context. * Returned path, unless an empty string, will always start with a slash and will never end with * a slash. * * @return context path */ public String getContextPath() { return ""; } /** * Returns the path to which wicket Filter is mapped or an empty string if the filter is mapped * to {@code /*}. Returned path, unless an empty string, will always start with a slash and will * never end with a slash. * * @return filter path */ public String getFilterPath() { return ""; } /** * Gets charset of the request * * @return request charset */ public abstract Charset getCharset(); /** * Provides access to the low-level container request object that implementaion of this * {@link Request} delegate to. This allows users to access features provided by the container * requests but not by generalized Wicket {@link Request} objects. * * @return low-level container request object, or {@code null} if none */ public abstract Object getContainerRequest(); }