    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.http;
    014
    015import java.util.List;
    016
    017import org.apache.commons.codec.net.URLCodec;
    018import org.apache.tapestry5.http.services.BaseURLSource;
    019import org.apache.tapestry5.http.services.Request;
    020import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
    021
    022/**
    023 * A link is the Tapestry representation of a URL or URI that triggers dynamic behavior. This link is in three parts: a
    024 * path portion, an optional anchor, and a set of query parameters. A request for a link will ultimately be recognized
    025 * by a {@link org.apache.tapestry5.http.services.Dispatcher}.
    026 *
    027 * Query parameter values are kept separate from the path portion to support encoding those values into hidden form
    028 * fields (where appropriate).
    029 */
    030public interface Link
    031{
    032    /**
    033     * Returns the names of any additional query parameters for the URI. Query parameters store less regular or less
    034     * often used values that can not be expressed in the path. They also are used to store, or link to, persistent
    035     * state.
    036     *
    037     * @return list of query parameter names, is alphabetical order
    038     */
    039    List<String> getParameterNames();
    040
    041    /**
    042     * Returns the value of a specifically named query parameter, or <code>null</code> if no such query parameter is stored
    043     * in the link.
    044     *
    045     * Use this method only when you are sure the parameter has only one value. If the parameter might have more than
    046     * one value, use {@link #getParameterValues}.
    047     *
    048     * If you use this method with a multivalued parameter, the value returned is equal to the first value in the
    049     * array returned by <code>getParameterValues</code>.
    050     *
    051     * @return a string representing the single value of the named parameter
    052     */
    053    String getParameterValue(String name);
    054
    055    /**
    056     * Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value should be URL
    057     * encoded via {@link URLCodec}.
    058     *
    059     * @param parameterName
    060     *         the name of the parameter to store
    061     * @param value
    062     *         the value to store, a null or blank value is allowed (as of Tapestry 5.3)
    063     * @return this Link, to support method chaining
    064     */
    065    @IncompatibleChange(release = "5.4", details = "changed from void to Link")
    066    Link addParameter(String parameterName, String value);
    067
    068    /**
    069     * Adds a parameter value as a value object; the value object is converted to a string via
    070     * <a href="http://tapestry.apache.org/current/apidocs/src-html/org/apache/tapestry5/services/ContextPathEncoder.html#line.31">ContextPathEncoder.encodeValue(Object)</a>
    071     * from tapestry-core and the result is added via {@link #addParameter(String, String)}.
    072     * The Link object is returned for further configuration.
    073     *
    074     * @since 5.2.2
    075     */
    076    Link addParameterValue(String parameterName, Object value);
    077
    078    /**
    079     * Removes a parameter value, which is occasionally useful when transforming a parameter into a portion of
    080     * the path.
    081     *
    082     * @return this Link, to support method chaining
    083     * @since 5.2.0
    084     */
    085    @IncompatibleChange(release = "5.4", details = "changed from void to Link")
    086    Link removeParameter(String parameterName);
    087
    088    /**
    089     * Returns the completely unadorned base path. Other methods (such as {@link #toURI()}), may append
    090     * an anchor or query parameters.
    091     *
    092     * @since 5.2.0
    093     */
    094    String getBasePath();
    095
    096    /**
    097     * Creates a copy of this link that has the same parameters, anchor, and other attributes, but a different
    098     * {@linkplain #getBasePath() base path}.
    099     *
    100     * @return a new Link instance
    101     * @since 5.2.0
    102     */
    103    Link copyWithBasePath(String basePath);
    104
    105    /**
    106     * Returns the URI portion of the link. When the link is created for a form, this will not include query parameters.
    107     * This is the same value returned from toString().
    108     *
    109     * @return the URI, ready to be added as an element attribute
    110     */
    111    String toURI();
    112
    113    /**
    114     * Returns the link as a redirect URI. The URI includes any query parameters.
    115     */
    116    String toRedirectURI();
    117
    118    /**
    119     * Returns the link anchor. If this link does not have an anchor, this method returns <code>null</code>.
    120     *
    121     * @return the link anchor
    122     */
    123    String getAnchor();
    124
    125    /**
    126     * Sets the link anchor. Null and empty anchors will be ignored when building the link URI.
    127     *
    128     * @param anchor
    129     *         the link anchor
    130     * @return this Link, to support method chaining
    131     */
    132    @IncompatibleChange(release = "5.4", details = "changed from void to Link")
    133    Link setAnchor(String anchor);
    134
    135    /**
    136     * Returns the absolute URL, which includes the scheme, hostname and possibly port (as per
    137     * {@link BaseURLSource#getBaseURL(boolean)}).
    138     * By default, the scheme is chosen to match the {@linkplain Request#isSecure() security} of the current request.
    139     *
    140     * Note: the semantics of this method changed between Tapestry 5.1 and 5.2. Most code should use toString() or
    141     * {@link #toURI()} (which are equivalent) instead.
    142     *
    143     * @return the complete, qualified URL, including query parameters.
    144     */
    145    String toAbsoluteURI();
    146
    147    /**
    148     * Returns either the secure or insecure URL, with complete scheme, hostname and possibly port (as per
    149     * {@link BaseURLSource#getBaseURL(boolean)}).
    150     *
    151     * @return the complete, qualified URL, including query parameters.
    152     * @since 5.2.2
    153     */
    154    String toAbsoluteURI(boolean secure);
    155
    156    /**
    157     * Changes the link's security, which can be useful to force a link to be either secure or insecure
    158     * when normally it might not be.
    159     *
    160     * @param newSecurity
    161     *         new security value, not null, typically {@link LinkSecurity#FORCE_SECURE} or {@link LinkSecurity#FORCE_INSECURE}
    162     * @since 5.3
    163     */
    164    @IncompatibleChange(release = "5.4", details = "LinkSecurity class moved from internal package to org.apache.tapestry5.")
    165    void setSecurity(LinkSecurity newSecurity);
    166
    167    /**
    168     * Returns the current security for this link, which reflects whether the targeted page is itself secure or insecure.
    169     *
    170     * @since 5.3
    171     */
    172    @IncompatibleChange(release = "5.4", details = "LinkSecurity class moved from internal package to org.apache.tapestry5.")
    173    LinkSecurity getSecurity();
    174
    175    /**
    176     * Returns the parameter values for the given name. Returns null if no such parameter is stored in the link.
    177     */
    178    String[] getParameterValues(String parameterName);
    179
    180}