01: // Copyright 2006, 2007 The Apache Software Foundation
02: //
03: // Licensed under the Apache License, Version 2.0 (the "License");
04: // you may not use this file except in compliance with the License.
05: // You may obtain a copy of the License at
06: //
07: // http://www.apache.org/licenses/LICENSE-2.0
08: //
09: // 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;
16:
17: import java.util.List;
18:
19: import org.apache.commons.codec.net.URLCodec;
20: import org.apache.tapestry.services.Dispatcher;
21:
22: /**
23: * A link is the Tapestry representation of a URL or URI that triggers dynamic behavior. This link
24: * is in two parts: a path portion and a set of query parameters. A request for a link will
25: * ultimately be recognized by a {@link Dispatcher}.
26: * <p>
27: * Query parameter values are kept separate from the path portion to support encoding those values
28: * into hidden form fields (where appropriate).
29: */
30: public interface Link {
31: /**
32: * The names of any additional query parameters for the URI. Query parameters store less regular
33: * or less often used values that can not be expressed in the path. They also are used to store,
34: * or link to, persistent state.
35: *
36: * @return list of query parameter names, is alphabetical order
37: */
38: List<String> getParameterNames();
39:
40: /**
41: * Returns the value of a specifically named query parameter, or null if no such query parameter
42: * is stored in the link.
43: */
44:
45: String getParameterValue(String name);
46:
47: /**
48: * Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value
49: * should be URL encoded via {@link URLCodec}.
50: *
51: * @param parameterName
52: * the name of the parameter to store
53: * @param value
54: * the value to store
55: * @throws IllegalArgumentException
56: * if the link already has a parameter with the given name
57: */
58: void addParameter(String parameterName, String value);
59:
60: /**
61: * Returns the URI portion of the link. When the link is created for a form, this will not
62: * include query parameters. This is the same value returned from toString().
63: *
64: * @return the URI, ready to be added as an element attribute
65: */
66: String toURI();
67:
68: /** Returns the link as a redirect URI. The URI includes any query parameters. */
69: String toRedirectURI();
70: }
|