xdocs/index.xml - turbine-fulcrum-parser - Git at Google

 <?xml version="1.0"?>
 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>

   <properties>
     <title>Parser Component</title>
     <author email="epugh@opensourceconnections.com">Eric Pugh</author>
   </properties>

   <body>

   <section name="Overview">
     <p>
       This Service functions as a repository for Parser components.
     </p>

     <p>
       It is written
       for use in Turbine but it can be used in any container compatible
       with Avalon's ECM container.
     </p>

   </section>

 <section name="Configuration">
     <subsection name="Role Configuration">
       <source><![CDATA[
 <role
     name="org.apache.fulcrum.parser.ParserService"
     shorthand="parser"
     default-class="org.apache.fulcrum.parser.DefaultParserService"/>
 ]]></source>
     </subsection>

     <subsection name="Component Configuration">
       <table>
         <tr>
           <th>Item</th>
           <th>Datatype</th>
           <th>Cardinality</th>
           <th>Description</th>
         </tr>
         <tr>
           <td>urlCaseFolding</td>
           <td>String</td>
           <td>[0|1]</td>
           <td>
             This setting controls how parameter names are to be folded during
             processing. Valid values are <code>none</code> (no folding),
             <code>upper</code> (all names upper case) and <code>lower</code>
             (all names lower case). The default is <code>none</code>.
           </td>
         </tr>
         <tr>
           <td>parameterEncoding</td>
           <td>String</td>
           <td>[0|1]</td>
           <td>
             The parameter encoding to use when converting strings to bytes or
             vice versa. This encoding is used when no explicit encoding is specified.
             This must be a valid encoding string for the JVM in use. The default is
             <code>iso-8859-1</code>.
           </td>
         </tr>
         <tr>
           <td>automaticUpload</td>
           <td>boolean</td>
           <td>[0|1]</td>
           <td>
             If set to <code>true</code>, parsing the multipart request for attachments
             will be performed automatically. Otherwise, the request may be parsed manually
             by calling <code>parseUpload(HttpServletRequest)</code>. The default value is
             <code>false</code>. When set to true, the component must have the
             <a href="http://turbine.apache.org/fulcrum/fulcrum-upload/">Fulcrum Upload Service</a>
             available to parse the request.
           </td>
         </tr>
         <tr>
           <td>pool2</td>
           <td>list</td>
           <td>*</td>
           <td>
             Wrapper for commons pool2 parameters (child components) <code>maxTotal</code>with value -1 =no limit, other plausible values 1024, 2048.
             <code>blockWhenExhausted</code> (by default <code>true</code>), <code>maxWaitMillis</code> by default <code>0</code>, <code>testOnBorrow</code>, <code>testOnCreate</code>, <code>testOnReturn</code>,<code>maxIdle</code> and <code>minIdle</code>.
             The parameter values are the same as for commons.pool2,
             compare the defaults (upper case and underscore-separated)
             <a href="
             https://commons.apache.org/proper/commons-pool/apidocs/index.html">here </a>
             look for org.apache.commons.pool2.impl.BaseObjectPoolConfig and BaseGenericObjectPool.
           </td>
         </tr>
       </table>
     </subsection>

     <subsection name="Component Configuration Example">
       <source><![CDATA[
 <parser>
     <urlCaseFolding>lower</urlCaseFolding>
     <parameterEncoding>utf-8</parameterEncoding>
     <automaticUpload>true</automaticUpload>
     <pool2>
          <maxTotal>2048</maxTotal><!-- default 8 -->
          <blockWhenExhausted>true</blockWhenExhausted><!-- default is true -->
          <maxWaitMillis>350</maxWaitMillis><!--  default is -1L -->
     </pool2>
 </parser>
 ]]></source>
     </subsection>

   </section>

   <section name="Usage">
     <p>
     You get a parser from the service like this:
     </p>

     <source><![CDATA[
 ValueParser parser;

 try
 {
     // Get a ValueParser instance
     parser = parserService.getParser(BaseValueParser.class);

     parser.add(...);
     Double d = parser.getDoubleObject(...);
 }
 finally
 {
     // Return the instance to the service
     if (parser != null)
     {
         parserService.putParser(parser);
     }
 }
 ]]></source>


     <p>
     Parsers are pooled inside the service. You can use this service to manage any types of
     parsers, you just need to provide the class you want to manage. If the parser class
     implements LogEnabled it will get an (Avalon) logger injected. If the parser class
     implements ParserServiceSupport it will get an instance of this service injected.
     </p>

   </section>

 </body>
 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>

	<properties>
	<title>Parser Component</title>
	<author email="epugh@opensourceconnections.com">Eric Pugh</author>
	</properties>

	<body>

	<section name="Overview">
	<p>
	This Service functions as a repository for Parser components.
	</p>

	<p>
	It is written
	for use in Turbine but it can be used in any container compatible
	with Avalon's ECM container.
	</p>

	</section>

	<section name="Configuration">
	<subsection name="Role Configuration">
	<source><![CDATA[
	<role
	name="org.apache.fulcrum.parser.ParserService"
	shorthand="parser"
	default-class="org.apache.fulcrum.parser.DefaultParserService"/>
	]]></source>
	</subsection>

	<subsection name="Component Configuration">
	<table>
	<tr>
	<th>Item</th>
	<th>Datatype</th>
	<th>Cardinality</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>urlCaseFolding</td>
	<td>String</td>
	<td>[0\|1]</td>
	<td>
	This setting controls how parameter names are to be folded during
	processing. Valid values are <code>none</code> (no folding),
	<code>upper</code> (all names upper case) and <code>lower</code>
	(all names lower case). The default is <code>none</code>.
	</td>
	</tr>
	<tr>
	<td>parameterEncoding</td>
	<td>String</td>
	<td>[0\|1]</td>
	<td>
	The parameter encoding to use when converting strings to bytes or
	vice versa. This encoding is used when no explicit encoding is specified.
	This must be a valid encoding string for the JVM in use. The default is
	<code>iso-8859-1</code>.
	</td>
	</tr>
	<tr>
	<td>automaticUpload</td>
	<td>boolean</td>
	<td>[0\|1]</td>
	<td>
	If set to <code>true</code>, parsing the multipart request for attachments
	will be performed automatically. Otherwise, the request may be parsed manually
	by calling <code>parseUpload(HttpServletRequest)</code>. The default value is
	<code>false</code>. When set to true, the component must have the
	<a href="http://turbine.apache.org/fulcrum/fulcrum-upload/">Fulcrum Upload Service</a>
	available to parse the request.
	</td>
	</tr>
	<tr>
	<td>pool2</td>
	<td>list</td>
	<td>*</td>
	<td>
	Wrapper for commons pool2 parameters (child components) <code>maxTotal</code>with value -1 =no limit, other plausible values 1024, 2048.
	<code>blockWhenExhausted</code> (by default <code>true</code>), <code>maxWaitMillis</code> by default <code>0</code>, <code>testOnBorrow</code>, <code>testOnCreate</code>, <code>testOnReturn</code>,<code>maxIdle</code> and <code>minIdle</code>.
	The parameter values are the same as for commons.pool2,
	compare the defaults (upper case and underscore-separated)
	<a href="
	https://commons.apache.org/proper/commons-pool/apidocs/index.html">here </a>
	look for org.apache.commons.pool2.impl.BaseObjectPoolConfig and BaseGenericObjectPool.
	</td>
	</tr>
	</table>
	</subsection>

	<subsection name="Component Configuration Example">
	<source><![CDATA[
	<parser>
	<urlCaseFolding>lower</urlCaseFolding>
	<parameterEncoding>utf-8</parameterEncoding>
	<automaticUpload>true</automaticUpload>
	<pool2>
	<maxTotal>2048</maxTotal><!-- default 8 -->
	<blockWhenExhausted>true</blockWhenExhausted><!-- default is true -->
	<maxWaitMillis>350</maxWaitMillis><!-- default is -1L -->
	</pool2>
	</parser>
	]]></source>
	</subsection>

	</section>

	<section name="Usage">
	<p>
	You get a parser from the service like this:
	</p>

	<source><![CDATA[
	ValueParser parser;

	try
	{
	// Get a ValueParser instance
	parser = parserService.getParser(BaseValueParser.class);

	parser.add(...);
	Double d = parser.getDoubleObject(...);
	}
	finally
	{
	// Return the instance to the service
	if (parser != null)
	{
	parserService.putParser(parser);
	}
	}
	]]></source>


	<p>
	Parsers are pooled inside the service. You can use this service to manage any types of
	parsers, you just need to provide the class you want to manage. If the parser class
	implements LogEnabled it will get an (Avalon) logger injected. If the parser class
	implements ParserServiceSupport it will get an instance of this service injected.
	</p>

	</section>

	</body>
	</document>