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