JavaDoc updates for parser
git-svn-id: https://svn.apache.org/repos/asf/turbine/fulcrum/trunk/parser@1844836 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/java/org/apache/fulcrum/parser/BaseValueParser.java b/src/java/org/apache/fulcrum/parser/BaseValueParser.java
index 77aa124..9b62124 100644
--- a/src/java/org/apache/fulcrum/parser/BaseValueParser.java
+++ b/src/java/org/apache/fulcrum/parser/BaseValueParser.java
@@ -82,10 +82,10 @@
private Logger logger;
/** String values which would evaluate to Boolean.TRUE */
- private static String[] trueValues = {"TRUE","T","YES","Y","1","ON"};
+ private static final String[] trueValues = {"TRUE","T","YES","Y","1","ON"};
/** String values which would evaluate to Boolean.FALSE */
- private static String[] falseValues = {"FALSE","F","NO","N","0","OFF"};
+ private static final String[] falseValues = {"FALSE","F","NO","N","0","OFF"};
/**
* The character encoding to use when converting to byte arrays
@@ -113,6 +113,8 @@
/**
* Constructor that takes a character encoding
+ *
+ * @param characterEncoding desired character encoding
*/
public BaseValueParser(String characterEncoding)
{
@@ -121,6 +123,9 @@
/**
* Constructor that takes a character encoding and a locale
+ *
+ * @param characterEncoding Sets the character encoding
+ * @param locale Sets the locale
*/
public BaseValueParser(String characterEncoding, Locale locale)
{
@@ -131,6 +136,8 @@
/**
* Set a ParserService instance
+ *
+ * @param parserService The parser service instance
*/
@Override
public void setParserService(ParserService parserService)
@@ -140,6 +147,7 @@
/**
* @see org.apache.avalon.framework.logger.LogEnabled#enableLogging(org.apache.avalon.framework.logger.Logger)
+ * @param logger The logger to be used
*/
@Override
public void enableLogging(Logger logger)
@@ -1151,7 +1159,7 @@
*
* @param name A String with the name.
* @return A byte[].
- * @exception UnsupportedEncodingException
+ * @throws UnsupportedEncodingException Generic exception
*/
@Override
public byte[] getBytes(String name)
diff --git a/src/java/org/apache/fulcrum/parser/CookieParser.java b/src/java/org/apache/fulcrum/parser/CookieParser.java
index ff1a90c..1420e0e 100644
--- a/src/java/org/apache/fulcrum/parser/CookieParser.java
+++ b/src/java/org/apache/fulcrum/parser/CookieParser.java
@@ -78,17 +78,26 @@
/**
* Set a cookie that will be stored on the client for
* the duration of the session.
+ *
+ * @param name The name of the cookie
+ * @param value The value of the cooking
*/
void set (String name, String value);
/**
- * Set a persisten cookie on the client that will expire
+ * Set a persistent cookie on the client that will expire
* after a maximum age (given in seconds).
+ *
+ * @param name A String for the name
+ * @param value A String for the value
+ * @param seconds_age An int for the age in seconds
*/
void set (String name, String value, int seconds_age);
/**
* Remove a previously set cookie from the client machine.
+ *
+ * @param name the name of the cooking to unset
*/
void unset (String name);
}
diff --git a/src/java/org/apache/fulcrum/parser/DataStreamParser.java b/src/java/org/apache/fulcrum/parser/DataStreamParser.java
index 38040fc..2bc19d9 100644
--- a/src/java/org/apache/fulcrum/parser/DataStreamParser.java
+++ b/src/java/org/apache/fulcrum/parser/DataStreamParser.java
@@ -126,6 +126,8 @@
* Initialize the StreamTokenizer instance used to read the lines
* from the input reader. This must be implemented in subclasses to
* set up the tokenizing properties.
+ *
+ * @param tokenizer the StreamTokenizer to use
*/
protected abstract void initTokenizer(StreamTokenizer tokenizer);
diff --git a/src/java/org/apache/fulcrum/parser/DefaultParserService.java b/src/java/org/apache/fulcrum/parser/DefaultParserService.java
index ff7a542..fdfeecc 100644
--- a/src/java/org/apache/fulcrum/parser/DefaultParserService.java
+++ b/src/java/org/apache/fulcrum/parser/DefaultParserService.java
@@ -237,10 +237,11 @@
}
/**
- * Return a used Parser to the service. This allows for
- * pooling and recycling
+ * Clears the parse and puts it back into
+ * the pool service. This allows for pooling
+ * and recycling
*
- * @param parser
+ * @param parser The value parser to use
*/
@Override
public void putParser(ValueParser parser)
@@ -251,6 +252,9 @@
/**
* Avalon component lifecycle method
+ *
+ * @param conf the configuration
+ * @throws ConfigurationException Generic exception
*/
@Override
public void configure(Configuration conf) throws ConfigurationException
@@ -284,6 +288,10 @@
// ---------------- Avalon Lifecycle Methods ---------------------
/**
* Avalon component lifecycle method
+ *
+ * @param manager The service manager instance
+ * @throws ServiceException generic exception
+ *
*/
@Override
public void service(ServiceManager manager) throws ServiceException
diff --git a/src/java/org/apache/fulcrum/parser/ParameterParser.java b/src/java/org/apache/fulcrum/parser/ParameterParser.java
index c55edfc..7c4c193 100644
--- a/src/java/org/apache/fulcrum/parser/ParameterParser.java
+++ b/src/java/org/apache/fulcrum/parser/ParameterParser.java
@@ -125,14 +125,14 @@
* exist or the object stored is not a Part
* array, return an empty list.
- * @return Collection<Part>
+ * @return Collection Collection of parts
*/
Collection<Part> getParts();
/**
* Convenience fileName utility, which extracts the filename from header
*
- *
+ * @param part The part which represents the uploaded file
* @return the fileName String object.
*/
String getFileName(Part part);
diff --git a/src/java/org/apache/fulcrum/parser/ParserService.java b/src/java/org/apache/fulcrum/parser/ParserService.java
index 06c2ca0..9f7eac1 100644
--- a/src/java/org/apache/fulcrum/parser/ParserService.java
+++ b/src/java/org/apache/fulcrum/parser/ParserService.java
@@ -55,8 +55,8 @@
* <p> The default value of 'automaticUpload' property
* (<code>false</code>). If set to <code>true</code>, parsing the
* multipart request will be performed automatically by {@link
- * org.apache.fulcrum.parser.ParameterParser}. Otherwise, an {@link
- * org.apache.turbine.modules.Action} may decide to parse the
+ * org.apache.fulcrum.parser.ParameterParser}. Otherwise, an
+ * org.apache.turbine.modules.Action may decide to parse the
* request by calling {@link #parseUpload(HttpServletRequest)
* parseRequest} manually.
*/
@@ -65,6 +65,8 @@
/**
* Get the parameter encoding that has been configured as default for
* the ParserService.
+ *
+ * @return A String for the parameter encoding
*/
String getParameterEncoding();
@@ -82,7 +84,6 @@
* Convert a String value according to the url-case-folding property.
*
* @param value the String to convert
- *
* @return a new String.
*
*/
@@ -117,8 +118,8 @@
/**
* Parse the given request for uploaded files
*
+ * @param request the HttpServletRequest object
* @return A list of {@link javax.servlet.http.Part}s
- *
* @throws ServiceException if parsing fails
*/
List<Part> parseUpload(HttpServletRequest request) throws ServiceException;
@@ -127,17 +128,17 @@
* Get a {@link ValueParser} instance from the service. Use the
* default implementation.
*
+ * @param <P> the parser class representation
+ * @param ppClass ...JavaDoc weirdness...
* @return An object that implements ValueParser
- *
* @throws InstantiationException if the instance could not be created
*/
<P extends ValueParser> P getParser(Class<P> ppClass) throws InstantiationException;
/**
- * Return a used Parser to the service. This allows for
- * pooling and recycling
+ * Put the parser into service
*
- * @param parser
+ * @param parser The value parser to be used
*/
void putParser(ValueParser parser);
}
diff --git a/src/java/org/apache/fulcrum/parser/ParserServiceSupport.java b/src/java/org/apache/fulcrum/parser/ParserServiceSupport.java
index d83ad20..b22e1fa 100644
--- a/src/java/org/apache/fulcrum/parser/ParserServiceSupport.java
+++ b/src/java/org/apache/fulcrum/parser/ParserServiceSupport.java
@@ -31,6 +31,8 @@
{
/**
* Set a ParserService instance
+ *
+ * @param parserService the service to be used
*/
void setParserService(ParserService parserService);
}
diff --git a/src/java/org/apache/fulcrum/parser/TSVParser.java b/src/java/org/apache/fulcrum/parser/TSVParser.java
index a95304d..46d7843 100644
--- a/src/java/org/apache/fulcrum/parser/TSVParser.java
+++ b/src/java/org/apache/fulcrum/parser/TSVParser.java
@@ -93,6 +93,8 @@
/**
* Initialize the StreamTokenizer instance used to read the lines
* from the input reader.
+ *
+ * @param tokenizer the stream tokenizer to be used
*/
protected void initTokenizer(StreamTokenizer tokenizer)
{
diff --git a/src/java/org/apache/fulcrum/parser/ValueParser.java b/src/java/org/apache/fulcrum/parser/ValueParser.java
index 33fe869..5011d76 100644
--- a/src/java/org/apache/fulcrum/parser/ValueParser.java
+++ b/src/java/org/apache/fulcrum/parser/ValueParser.java
@@ -75,41 +75,57 @@
/**
* Set the character encoding that will be used by this ValueParser.
+ *
+ * @param characterEncoding the character encoding to use
*/
- void setCharacterEncoding(String s);
+ void setCharacterEncoding(String characterEncoding);
/**
* Get the character encoding that will be used by this ValueParser.
+ *
+ * @return Current character encoding
*/
String getCharacterEncoding();
/**
* Set the locale that will be used by this ValueParser.
+ *
+ * @param locale the default locale to be used by the parser
*/
- void setLocale(Locale l);
+ void setLocale(Locale locale);
/**
* Get the locale that will be used by this ValueParser.
+ *
+ * @return Locale the locale being used
*/
Locale getLocale();
/**
* Set the date format that will be used by this ValueParser.
+ *
+ * @param dateFormat the date format
*/
- void setDateFormat(DateFormat df);
+ void setDateFormat(DateFormat dateFormat);
/**
* Get the date format that will be used by this ValueParser.
+ *
+ * @return DateFormat current date format used by this ValueParser
*/
DateFormat getDateFormat();
/**
* Set the number format that will be used by this ValueParser.
+ *
+ * @param numberFormat the number format to use
*/
- void setNumberFormat(NumberFormat nf);
+ void setNumberFormat(NumberFormat numberFormat);
/**
* Get the number format that will be used by this ValueParser.
+ *
+ * @return NumberFormat the current number format
*/
NumberFormat getNumberFormat();
@@ -178,6 +194,7 @@
* contained <code>Hashtable.remove()</code>.
*
*
+ * @param name the name of the mapped value to remove
* @return The value that was mapped to the key (a <code>String[]</code>)
* or <code>null</code> if the key was not mapped.
*/
@@ -251,6 +268,7 @@
* The string is compared without regard to case.
*
* @param name A String with the name.
+ * @param defaultValue boolean default if not found
* @return A Boolean.
*/
Boolean getBooleanObject(String name, Boolean defaultValue);
@@ -551,7 +569,7 @@
*
* @param name A String with the name.
* @return A byte[].
- * @exception UnsupportedEncodingException
+ * @throws UnsupportedEncodingException Generic exception
*/
byte[] getBytes(String name) throws UnsupportedEncodingException;
@@ -733,6 +751,7 @@
* string so that it does not destroy the value data.
*
* @param value A String to be processed.
+ * @param folding the type of URL case folding to be used
* @return A new String converted and trimmed.
*/
String convertAndTrim(String value, URLCaseFolding folding);