001 // Copyright 2004, 2005 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.tapestry.engine;
016
017 /**
018 * Define a link that may be generated as part of a page render. The vast majority of links are tied
019 * to {@link IEngineService services}and are, in fact, callbacks. A small number, such as those
020 * generated by {@link org.apache.tapestry.link.GenericLink} component, are to arbitrary locations.
021 * In addition, ILink differentiates between the path portion of the link, and any query parameters
022 * encoded into a link, primarily to benefit {@link org.apache.tapestry.form.Form}, which needs to
023 * encode the query parameters as hidden form fields.
024 * <p>
025 * In addition, an ILink is responsible for passing constructed URLs through
026 * {@link org.apache.tapestry.IRequestCycle#encodeURL(String)} as needed.
027 *
028 * @author Howard Lewis Ship
029 * @since 3.0
030 */
031
032 public interface ILink
033 {
034 /**
035 * Returns the relative URL as a String. A relative URL may include a leading slash, but omits
036 * the scheme, host and port portions of a full URL.
037 *
038 * @return the relative URL, with no anchor, but including query parameters.
039 */
040
041 String getURL();
042
043 /**
044 * Returns the relative URL as a String. This is used for most links.
045 *
046 * @param anchor
047 * if not null, appended to the URL
048 * @param includeParameters
049 * if true, parameters are included
050 */
051
052 String getURL(String anchor, boolean includeParameters);
053
054 /**
055 * Returns the absolute URL as a String, using default scheme, server and port, including
056 * parameters, and no anchor.
057 */
058
059 String getAbsoluteURL();
060
061 /**
062 * Returns the absolute URL as a String.
063 *
064 * @param scheme
065 * if not null, overrides the default scheme.
066 * @param server
067 * if not null, overrides the default server
068 * @param port
069 * if non-zero, overrides the default port
070 * @param anchor
071 * if not null, appended to the URL
072 * @param includeParameters
073 * if true, parameters are included
074 */
075
076 String getAbsoluteURL(String scheme, String server, int port, String anchor,
077 boolean includeParameters);
078
079 /**
080 * Returns the URL as either a local or absoluate URL, depending on whether any of the
081 * parameters are both non-null and mismatched against the incoming request.
082 *
083 * @param scheme
084 * if not null, overrides the default scheme.
085 * @param server
086 * if not null, overrides the default server
087 * @param port
088 * if non-zero, overrides the default port
089 * @param anchor
090 * if not null, appended to the URL
091 * @param includeParameters
092 * if true, parameters are included
093 * @see #getURL(String, boolean)
094 * @see #getAbsoluteURL(String, String, int, String, boolean)
095 * @since 4.0
096 */
097
098 String getURL(String scheme, String server, int port, String anchor,
099 boolean includeParameters);
100
101 /**
102 * Returns an array of parameters names (in no alphabetical order).
103 *
104 * @see #getParameterValues(String)
105 */
106
107 String[] getParameterNames();
108
109 /**
110 * Returns the values for the named parameter. Will return null if no value is defined for
111 * the parameter.
112 */
113
114 String[] getParameterValues(String name);
115 }