001 // Copyright 2006, 2007, 2008 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry5;
016
017 import org.apache.commons.codec.net.URLCodec;
018
019 import java.util.List;
020
021 /**
022 * A link is the Tapestry representation of a URL or URI that triggers dynamic behavior. This link is in three parts: a
023 * path portion, an optional anchor, and a set of query parameters. A request for a link will ultimately be recognized
024 * by a {@link org.apache.tapestry5.services.Dispatcher}.
025 * <p/>
026 * Query parameter values are kept separate from the path portion to support encoding those values into hidden form
027 * fields (where appropriate).
028 */
029 public interface Link
030 {
031 /**
032 * Returns the names of any additional query parameters for the URI. Query parameters store less regular or less
033 * often used values that can not be expressed in the path. They also are used to store, or link to, persistent
034 * state.
035 *
036 * @return list of query parameter names, is alphabetical order
037 */
038 List<String> getParameterNames();
039
040 /**
041 * Returns the value of a specifically named query parameter, or <tt>null</tt> if no such query parameter is stored
042 * in the link.
043 *
044 * @return the value of the named parameter
045 */
046 String getParameterValue(String name);
047
048 /**
049 * Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value should be URL
050 * encoded via {@link URLCodec}.
051 *
052 * @param parameterName the name of the parameter to store
053 * @param value the value to store
054 * @throws IllegalArgumentException if the link already has a parameter with the given name
055 */
056 void addParameter(String parameterName, String value);
057
058 /**
059 * Returns the URI portion of the link. When the link is created for a form, this will not include query parameters.
060 * This is the same value returned from toString(). In some circumstances, this may be a relative URI (relative to
061 * the current Request's URI).
062 *
063 * @return the URI, ready to be added as an element attribute
064 */
065 String toURI();
066
067 /**
068 * Returns the link as a redirect URI. The URI includes any query parameters.
069 */
070 String toRedirectURI();
071
072 /**
073 * Returns the link anchor. If this link does not have an anchor, this method returns <tt>null</tt>.
074 *
075 * @return the link anchor
076 */
077 String getAnchor();
078
079 /**
080 * Sets the link anchor. Null and empty anchors will be ignored when building the link URI.
081 *
082 * @param anchor the link anchor
083 */
084 void setAnchor(String anchor);
085
086 /**
087 * Converts the link to an absolute URI, a complete path, starting with a leading slash. This is necessary in many
088 * cases for client-side JavaScript that must send a request to application via XMLHttpRequest.
089 *
090 * @return the complete URI (not abbreviated relative to the current request path)
091 */
092 String toAbsoluteURI();
093 }