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 * Contains the information needed to encode a request for a service; the
019 * servlet path plus and query parameters. The service encoding is passed to
020 * each {@link org.apache.tapestry.engine.ServiceEncoder} , which is
021 * allowed to modify the encoding (typically, by changing the servlet path and
022 * settting query parameters to null). From this modified encoding, an
023 * {@link org.apache.tapestry.engine.ILink}can be constructed.
024 * <p>
025 * Additionally, when a request is dispatched by Tapestry, an SRE is also
026 * created and passed to each {@link org.apache.tapestry.engine.ServiceEncoder} for
027 * decoding. Here, the query parameters that may have been nulled out by the
028 * encoding are restored.
029 *
030 * @author Howard M. Lewis Ship
031 * @since 4.0
032 * @see org.apache.tapestry.services.ServiceConstants
033 */
034 public interface ServiceEncoding
035 {
036
037 /**
038 * Returns the value for the named parameter. If multiple values are stored
039 * for the query parameter, only the first is returned.
040 *
041 * @parameter name the name of the query parameter to access
042 * @return the value, or null if no such query parameter exists
043 */
044
045 String getParameterValue(String name);
046
047 /**
048 * Returns the value for the named parameter.
049 *
050 * @parameter name the name of the query parameter to access
051 * @return the values, or null if no such query parameter exists
052 */
053 String[] getParameterValues(String name);
054
055 /**
056 * Updates the servlet path for the encoding. In some cases, this is a
057 * combination of the servlet and additional path info.
058 */
059
060 void setServletPath(String servletPath);
061
062 /**
063 * Sets the value for the named query parameter to the provided string.
064 *
065 * @param name
066 * the name of the parameter to set.
067 * @param value
068 * the new value, which may be null.
069 */
070 void setParameterValue(String name, String value);
071
072 /**
073 * Sets the values for a named query parameter.
074 */
075
076 void setParameterValues(String name, String[] values);
077
078 /**
079 * Returns the servlet path for the request. This is the portion of the URL
080 * recognized as the servlet. When the URL pattern (in web.xml) ends in a
081 * "*" (such as "/book/*"), this method will return the matched servlet
082 * portion ("/book/") and {#link #getPathInfo} will return the rest of the
083 * URL.
084 */
085
086 String getServletPath();
087
088 /**
089 * Returns the portion of the URL after the servlet itself.
090 *
091 * @return pathInfo if path info was supplied in the request, or null
092 * otherwise.
093 */
094 String getPathInfo();
095
096 /**
097 * Returns an array of parameter names. The names are returned in
098 * alphabetically sorted order. This list includes all parameter names, even
099 * those for which the stored value is null.
100 */
101
102 String[] getParameterNames();
103 }