1 package org.apache.fulcrum.parser;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23
24 import javax.servlet.http.HttpServletRequest;
25 import javax.servlet.http.Part;
26
27 import org.apache.avalon.framework.service.ServiceException;
28 import org.apache.fulcrum.parser.ValueParser.URLCaseFolding;
29
30 /**
31 * ParserService defines the methods which are needed by the parser objects
32 * to get their necessities.
33 *
34 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
35 * @version $Id: ValueParser.java 535465 2007-05-05 06:58:06Z tv $
36 */
37 public interface ParserService
38 {
39 /** Avalon Identifier **/
40 String ROLE = ParserService.class.getName();
41
42 /** Default Encoding for Parameter Parser */
43 String PARAMETER_ENCODING_DEFAULT = "ISO-8859-1";
44
45 /** Key for the Parameter Parser Encoding */
46 String PARAMETER_ENCODING_KEY = "parameterEncoding";
47
48 /** Property for setting the URL folding value */
49 String URL_CASE_FOLDING_KEY = "urlCaseFolding";
50
51 /** Parse file upload items automatically */
52 String AUTOMATIC_KEY = "automaticUpload";
53
54 /** fulcrum pool by default false */
55 boolean FULCRUM_POOL_DEFAULT = false;
56
57 /** fulcrum pool activation parameter */
58 String FULCRUM_POOL_KEY = "fulcrumPool";
59
60 /** commons pool2 parameters */
61 String POOL_KEY = "pool2";
62
63 /**
64 * <p> The default value of 'automaticUpload' property
65 * (<code>false</code>). If set to <code>true</code>, parsing the
66 * multipart request will be performed automatically by {@link
67 * org.apache.fulcrum.parser.ParameterParser}. Otherwise, an
68 * org.apache.turbine.modules.Action may decide to parse the
69 * request by calling {@link #parseUpload(HttpServletRequest)
70 * parseRequest} manually.
71 */
72 boolean AUTOMATIC_DEFAULT = false;
73
74 /**
75 * <p> The default value of 'maxTotal' property in 'pool'
76 * (<code>1024</code>). The default pool capacity.
77 */
78 int DEFAULT_POOL_CAPACITY = 1024;
79
80 /**
81 * <p> The default value of 'maxIdle' property in 'pool'
82 * (<code>2</code>). The default maximum idle object.
83 */
84 int DEFAULT_MAX_IDLE = 2;
85
86 /**
87 * Get the parameter encoding that has been configured as default for
88 * the ParserService.
89 *
90 * @return A String for the parameter encoding
91 */
92 String getParameterEncoding();
93
94 /**
95 * Trims the string data and applies the conversion specified in
96 * the property given by URL_CASE_FOLDING. It returns a new
97 * string so that it does not destroy the value data.
98 *
99 * @param value A String to be processed.
100 * @return A new String converted to lowercase and trimmed.
101 */
102 String convert(String value);
103
104 /**
105 * Convert a String value according to the url-case-folding property.
106 *
107 * @param value the String to convert
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, URLCaseFolding fold);
124
125 /**
126 * Gets the folding value from the configuration
127 *
128 * @return The current Folding Value
129 */
130 URLCaseFolding 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 * Parse the given request for uploaded files
141 *
142 * @param request the HttpServletRequest object
143 * @return A list of {@link javax.servlet.http.Part}s
144 * @throws ServiceException if parsing fails
145 */
146 List<Part> parseUpload(HttpServletRequest request) throws ServiceException;
147
148 /**
149 * Get a {@link ValueParser} instance from the service. Use the
150 * default implementation.
151 *
152 * @param <P> The ValueParser we are using
153 * @param ppClass parameter parser class
154 * @return An object that implements ValueParser
155 * @throws InstantiationException if the instance could not be created
156 */
157 <P extends ValueParser> P getParser(Class<P> ppClass) throws InstantiationException;
158
159 /**
160 * Put the parser into service
161 *
162 * @param parser The value parser to be used
163 */
164 void putParser(ValueParser parser);
165 }
166