001 // Copyright 2006, 2007, 2008, 2010, 2011 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 import org.apache.tapestry5.internal.services.LinkSecurity;
019 import org.apache.tapestry5.services.BaseURLSource;
020 import org.apache.tapestry5.services.ContextPathEncoder;
021 import org.apache.tapestry5.services.Request;
022
023 import java.util.List;
024
025 /**
026 * A link is the Tapestry representation of a URL or URI that triggers dynamic behavior. This link is in three parts: a
027 * path portion, an optional anchor, and a set of query parameters. A request for a link will ultimately be recognized
028 * by a {@link org.apache.tapestry5.services.Dispatcher}.
029 * <p/>
030 * Query parameter values are kept separate from the path portion to support encoding those values into hidden form
031 * fields (where appropriate).
032 */
033 public interface Link
034 {
035 /**
036 * Returns the names of any additional query parameters for the URI. Query parameters store less regular or less
037 * often used values that can not be expressed in the path. They also are used to store, or link to, persistent
038 * state.
039 *
040 * @return list of query parameter names, is alphabetical order
041 */
042 List<String> getParameterNames();
043
044 /**
045 * Returns the value of a specifically named query parameter, or <tt>null</tt> if no such query parameter is stored
046 * in the link.
047 *
048 * @return the string value of the named parameter
049 */
050 String getParameterValue(String name);
051
052 /**
053 * Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value should be URL
054 * encoded via {@link URLCodec}.
055 *
056 * @param parameterName the name of the parameter to store
057 * @param value the value to store, a null or blank value is allowed (as of Tapestry 5.3)
058 * @throws IllegalArgumentException if the link already has a parameter with the given name
059 */
060 void addParameter(String parameterName, String value);
061
062 /**
063 * Adds a parameter value as a value object; the value object is converted to a string via
064 * {@link ContextPathEncoder#encodeValue(Object)} and the result is added via {@link #addParameter(String, String)}.
065 * The Link object is returned for further configuration.
066 *
067 * @since 5.2.2
068 */
069 Link addParameterValue(String parameterName, Object value);
070
071 /**
072 * Removes a parameter value, which is occasionally useful when transforming a parameter into a portion of
073 * the path.
074 *
075 * @since 5.2.0
076 */
077 void removeParameter(String parameterName);
078
079 /**
080 * Returns the completely unadorned base path. Other methods (such as {@link #toURI()}), may append
081 * an anchor or query parameters.
082 *
083 * @since 5.2.0
084 */
085 String getBasePath();
086
087 /**
088 * Creates a copy of this link that has the same parameters, anchor, and other attributes, but a different
089 * {@linkplain #getBasePath() base path}.
090 *
091 * @since 5.2.0
092 */
093 Link copyWithBasePath(String basePath);
094
095 /**
096 * Returns the URI portion of the link. When the link is created for a form, this will not include query parameters.
097 * This is the same value returned from toString().
098 *
099 * @return the URI, ready to be added as an element attribute
100 */
101 String toURI();
102
103 /**
104 * Returns the link as a redirect URI. The URI includes any query parameters.
105 */
106 String toRedirectURI();
107
108 /**
109 * Returns the link anchor. If this link does not have an anchor, this method returns <tt>null</tt>.
110 *
111 * @return the link anchor
112 */
113 String getAnchor();
114
115 /**
116 * Sets the link anchor. Null and empty anchors will be ignored when building the link URI.
117 *
118 * @param anchor the link anchor
119 */
120 void setAnchor(String anchor);
121
122 /**
123 * Returns the absolute URL, which includes the scheme, hostname and possibly port (as per
124 * {@link BaseURLSource#getBaseURL(boolean)}).
125 * By default, the scheme is chosen to match the current {@linkplain Request#isSecure() requests security}.
126 * <p/>
127 * Note: the semantics of this method changed between Tapestry 5.1 and 5.2. Most code should use toString() or
128 * {@link #toURI()} (which are equivalent) instead.
129 *
130 * @return the complete, qualified URL, including query parameters.
131 */
132 String toAbsoluteURI();
133
134 /**
135 * Returns either the secure or insecure URL, with complete scheme, hostname and possibly port (as per
136 * {@link BaseURLSource#getBaseURL(boolean)}).
137 *
138 * @return the complete, qualified URL, including query parameters.
139 * @since 5.2.2
140 */
141 String toAbsoluteURI(boolean secure);
142
143 /**
144 * Changes the link's security, which can be useful to force a link to be either secure or insecure
145 * when normally it might not be.
146 *
147 * @param newSecurity new security value, not null, typically {@link LinkSecurity#FORCE_SECURE} or {@link LinkSecurity#FORCE_INSECURE}
148 * @since 5.3
149 */
150 void setSecurity(LinkSecurity newSecurity);
151
152 /**
153 * Returns the current security for this link, which reflects whether the targetted page is itself secure or insecure.
154 *
155 * @since 5.3
156 */
157 LinkSecurity getSecurity();
158 }