001// Copyright 2006-2013 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 015package org.apache.tapestry5; 016 017import org.apache.commons.codec.net.URLCodec; 018import org.apache.tapestry5.ioc.annotations.IncompatibleChange; 019import org.apache.tapestry5.services.BaseURLSource; 020import org.apache.tapestry5.services.ContextPathEncoder; 021import org.apache.tapestry5.services.Request; 022 023import 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 */ 033public 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 * <p/> 048 * <p>Use this method only when you are sure the parameter has only one value. If the parameter might have more than 049 * one value, use {@link #getParameterValues}. 050 * <p/> 051 * <p>If you use this method with a multivalued parameter, the value returned is equal to the first value in the 052 * array returned by <code>getParameterValues</code>. 053 * 054 * @return a string representing the single value of the named parameter 055 */ 056 String getParameterValue(String name); 057 058 /** 059 * Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value should be URL 060 * encoded via {@link URLCodec}. 061 * 062 * @param parameterName 063 * the name of the parameter to store 064 * @param value 065 * the value to store, a null or blank value is allowed (as of Tapestry 5.3) 066 * @return this Link, to support method chaining 067 */ 068 @IncompatibleChange(release = "5.4", details = "changed from void to Link") 069 Link addParameter(String parameterName, String value); 070 071 /** 072 * Adds a parameter value as a value object; the value object is converted to a string via 073 * {@link ContextPathEncoder#encodeValue(Object)} and the result is added via {@link #addParameter(String, String)}. 074 * The Link object is returned for further configuration. 075 * 076 * @since 5.2.2 077 */ 078 Link addParameterValue(String parameterName, Object value); 079 080 /** 081 * Removes a parameter value, which is occasionally useful when transforming a parameter into a portion of 082 * the path. 083 * 084 * @return this Link, to support method chaining 085 * @since 5.2.0 086 */ 087 @IncompatibleChange(release = "5.4", details = "changed from void to Link") 088 Link removeParameter(String parameterName); 089 090 /** 091 * Returns the completely unadorned base path. Other methods (such as {@link #toURI()}), may append 092 * an anchor or query parameters. 093 * 094 * @since 5.2.0 095 */ 096 String getBasePath(); 097 098 /** 099 * Creates a copy of this link that has the same parameters, anchor, and other attributes, but a different 100 * {@linkplain #getBasePath() base path}. 101 * 102 * @return a new Link instance 103 * @since 5.2.0 104 */ 105 Link copyWithBasePath(String basePath); 106 107 /** 108 * Returns the URI portion of the link. When the link is created for a form, this will not include query parameters. 109 * This is the same value returned from toString(). 110 * 111 * @return the URI, ready to be added as an element attribute 112 */ 113 String toURI(); 114 115 /** 116 * Returns the link as a redirect URI. The URI includes any query parameters. 117 */ 118 String toRedirectURI(); 119 120 /** 121 * Returns the link anchor. If this link does not have an anchor, this method returns <tt>null</tt>. 122 * 123 * @return the link anchor 124 */ 125 String getAnchor(); 126 127 /** 128 * Sets the link anchor. Null and empty anchors will be ignored when building the link URI. 129 * 130 * @param anchor 131 * the link anchor 132 * @return this Link, to support method chaining 133 */ 134 @IncompatibleChange(release = "5.4", details = "changed from void to Link") 135 Link setAnchor(String anchor); 136 137 /** 138 * Returns the absolute URL, which includes the scheme, hostname and possibly port (as per 139 * {@link BaseURLSource#getBaseURL(boolean)}). 140 * By default, the scheme is chosen to match the {@linkplain Request#isSecure() security} of the current request. 141 * <p/> 142 * Note: the semantics of this method changed between Tapestry 5.1 and 5.2. Most code should use toString() or 143 * {@link #toURI()} (which are equivalent) instead. 144 * 145 * @return the complete, qualified URL, including query parameters. 146 */ 147 String toAbsoluteURI(); 148 149 /** 150 * Returns either the secure or insecure URL, with complete scheme, hostname and possibly port (as per 151 * {@link BaseURLSource#getBaseURL(boolean)}). 152 * 153 * @return the complete, qualified URL, including query parameters. 154 * @since 5.2.2 155 */ 156 String toAbsoluteURI(boolean secure); 157 158 /** 159 * Changes the link's security, which can be useful to force a link to be either secure or insecure 160 * when normally it might not be. 161 * 162 * @param newSecurity 163 * new security value, not null, typically {@link LinkSecurity#FORCE_SECURE} or {@link LinkSecurity#FORCE_INSECURE} 164 * @since 5.3 165 */ 166 @IncompatibleChange(release = "5.4", details = "LinkSecurity class moved from internal package to org.apache.tapestry5.") 167 void setSecurity(LinkSecurity newSecurity); 168 169 /** 170 * Returns the current security for this link, which reflects whether the targeted page is itself secure or insecure. 171 * 172 * @since 5.3 173 */ 174 @IncompatibleChange(release = "5.4", details = "LinkSecurity class moved from internal package to org.apache.tapestry5.") 175 LinkSecurity getSecurity(); 176 177 /** 178 * Returns the parameter values for the given name. Returns null if no such parameter is stored in the link. 179 */ 180 String[] getParameterValues(String parameterName); 181 182}