001 package org.apache.fulcrum.parser;
002
003
004 /*
005 * Licensed to the Apache Software Foundation (ASF) under one
006 * or more contributor license agreements. See the NOTICE file
007 * distributed with this work for additional information
008 * regarding copyright ownership. The ASF licenses this file
009 * to you under the Apache License, Version 2.0 (the
010 * "License"); you may not use this file except in compliance
011 * with the License. You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing,
016 * software distributed under the License is distributed on an
017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018 * KIND, either express or implied. See the License for the
019 * specific language governing permissions and limitations
020 * under the License.
021 */
022
023
024 import java.util.List;
025
026 import javax.servlet.http.HttpServletRequest;
027
028 import org.apache.avalon.framework.service.ServiceException;
029
030
031 /**
032 * ParserService defines the methods which are needed by the parser objects
033 * to get their necessities.
034 *
035 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
036 * @version $Id: ValueParser.java 535465 2007-05-05 06:58:06Z tv $
037 */
038 public interface ParserService
039 {
040 /** Avalon Identifier **/
041 String ROLE = ParserService.class.getName();
042
043 /** Default Encoding for Parameter Parser */
044 String PARAMETER_ENCODING_DEFAULT = "ISO-8859-1";
045
046 /** Key for the Parameter Parser Encoding */
047 String PARAMETER_ENCODING_KEY = "parameterEncoding";
048
049 /** Property for setting the URL folding value */
050 String URL_CASE_FOLDING_KEY = "urlCaseFolding";
051
052 /** No folding */
053 String URL_CASE_FOLDING_NONE_VALUE = "none";
054
055 /** Fold to lower case */
056 String URL_CASE_FOLDING_LOWER_VALUE = "lower";
057
058 /** Fold to upper case */
059 String URL_CASE_FOLDING_UPPER_VALUE = "upper";
060
061 /** No folding set */
062 int URL_CASE_FOLDING_UNSET = 0;
063
064 /** Folding set to "no folding" */
065 int URL_CASE_FOLDING_NONE = 1;
066
067 /** Folding set to "lowercase" */
068 int URL_CASE_FOLDING_LOWER = 2;
069
070 /** Folding set to "uppercase" */
071 int URL_CASE_FOLDING_UPPER = 3;
072
073 /** Parse file upload items automatically */
074 String AUTOMATIC_KEY = "automaticUpload";
075
076 /**
077 * <p> The default value of 'automaticUpload' property
078 * (<code>false</code>). If set to <code>true</code>, parsing the
079 * multipart request will be performed automatically by {@link
080 * org.apache.fulcrum.parser.ParameterParser}. Otherwise, an {@link
081 * org.apache.turbine.modules.Action} may decide to parse the
082 * request by calling {@link #parseUpload(HttpServletRequest)
083 * parseRequest} manually.
084 */
085 boolean AUTOMATIC_DEFAULT = false;
086
087 /**
088 * Get the parameter encoding that has been configured as default for
089 * the ParserService.
090 */
091 String getParameterEncoding();
092
093 /**
094 * Trims the string data and applies the conversion specified in
095 * the property given by URL_CASE_FOLDING. It returns a new
096 * string so that it does not destroy the value data.
097 *
098 * @param value A String to be processed.
099 * @return A new String converted to lowercase and trimmed.
100 */
101 String convert(String value);
102
103 /**
104 * Convert a String value according to the url-case-folding property.
105 *
106 * @param value the String to convert
107 *
108 * @return a new String.
109 *
110 */
111 String convertAndTrim(String value);
112
113 /**
114 * A convert method, which trims the string data and applies the
115 * conversion specified in the parameter given. It returns a new
116 * string so that it does not destroy the value data.
117 *
118 * @param value A String to be processed.
119 * @param fold The parameter folding to be applied
120 * (see {@link ParserService})
121 * @return A new String converted to the correct case and trimmed.
122 */
123 String convertAndTrim(String value, int fold);
124
125 /**
126 * Gets the folding value from the configuration
127 *
128 * @return The current Folding Value
129 */
130 int getUrlFolding();
131
132 /**
133 * Gets the automaticUpload value from the configuration
134 *
135 * @return The current automaticUpload Value
136 */
137 boolean getAutomaticUpload();
138
139 /**
140 * Use the UploadService if available to parse the given request
141 * for uploaded files
142 *
143 * @return A list of {@link org.apache.commons.upload.FileItem}s
144 *
145 * @throws ServiceException if parsing fails or the UploadService
146 * is not available
147 */
148 List parseUpload(HttpServletRequest request) throws ServiceException;
149
150 /**
151 * Get a {@link ValueParser} instance from the service. Use the
152 * default imlementation.
153 *
154 * @return An object that implements ValueParser
155 *
156 * @throws InstantiationException if the instance could not be created
157 */
158 ValueParser getParser(Class ppClass) throws InstantiationException;
159
160 /**
161 * Return a used Parser to the service. This allows for
162 * pooling and recycling
163 *
164 * @param parser
165 */
166 void putParser(ValueParser parser);
167 }
168