ParserService.java

  1. package org.apache.fulcrum.parser;

  2. /*
  3.  * Licensed to the Apache Software Foundation (ASF) under one
  4.  * or more contributor license agreements.  See the NOTICE file
  5.  * distributed with this work for additional information
  6.  * regarding copyright ownership.  The ASF licenses this file
  7.  * to you under the Apache License, Version 2.0 (the
  8.  * "License"); you may not use this file except in compliance
  9.  * with the License.  You may obtain a copy of the License at
  10.  *
  11.  *   http://www.apache.org/licenses/LICENSE-2.0
  12.  *
  13.  * Unless required by applicable law or agreed to in writing,
  14.  * software distributed under the License is distributed on an
  15.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  16.  * KIND, either express or implied.  See the License for the
  17.  * specific language governing permissions and limitations
  18.  * under the License.
  19.  */

  20. import java.util.List;

  21. import javax.servlet.http.HttpServletRequest;
  22. import javax.servlet.http.Part;

  23. import org.apache.avalon.framework.service.ServiceException;
  24. import org.apache.fulcrum.parser.ValueParser.URLCaseFolding;

  25. /**
  26.  * ParserService defines the methods which are needed by the parser objects
  27.  * to get their necessities.
  28.  *
  29.  * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
  30.  * @version $Id: ValueParser.java 535465 2007-05-05 06:58:06Z tv $
  31.  */
  32. public interface ParserService
  33. {
  34.     /** Avalon Identifier **/
  35.     String ROLE = ParserService.class.getName();

  36.     /** Default Encoding for Parameter Parser */
  37.     String PARAMETER_ENCODING_DEFAULT = "ISO-8859-1";

  38.     /** Key for the Parameter Parser Encoding */
  39.     String PARAMETER_ENCODING_KEY = "parameterEncoding";

  40.     /** Property for setting the URL folding value */
  41.     String URL_CASE_FOLDING_KEY = "urlCaseFolding";

  42.     /** Parse file upload items automatically */
  43.     String AUTOMATIC_KEY = "automaticUpload";
  44.    
  45.     /** fulcrum pool by default false */
  46.     boolean FULCRUM_POOL_DEFAULT = false;
  47.    
  48.     /** fulcrum pool activation parameter */
  49.     String FULCRUM_POOL_KEY = "fulcrumPool";
  50.    
  51.     /** commons pool2 parameters */
  52.     String POOL_KEY = "pool2";

  53.     /**
  54.      * <p> The default value of 'automaticUpload' property
  55.      * (<code>false</code>).  If set to <code>true</code>, parsing the
  56.      * multipart request will be performed automatically by {@link
  57.      * org.apache.fulcrum.parser.ParameterParser}.  Otherwise, an
  58.      * org.apache.turbine.modules.Action may decide to parse the
  59.      * request by calling {@link #parseUpload(HttpServletRequest)
  60.      * parseRequest} manually.
  61.      */
  62.     boolean AUTOMATIC_DEFAULT = false;
  63.    
  64.     /**
  65.      * <p> The default value of 'maxTotal' property in 'pool'
  66.      * (<code>1024</code>). The default pool capacity.
  67.      */
  68.     int DEFAULT_POOL_CAPACITY = 1024;
  69.    
  70.     /**
  71.      * <p> The default value of 'maxIdle' property in 'pool'
  72.      * (<code>2</code>). The default maximum idle object.
  73.      */
  74.     int DEFAULT_MAX_IDLE = 2;

  75.     /**
  76.      * Get the parameter encoding that has been configured as default for
  77.      * the ParserService.
  78.      *
  79.      * @return A String for the parameter encoding
  80.      */
  81.     String getParameterEncoding();

  82.     /**
  83.      * Trims the string data and applies the conversion specified in
  84.      * the property given by URL_CASE_FOLDING. It returns a new
  85.      * string so that it does not destroy the value data.
  86.      *
  87.      * @param value A String to be processed.
  88.      * @return A new String converted to lowercase and trimmed.
  89.      */
  90.     String convert(String value);

  91.     /**
  92.      * Convert a String value according to the url-case-folding property.
  93.      *
  94.      * @param value the String to convert
  95.      * @return a new String.
  96.      *
  97.      */
  98.     String convertAndTrim(String value);

  99.     /**
  100.      * A convert method, which trims the string data and applies the
  101.      * conversion specified in the parameter given. It returns a new
  102.      * string so that it does not destroy the value data.
  103.      *
  104.      * @param value A String to be processed.
  105.      * @param fold The parameter folding to be applied
  106.      * (see {@link ParserService})
  107.      * @return A new String converted to the correct case and trimmed.
  108.      */
  109.     String convertAndTrim(String value, URLCaseFolding fold);

  110.     /**
  111.      * Gets the folding value from the configuration
  112.      *
  113.      * @return The current Folding Value
  114.      */
  115.     URLCaseFolding getUrlFolding();

  116.     /**
  117.      * Gets the automaticUpload value from the configuration
  118.      *
  119.      * @return The current automaticUpload Value
  120.      */
  121.     boolean getAutomaticUpload();

  122.     /**
  123.      * Parse the given request for uploaded files
  124.      *
  125.      * @param request the HttpServletRequest object
  126.      * @return A list of {@link javax.servlet.http.Part}s
  127.      * @throws ServiceException if parsing fails
  128.      */
  129.     List<Part> parseUpload(HttpServletRequest request) throws ServiceException;

  130.     /**
  131.      * Get a {@link ValueParser} instance from the service. Use the
  132.      * default implementation.
  133.      *
  134.      * @param <P> The ValueParser we are using
  135.      * @param ppClass parameter parser class
  136.      * @return An object that implements ValueParser
  137.      * @throws InstantiationException if the instance could not be created
  138.      */
  139.     <P extends ValueParser> P getParser(Class<P> ppClass) throws InstantiationException;

  140.     /**
  141.      * Put the parser into service
  142.      *
  143.      * @param parser The value parser to be used
  144.      */
  145.     void putParser(ValueParser parser);
  146. }