// Licensed 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.tapestry5;
import org.apache.commons.codec.net.URLCodec;
import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
import org.apache.tapestry5.services.BaseURLSource;
import org.apache.tapestry5.services.ContextPathEncoder;
import org.apache.tapestry5.services.Request;
import java.util.List;
/**
* A link is the Tapestry representation of a URL or URI that triggers dynamic behavior. This link is in three parts: a
* path portion, an optional anchor, and a set of query parameters. A request for a link will ultimately be recognized
* by a {@link org.apache.tapestry5.services.Dispatcher}.
*
* Query parameter values are kept separate from the path portion to support encoding those values into hidden form
* fields (where appropriate).
*/
public interface Link
{
/**
* Returns the names of any additional query parameters for the URI. Query parameters store less regular or less
* often used values that can not be expressed in the path. They also are used to store, or link to, persistent
* state.
*
* @return list of query parameter names, is alphabetical order
*/
List<String> getParameterNames();
/**
* Returns the value of a specifically named query parameter, or <tt>null</tt> if no such query parameter is stored
* in the link.
*
* Use this method only when you are sure the parameter has only one value. If the parameter might have more than
* one value, use {@link #getParameterValues}.
*
* If you use this method with a multivalued parameter, the value returned is equal to the first value in the
* array returned by <code>getParameterValues</code>.
*
* @return a string representing the single value of the named parameter
*/
String getParameterValue(String name);
/**
* Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value should be URL
* encoded via {@link URLCodec}.
*
* @param parameterName
* the name of the parameter to store
* @param value
* the value to store, a null or blank value is allowed (as of Tapestry 5.3)
* @return this Link, to support method chaining
*/
@IncompatibleChange(release = "5.4", details = "changed from void to Link")
Link addParameter(String parameterName, String value);
/**
* Adds a parameter value as a value object; the value object is converted to a string via
* {@link ContextPathEncoder#encodeValue(Object)} and the result is added via {@link #addParameter(String, String)}.
* The Link object is returned for further configuration.
*
* @since 5.2.2
*/
Link addParameterValue(String parameterName, Object value);
/**
* Removes a parameter value, which is occasionally useful when transforming a parameter into a portion of
* the path.
*
* @return this Link, to support method chaining
* @since 5.2.0
*/
@IncompatibleChange(release = "5.4", details = "changed from void to Link")
Link removeParameter(String parameterName);
/**
* Returns the completely unadorned base path. Other methods (such as {@link #toURI()}), may append
* an anchor or query parameters.
*
* @since 5.2.0
*/
String getBasePath();
/**
* Creates a copy of this link that has the same parameters, anchor, and other attributes, but a different
* {@linkplain #getBasePath() base path}.
*
* @return a new Link instance
* @since 5.2.0
*/
Link copyWithBasePath(String basePath);
/**
* Returns the URI portion of the link. When the link is created for a form, this will not include query parameters.
* This is the same value returned from toString().
*
* @return the URI, ready to be added as an element attribute
*/
String toURI();
/**
* Returns the link as a redirect URI. The URI includes any query parameters.
*/
String toRedirectURI();
/**
* Returns the link anchor. If this link does not have an anchor, this method returns <tt>null</tt>.
*
* @return the link anchor
*/
String getAnchor();
/**
* Sets the link anchor. Null and empty anchors will be ignored when building the link URI.
*
* @param anchor
* the link anchor
* @return this Link, to support method chaining
*/
@IncompatibleChange(release = "5.4", details = "changed from void to Link")
Link setAnchor(String anchor);
/**
* Returns the absolute URL, which includes the scheme, hostname and possibly port (as per
* {@link BaseURLSource#getBaseURL(boolean)}).
* By default, the scheme is chosen to match the {@linkplain Request#isSecure() security} of the current request.
*
* Note: the semantics of this method changed between Tapestry 5.1 and 5.2. Most code should use toString() or
* {@link #toURI()} (which are equivalent) instead.
*
* @return the complete, qualified URL, including query parameters.
*/
String toAbsoluteURI();
/**
* Returns either the secure or insecure URL, with complete scheme, hostname and possibly port (as per
* {@link BaseURLSource#getBaseURL(boolean)}).
*
* @return the complete, qualified URL, including query parameters.
* @since 5.2.2
*/
String toAbsoluteURI(boolean secure);
/**
* Changes the link's security, which can be useful to force a link to be either secure or insecure
* when normally it might not be.
*
* @param newSecurity
* new security value, not null, typically {@link LinkSecurity#FORCE_SECURE} or {@link LinkSecurity#FORCE_INSECURE}
* @since 5.3
*/
@IncompatibleChange(release = "5.4", details = "LinkSecurity class moved from internal package to org.apache.tapestry5.")
void setSecurity(LinkSecurity newSecurity);
/**
* Returns the current security for this link, which reflects whether the targeted page is itself secure or insecure.
*
* @since 5.3
*/
@IncompatibleChange(release = "5.4", details = "LinkSecurity class moved from internal package to org.apache.tapestry5.")
LinkSecurity getSecurity();
/**
* Returns the parameter values for the given name. Returns null if no such parameter is stored in the link.
*/
String[] getParameterValues(String parameterName);
}