Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ILink |
|
| 1.0;1 |
1 | // Copyright 2004, 2005 The Apache Software Foundation | |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 | // you may not use this file except in compliance with the License. | |
5 | // You may obtain a copy of the License at | |
6 | // | |
7 | // http://www.apache.org/licenses/LICENSE-2.0 | |
8 | // | |
9 | // Unless required by applicable law or agreed to in writing, software | |
10 | // distributed under the License is distributed on an "AS IS" BASIS, | |
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 | // See the License for the specific language governing permissions and | |
13 | // limitations under the License. | |
14 | ||
15 | package org.apache.tapestry.engine; | |
16 | ||
17 | /** | |
18 | * Define a link that may be generated as part of a page render. The vast majority of links are tied | |
19 | * to {@link IEngineService services}and are, in fact, callbacks. A small number, such as those | |
20 | * generated by {@link org.apache.tapestry.link.GenericLink} component, are to arbitrary locations. | |
21 | * In addition, ILink differentiates between the path portion of the link, and any query parameters | |
22 | * encoded into a link, primarily to benefit {@link org.apache.tapestry.form.Form}, which needs to | |
23 | * encode the query parameters as hidden form fields. | |
24 | * <p> | |
25 | * In addition, an ILink is responsible for passing constructed URLs through | |
26 | * {@link org.apache.tapestry.IRequestCycle#encodeURL(String)} as needed. | |
27 | * | |
28 | * @author Howard Lewis Ship | |
29 | * @since 3.0 | |
30 | */ | |
31 | ||
32 | public interface ILink | |
33 | { | |
34 | /** | |
35 | * Returns the relative URL as a String. A relative URL may include a leading slash, but omits | |
36 | * the scheme, host and port portions of a full URL. | |
37 | * | |
38 | * @return the relative URL, with no anchor, but including query parameters. | |
39 | */ | |
40 | ||
41 | String getURL(); | |
42 | ||
43 | /** | |
44 | * Returns the relative URL as a String. This is used for most links. | |
45 | * | |
46 | * @param anchor | |
47 | * if not null, appended to the URL | |
48 | * @param includeParameters | |
49 | * if true, parameters are included | |
50 | */ | |
51 | ||
52 | String getURL(String anchor, boolean includeParameters); | |
53 | ||
54 | /** | |
55 | * Returns the absolute URL as a String, using default scheme, server and port, including | |
56 | * parameters, and no anchor. | |
57 | */ | |
58 | ||
59 | String getAbsoluteURL(); | |
60 | ||
61 | /** | |
62 | * Returns the absolute URL as a String. | |
63 | * | |
64 | * @param scheme | |
65 | * if not null, overrides the default scheme. | |
66 | * @param server | |
67 | * if not null, overrides the default server | |
68 | * @param port | |
69 | * if non-zero, overrides the default port | |
70 | * @param anchor | |
71 | * if not null, appended to the URL | |
72 | * @param includeParameters | |
73 | * if true, parameters are included | |
74 | */ | |
75 | ||
76 | String getAbsoluteURL(String scheme, String server, int port, String anchor, | |
77 | boolean includeParameters); | |
78 | ||
79 | /** | |
80 | * Returns the URL as either a local or absoluate URL, depending on whether any of the | |
81 | * parameters are both non-null and mismatched against the incoming request. | |
82 | * | |
83 | * @param scheme | |
84 | * if not null, overrides the default scheme. | |
85 | * @param server | |
86 | * if not null, overrides the default server | |
87 | * @param port | |
88 | * if non-zero, overrides the default port | |
89 | * @param anchor | |
90 | * if not null, appended to the URL | |
91 | * @param includeParameters | |
92 | * if true, parameters are included | |
93 | * @see #getURL(String, boolean) | |
94 | * @see #getAbsoluteURL(String, String, int, String, boolean) | |
95 | * @since 4.0 | |
96 | */ | |
97 | ||
98 | String getURL(String scheme, String server, int port, String anchor, | |
99 | 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 | } |