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