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