You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/03/19 20:31:38 UTC
[commons-validator] 04/04: Javadoc: Convert package.html to package-info.java
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-validator.git
commit 7ac02e5369d7b2437e4a7790a21063245dc3de5f
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Mar 19 16:31:30 2023 -0400
Javadoc: Convert package.html to package-info.java
---
.../org/apache/commons/validator/package-info.java | 223 +++++++++++++++++++
.../java/org/apache/commons/validator/package.html | 244 ---------------------
2 files changed, 223 insertions(+), 244 deletions(-)
diff --git a/src/main/java/org/apache/commons/validator/package-info.java b/src/main/java/org/apache/commons/validator/package-info.java
new file mode 100644
index 00000000..d8d7a990
--- /dev/null
+++ b/src/main/java/org/apache/commons/validator/package-info.java
@@ -0,0 +1,223 @@
+/*
+ * 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.
+ */
+
+/**
+ * The Validator package provides validation for JavaBeans based on an xml file.
+ *
+ * <a id="doc.Description"></a>
+ * <div>
+ * <a href="http://commons.apache.org/validator/dependencies.html">[Dependencies]</a>
+ * <a href="#doc.Intro">[Introduction]</a>
+ * <a href="#doc.Overview">[Overview]</a>
+ * <a href="#doc.Resources">[Resources]</a>
+ * <a href="#doc.Usage">[Usage Example]</a>
+ * </div>
+ * <a id="doc.Intro"></a>
+ * <h2>Introduction</h2>
+ * <p>A common issue when receiving data either electronically or from
+ * user input is verifying the integrity of the data. This work is
+ * repetitive and becomes even more complicated when different sets
+ * of validation rules need to be applied to the same set of data based
+ * on locale for example. Error messages may also vary by locale.
+ * This package attempts to address some of these issues and
+ * speed development and maintenance of validation rules.
+ * </p>
+ * <p>In order to use the Validator, the following basic steps are required:</p>
+ * <ul>
+ * <li>Create a new instance of the
+ * <code>org.apache.commons.validator.Validator</code> class. Currently
+ * Validator instances may be safely reused if the current ValidatorResources
+ * are the same, as long as
+ * you have completed any previous validation, and you do not try to utilize
+ * a particular Validator instance from more than one thread at a time.</li>
+ * <li>Add any <a href="#doc.Resources">resources</a>
+ * needed to perform the validations. Such as the JavaBean to validate.</li>
+ * <li>Call the validate method on <code>org.apache.commons.validator.Validator</code>.</li>
+ * </ul>
+ * <a id="doc.Overview"></a>
+ * <h2>Overview</h2>
+ * <p>
+ * The Commons Validator is a basic validation framework that
+ * lets you define validation rules for a JavaBean in an xml file.
+ * Validators, the validation definition, can also be defined in
+ * the xml file. An example of a validator would be defining
+ * what method and class will be called to perform the validation
+ * for a required field. Validation rules can be grouped together
+ * based on locale and a JavaBean/Form that the rules are associated
+ * with. The framework has basic support for user defined constants
+ * which can be used in some field attributes.
+ * </p>
+ * <p>
+ * Validation rules can be defined in an xml file which keeps
+ * them abstracted from JavaBean you are validating. The
+ * property reference to a field supports nested properties
+ * using the Apache Commons BeanUtils
+ * (http://commons.apache.org/beanutils/) package.
+ * Error messages and the arguments for error messages can be
+ * associated with a fields validation.
+ * </p>
+ * <a id="doc.Resources"></a>
+ * <h2>Resources</h2>
+ * <p>
+ * After a Validator instance is created, instances of
+ * classes can be added to it to be passed into
+ * validation methods by calling the setParameter()
+ * method. Below is a list of reserved parameters (class names).
+ * </p>
+ * <table border="1">
+ * <caption>Reserved Parameters</caption>
+ * <tr>
+ * <th>Class Name</th>
+ * <th>Validator Contstant</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>java.lang.Object</td>
+ * <td>Validator.BEAN_PARAM</td>
+ * <td>JavaBean that is being validated</td>
+ * </tr>
+ * <tr>
+ * <td>java.util.Locale</td>
+ * <td>Validator.LOCALE_PARAM</td>
+ * <td>
+ * Locale to use when retrieving a FormSet.
+ * The default locale will be used if one
+ * isn't specified.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>org.apache.commons.validator.ValidatorAction</td>
+ * <td>Validator.VALIDATOR_ACTION_PARAM</td>
+ * <td>
+ * This is automatically added to a Validator's
+ * resources as a validation is being processed.
+ * If this class name is used when defining
+ * a method signature for a pluggable validator,
+ * the current ValidatorAction will be passed into
+ * the validation method.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>org.apache.commons.validator.Field</td>
+ * <td>Validator.FIELD_PARAM</td>
+ * <td>
+ * This is automatically added to a Validator's
+ * resources as a validation is being processed.
+ * If this class name is used when defining
+ * a method signature for a pluggable validator,
+ * the current Field will be passed into
+ * the validation method.
+ * </td>
+ * </tr>
+ * </table>
+ * <a id="doc.Usage"></a>
+ * <h2>Usage Example</h2>
+ * <p>
+ * This is a basic example setting up a required validator for
+ * a name bean. This example is a working unit test (reference
+ * <code>org.apache.commons.validator.RequiredNameTest</code> and
+ * validator-name-required.xml located under validator/src/test).
+ * </p>
+ * <p>
+ * Create an xml file with your validator and validation rules.
+ * Setup your required validator in your xml file.<br>
+ * <br>
+ * <a href="#doc.Usage.xml">XML Example</a><br>
+ * <a href="#doc.Usage.validator">Validator Example</a><br>
+ * <a href="#doc.Usage.pluggableValidator">Pluggable Validator Example</a>
+ * </p>
+ * <a id="doc.Usage.xml"></a>
+ * <h2>XML Example</h2>
+ * <p>
+ * Definition of a 'required' pluggable validator.<br>
+ * <pre>
+ * <form-validation>
+ * <global>
+ * <validator name="required"
+ * classname="org.apache.commons.validator.TestValidator"
+ * method="validateRequired"
+ * methodParams="java.lang.Object, org.apache.commons.validator.Field"/>
+ * </global>
+ * <formset>
+ * </formset>
+ * </form-validation>
+ * </pre>
+ * <p>
+ * Add validation rules to require a first name and a last name.<br>
+ * <pre>
+ * <form-validation>
+ * <global>
+ * <validator name="required"
+ * classname="org.apache.commons.validator.TestValidator"
+ * method="validateRequired"
+ * methodParams="java.lang.Object, org.apache.commons.validator.Field"/>
+ * </global>
+ * <b>
+ * <formset>
+ * <form name="nameForm">
+ * <field property="firstName" depends="required">
+ * <arg0 key="nameForm.firstname.displayname"/>
+ * </field>
+ * <field property="lastName" depends="required">
+ * <arg0 key="nameForm.lastname.displayname"/>
+ * </field>
+ * </form>
+ * </formset>
+ * </b>
+ * </form-validation>
+ * </pre>
+ * <a id="doc.Usage.validator"></a>
+ * <h2>Validator Example</h2>
+ * <p>
+ * Excerpts from org.apache.commons.validator.RequiredNameTest
+ * </p>
+ * <pre>
+ * InputStream in = this.getClass().getResourceAsStream("validator-name-required.xml");
+ * // Create an instance of ValidatorResources to initialize from an xml file.
+ * ValidatorResources resources = new ValidatorResources(in);
+ * // Create bean to run test on.
+ * Name name = new Name();
+ * // Construct validator based on the loaded resources and the form key
+ * Validator validator = new Validator(resources, "nameForm");
+ * // add the name bean to the validator as a resource
+ * // for the validations to be performed on.
+ * validator.setParameter(Validator.BEAN_PARAM, name);
+ * // Get results of the validation.
+ * Map results;
+ * // throws ValidatorException (catch clause not shown here)
+ * results = validator.validate();
+ * if (results.get("firstName") == null) {
+ * // no error
+ * } else {
+ * // number of errors for first name
+ * int errors = ((Integer)results.get("firstName")).intValue();
+ * }
+ * </pre>
+ * <a id="doc.Usage.pluggableValidator"></a>
+ * <h2>Pluggable Validator Example</h2>
+ * <p>
+ * Validation method defined in the 'required' pluggable validator
+ * (excerpt from org.apache.commons.validator.TestValidator).
+ * </p>
+ * <pre>
+ * public static boolean validateRequired(Object bean, Field field) {
+ * String value = ValidatorUtil.getValueAsString(bean, field.getProperty());
+ * return GenericValidator.isBlankOrNull(value);
+ * }
+ * </pre>
+ */
+package org.apache.commons.validator;
diff --git a/src/main/java/org/apache/commons/validator/package.html b/src/main/java/org/apache/commons/validator/package.html
deleted file mode 100644
index 5f6647b8..00000000
--- a/src/main/java/org/apache/commons/validator/package.html
+++ /dev/null
@@ -1,244 +0,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.
--->
-<html>
-<head>
- <title>Package Documentation for org.apache.commons.validator</title>
-</head>
-<body bgcolor="white">
-The Validator package provides validation for JavaBeans based on an xml file.
-<br><br>
-<a id="doc.Description"></a>
-<div>
-<a href="http://commons.apache.org/validator/dependencies.html">[Dependencies]</a>
-<a href="#doc.Intro">[Introduction]</a>
-<a href="#doc.Overview">[Overview]</a>
-<a href="#doc.Resources">[Resources]</a>
-<a href="#doc.Usage">[Usage Example]</a>
-</div>
-
-<a id="doc.Intro"></a>
-<h2>Introduction</h2>
-
-<p>A common issue when receiving data either electronically or from
-user input is verifying the integrity of the data. This work is
-repetitive and becomes even more complicated when different sets
-of validation rules need to be applied to the same set of data based
-on locale for example. Error messages may also vary by locale.
-This package attempts to address some of these issues and
-speed development and maintenance of validation rules.
-</p>
-
-<p>In order to use the Validator, the following basic steps are required:</p>
-<ul>
- <li>Create a new instance of the
- <code>org.apache.commons.validator.Validator</code> class. Currently
- Validator instances may be safely reused if the current ValidatorResources
- are the same, as long as
- you have completed any previous validation, and you do not try to utilize
- a particular Validator instance from more than one thread at a time.</li>
- <li>Add any <a href="#doc.Resources">resources</a>
- needed to perform the validations. Such as the JavaBean to validate.</li>
- <li>Call the validate method on <code>org.apache.commons.validator.Validator</code>.</li>
-</ul>
-
-<a id="doc.Overview"></a>
-<h2>Overview</h2>
-<p>
- The Commons Validator is a basic validation framework that
- lets you define validation rules for a JavaBean in an xml file.
- Validators, the validation definition, can also be defined in
- the xml file. An example of a validator would be defining
- what method and class will be called to perform the validation
- for a required field. Validation rules can be grouped together
- based on locale and a JavaBean/Form that the rules are associated
- with. The framework has basic support for user defined constants
- which can be used in some field attributes.
-</p>
-<p>
- Validation rules can be defined in an xml file which keeps
- them abstracted from JavaBean you are validating. The
- property reference to a field supports nested properties
- using the Apache Commons BeanUtils
- (http://commons.apache.org/beanutils/) package.
- Error messages and the arguments for error messages can be
- associated with a fields validation.
-</p>
-
-<a id="doc.Resources"></a>
-<h2>Resources</h2>
-<p>
- After a Validator instance is created, instances of
- classes can be added to it to be passed into
- validation methods by calling the setParameter()
- method. Below is a list of reserved parameters (class names).
-</p>
-
-<table border="1">
- <caption>Reserved Parameters</caption>
- <tr>
- <th>Class Name</th>
- <th>Validator Contstant</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>java.lang.Object</td>
- <td>Validator.BEAN_PARAM</td>
- <td>JavaBean that is being validated</td>
- </tr>
- <tr>
- <td>java.util.Locale</td>
- <td>Validator.LOCALE_PARAM</td>
- <td>
- Locale to use when retrieving a FormSet.
- The default locale will be used if one
- isn't specified.
- </td>
- </tr>
- <tr>
- <td>org.apache.commons.validator.ValidatorAction</td>
- <td>Validator.VALIDATOR_ACTION_PARAM</td>
- <td>
- This is automatically added to a Validator's
- resources as a validation is being processed.
- If this class name is used when defining
- a method signature for a pluggable validator,
- the current ValidatorAction will be passed into
- the validation method.
- </td>
- </tr>
- <tr>
- <td>org.apache.commons.validator.Field</td>
- <td>Validator.FIELD_PARAM</td>
- <td>
- This is automatically added to a Validator's
- resources as a validation is being processed.
- If this class name is used when defining
- a method signature for a pluggable validator,
- the current Field will be passed into
- the validation method.
- </td>
- </tr>
-</table>
-
-
-<a id="doc.Usage"></a>
-<h2>Usage Example</h2>
-<p>
- This is a basic example setting up a required validator for
- a name bean. This example is a working unit test (reference
- <code>org.apache.commons.validator.RequiredNameTest</code> and
- validator-name-required.xml located under validator/src/test).
-</p>
-<p>
- Create an xml file with your validator and validation rules.
- Setup your required validator in your xml file.<br>
- <br>
- <a href="#doc.Usage.xml">XML Example</a><br>
- <a href="#doc.Usage.validator">Validator Example</a><br>
- <a href="#doc.Usage.pluggableValidator">Pluggable Validator Example</a>
-</p>
-
-<a id="doc.Usage.xml"></a>
-<h2>XML Example</h2>
-<p>
- Definition of a 'required' pluggable validator.<br>
-<pre>
-<form-validation>
- <global>
- <validator name="required"
- classname="org.apache.commons.validator.TestValidator"
- method="validateRequired"
- methodParams="java.lang.Object, org.apache.commons.validator.Field"/>
- </global>
- <formset>
- </formset>
-</form-validation>
-</pre>
-
-<p>
- Add validation rules to require a first name and a last name.<br>
-<pre>
-<form-validation>
- <global>
- <validator name="required"
- classname="org.apache.commons.validator.TestValidator"
- method="validateRequired"
- methodParams="java.lang.Object, org.apache.commons.validator.Field"/>
- </global>
-<b>
- <formset>
- <form name="nameForm">
- <field property="firstName" depends="required">
- <arg0 key="nameForm.firstname.displayname"/>
- </field>
- <field property="lastName" depends="required">
- <arg0 key="nameForm.lastname.displayname"/>
- </field>
- </form>
- </formset>
-</b>
-</form-validation>
-</pre>
-
-<a id="doc.Usage.validator"></a>
-<h2>Validator Example</h2>
-<p>
-Excerpts from org.apache.commons.validator.RequiredNameTest
-</p>
-<pre>
-InputStream in = this.getClass().getResourceAsStream("validator-name-required.xml");
-
-// Create an instance of ValidatorResources to initialize from an xml file.
-ValidatorResources resources = new ValidatorResources(in);
-// Create bean to run test on.
-Name name = new Name();
-
-// Construct validator based on the loaded resources and the form key
-Validator validator = new Validator(resources, "nameForm");
-// add the name bean to the validator as a resource
-// for the validations to be performed on.
-validator.setParameter(Validator.BEAN_PARAM, name);
-
-// Get results of the validation.
-Map results;
-
-// throws ValidatorException (catch clause not shown here)
-results = validator.validate();
-
-if (results.get("firstName") == null) {
- // no error
-} else {
- // number of errors for first name
- int errors = ((Integer)results.get("firstName")).intValue();
-}
-</pre>
-
-<a id="doc.Usage.pluggableValidator"></a>
-<h2>Pluggable Validator Example</h2>
-<p>
-Validation method defined in the 'required' pluggable validator
-(excerpt from org.apache.commons.validator.TestValidator).
-</p>
-
-<pre>
-public static boolean validateRequired(Object bean, Field field) {
- String value = ValidatorUtil.getValueAsString(bean, field.getProperty());
- return GenericValidator.isBlankOrNull(value);
-}
-</pre>
-</body>
-</html>