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 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 */ 032 public 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 }