    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}