org.locomotive.loco
Class FormData

java.lang.Object
  |
  +--org.locomotive.loco.FormData

public class FormData
extends java.lang.Object

FormData combines the features of a Hashtable with a string-checker and a StringBuffer into one powerful class. FormData allows you to get the values of the fields in a form, check whether those values fit a specific format, and generate automatic error messages when those values do not fit the format. You do not need to create an instance of FormData, if you use the GenericRequest class. The constructor for GenericRequest automatically instantiates a local variable called form_data, which is an instance of FormData that has been filled out with the form values from the Web browser. There is extensive documentation about how to use the FormData class, in Chapter III of the Locomotive Developer's Guide. However, we will present a few examples here. In general, you can use the methods whose names start with get...() to retrieve the values of fields. For example:

     String username = form_data.getAlphanum ("LOGIN_USERNAME", "username", 2, 12, true);
 
In general, all the get...() methods have the same five arguments:
  1. The first argument is the actual name of the field in the form.
  2. the second argument is a "friendly" name, to be displayed to the user in an error message.
  3. the third argument is the minimum length that the field must be.
  4. the fourth argument is the maximum length that the field must be.
  5. you can use the fifth argument to tell this FormData object whether to generate an error code and an error message when there is an error.
If the field does not fit your formatting criteria, or it could not be found in the form, or it was empty, the FormData object will generate an error code and an error message. Then, unless you ignore or override this error, the error message will be added to an accumulation of all error messages. So, this object "keeps track" of the errors for you. These are the different error codes that are thrown (which are very similar to the error codes of org.locomotive.util.ParseStringException):
  1. If the field is not found in the form, the FormData object generates an error code of FormData.IS_NULL.
  2. if the field exists in the form, but it's just an empty string "", and the minimum length is not 0, then the FormData generates FormData.IS_EMPTY.
  3. if the field is shorter than the minimum length, the FormData generates FormData.TOO_SHORT.
  4. if it is longer than the maximum length, the FormData generates FormData.TOO_LONG.
  5. if the field does not fit the specific type you specified, for example, if you expected digits, and there were alphabetical letters in the field, then the FormData will generate FormData.DOESNT_FIT_TYPE.
  6. if the field is numeric, and the field is smaller than the lower bound which you specified, then the FormData will generate FormData.TOO_SMALL.
  7. however, if a numeric field is larger than the upper bound, then the FormData will generate FormData.TOO_LARGE.
In order to find out whether the last get...() generated one or more error codes, you call the method hasError(int your_error_code). In order to see the last error message that was generated for a particular error code, call the method lastErrorMsg(int your_error_code). Here's an example:
     boolean too_short = form_data.hasError(FormData.TOO_SHORT);
     String too_short_message = form_data.lastErrorMsg(FormData.TOO_SHORT);
 
You can override the error message that was generated for a particular error code during the last get...() method call, using setErrorMsg(...). Or, if you want to ignore an error code, use ignoreErrorCode(...). If you want to see the sum total of all error messages generated for all fields, use allErrorMsgs().


Field Summary
static int DOESNT_FIT_TYPE
           
static int IS_EMPTY
           
static int IS_NULL
           
static int NO_ERROR
           
static int TOO_LARGE
           
static int TOO_LONG
           
static int TOO_SHORT
           
static int TOO_SMALL
           
 
Constructor Summary
FormData(java.util.Hashtable form_hash)
          create a new FormData object, and initialize it with the values of the fields from the Hashtable, form_hash.
 
Method Summary
 java.lang.String allErrorMsgs()
          returns a String containing all the error messages generated while accessing all the fields in this form.
 boolean containsAll(java.lang.String[] names_of_all_fields)
          tells whether the form contains values for all of the fields mentioned.
 boolean containsAllNonEmpty(java.lang.String[] names_of_all_fields)
          tells whether the form contains non-empty values for all of the fields mentioned.
 void copyAllIntoSteam(java.util.Hashtable steam_variables)
          copies the values of all fields in this form to the Hashtable containing all the Steam variables, so that you can use the Steam variables to put in default values for the form fields in the HTML template.
 java.lang.String getAlphanum(java.lang.String field_name, java.lang.String name_to_display, int minimum_length, int maximum_length, boolean warn_non_alphanum)
          if this field contains non_alphanumerics, then they will be removed.
 java.util.Date getDate(java.lang.String field_name, java.lang.String name_to_display)
          tries to parse a field as a Date in one of the following formats: "MMM d, yyyy", "MM-d-yy", "MM-d-yyyy", "MM/d/yy", "MM/d/yyyy", "d.MM.yy", "d.MM.yyyy".
 java.util.Date getDate(java.lang.String month_field, java.lang.String day_field, java.lang.String year_field, java.lang.String name_to_display)
          tries to parse the three fields, month_field, day_field, and year_field, and create a Date out of them.
 java.lang.String getDigits(java.lang.String field_name, java.lang.String name_to_display, int minimum_length, int maximum_length, boolean warn_non_digits)
          if this field contains non-digits, then the non-digits will be removed.
 java.lang.String getEmailAddress(java.lang.String field_name, java.lang.String name_to_display, int minimum_length, int maximum_length)
          Will return the email address no matter what, even if it doesn't fit, but if there are errors, will give IS_NULL, IS_EMPTY, TOO_SHORT, TOO_LONG, and DOESNT_FIT_TYPE.
 java.lang.String getField(java.lang.String field_name)
          returns the value of the field named field_name.
 java.util.Hashtable getHashtable()
          returns the value of a Hashtable containing all fields in this form.
 int getInt(java.lang.String field_name, java.lang.String name_to_display)
          tries to read a field as an int.
 int getIntWithinBounds(java.lang.String field_name, java.lang.String name_to_display, int minimum, int maximum)
          tries to read a field as an int, bounded by a minimum and a maximum.
 java.lang.String getNonEmptyField(java.lang.String field_name, java.lang.String name_to_display)
          returns the value of the field named field_name.
 java.lang.String getNonNullField(java.lang.String field_name, java.lang.String name_to_display)
          returns the value of the field named field_name.
 java.lang.String getString(java.lang.String field_name, java.lang.String name_to_display, int minimum_length, int maximum_length)
          Returns the string field named field_name.
 java.lang.String getTrimmedString(java.lang.String field_name, java.lang.String name_to_display, int minimum_length, int maximum_length)
          This method trims the leading and trailing whitespace in a field, and returns its value.
 boolean hasAnyErrors()
          tells whether the last get...() method generated any errors of any kind.
 boolean hasError(int error_code)
          tells whether the last get...() method generated an error whose code matches error_code.
 void ignoreErrorCode(int error_code)
          allows you to ignore the error message associated with error_code in the last get...() method call.
 void ignoreErrors()
          allows you to ignore all the error messages in the last get...() method call.
 boolean isEmpty()
          tells whether the form is empty (contains no fields).
 java.lang.String lastErrorMsg(int error_code)
          if the last get...() method generated an error matching error_code, this method will return the error message.
 void setMsgForError(int error_code, java.lang.String error_msg)
          allows you to set the error message for a particular error code.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_ERROR

public static final int NO_ERROR

IS_NULL

public static final int IS_NULL

IS_EMPTY

public static final int IS_EMPTY

TOO_SHORT

public static final int TOO_SHORT

TOO_LONG

public static final int TOO_LONG

TOO_SMALL

public static final int TOO_SMALL

TOO_LARGE

public static final int TOO_LARGE

DOESNT_FIT_TYPE

public static final int DOESNT_FIT_TYPE
Constructor Detail

FormData

public FormData(java.util.Hashtable form_hash)
create a new FormData object, and initialize it with the values of the fields from the Hashtable, form_hash.
Method Detail

getField

public java.lang.String getField(java.lang.String field_name)
returns the value of the field named field_name. If the form does not contain this field, will return null. NOTE: this is the only method which returns the value of a field without generating any error codes or error messages.

getHashtable

public java.util.Hashtable getHashtable()
returns the value of a Hashtable containing all fields in this form. if the form is empty, will return a new Hashtable().

isEmpty

public boolean isEmpty()
tells whether the form is empty (contains no fields).

copyAllIntoSteam

public void copyAllIntoSteam(java.util.Hashtable steam_variables)
copies the values of all fields in this form to the Hashtable containing all the Steam variables, so that you can use the Steam variables to put in default values for the form fields in the HTML template.

containsAll

public boolean containsAll(java.lang.String[] names_of_all_fields)
tells whether the form contains values for all of the fields mentioned. Example:
     String[] required_fields = { "USERNAME", "USERID", ... };
     boolean is_good = my_form.containsAll(required_fields);
 

containsAllNonEmpty

public boolean containsAllNonEmpty(java.lang.String[] names_of_all_fields)
tells whether the form contains non-empty values for all of the fields mentioned.

getNonNullField

public java.lang.String getNonNullField(java.lang.String field_name,
                                        java.lang.String name_to_display)
returns the value of the field named field_name. if the form does not contain this field, will return an empty String, "", rather than null, and generate the error code IS_NULL.

getNonEmptyField

public java.lang.String getNonEmptyField(java.lang.String field_name,
                                         java.lang.String name_to_display)
returns the value of the field named field_name. if the form does not contain this field, or if the field is an empty string (""), will set the error code, IS_EMPTY, and store an error message, then return an empty string, "".

hasError

public boolean hasError(int error_code)
tells whether the last get...() method generated an error whose code matches error_code. Remember, it may have generated multiple error codes, so you can check each individual error code.

hasAnyErrors

public boolean hasAnyErrors()
tells whether the last get...() method generated any errors of any kind.

lastErrorMsg

public java.lang.String lastErrorMsg(int error_code)
if the last get...() method generated an error matching error_code, this method will return the error message. If there was no error, it will return "".

setMsgForError

public void setMsgForError(int error_code,
                           java.lang.String error_msg)
allows you to set the error message for a particular error code. However, if the last get...() method did not generate that error code, your error message will not be added to the accumulation of all error messages.

allErrorMsgs

public java.lang.String allErrorMsgs()
returns a String containing all the error messages generated while accessing all the fields in this form.

ignoreErrorCode

public void ignoreErrorCode(int error_code)
allows you to ignore the error message associated with error_code in the last get...() method call.

ignoreErrors

public void ignoreErrors()
allows you to ignore all the error messages in the last get...() method call.

getInt

public int getInt(java.lang.String field_name,
                  java.lang.String name_to_display)
tries to read a field as an int.
Parameters:
field_name - the name of the int field in the form.
name_to_display - the name to display in an error message to the user. May generate the errors IS_NULL, IS_EMPTY, and DOESNT_FIT_TYPE.

getIntWithinBounds

public int getIntWithinBounds(java.lang.String field_name,
                              java.lang.String name_to_display,
                              int minimum,
                              int maximum)
tries to read a field as an int, bounded by a minimum and a maximum.
Parameters:
field_name - the name of the int field in the form.
name_to_display - the name to display in an error message to the user.
minimum - the minimum this number can be.
maximum - the maximum this number can be. May generate the errors IS_NULL, IS_EMPTY, DOESNT_FIT_TYPE, TOO_SMALL, and TOO_LARGE.

getDigits

public java.lang.String getDigits(java.lang.String field_name,
                                  java.lang.String name_to_display,
                                  int minimum_length,
                                  int maximum_length,
                                  boolean warn_non_digits)
if this field contains non-digits, then the non-digits will be removed. Also, if it does contain non-digits, and warn_non_digits is true, then will generate an error code of DOESNT_FIT_TYPE.

getAlphanum

public java.lang.String getAlphanum(java.lang.String field_name,
                                    java.lang.String name_to_display,
                                    int minimum_length,
                                    int maximum_length,
                                    boolean warn_non_alphanum)
if this field contains non_alphanumerics, then they will be removed. also, if it does contain non_alphanumerics, and warn_non_alphanum is true, then will generate an error code of DOESNT_FIT_TYPE.

getString

public java.lang.String getString(java.lang.String field_name,
                                  java.lang.String name_to_display,
                                  int minimum_length,
                                  int maximum_length)
Returns the string field named field_name. Does NOT trim any leading or trailing whitespace in the field, unlike all the other methods. If it's null, too short, or too long, then this method will set the error code.

getTrimmedString

public java.lang.String getTrimmedString(java.lang.String field_name,
                                         java.lang.String name_to_display,
                                         int minimum_length,
                                         int maximum_length)
This method trims the leading and trailing whitespace in a field, and returns its value. It will NOT give an error if there is whitespace in the field.

getDate

public java.util.Date getDate(java.lang.String field_name,
                              java.lang.String name_to_display)
tries to parse a field as a Date in one of the following formats: "MMM d, yyyy", "MM-d-yy", "MM-d-yyyy", "MM/d/yy", "MM/d/yyyy", "d.MM.yy", "d.MM.yyyy". Will generate DOESNT_FIT_TYPE if it could not parse the field as a Date, and then return null. This method uses the StringUtil.getDate() method.

getDate

public java.util.Date getDate(java.lang.String month_field,
                              java.lang.String day_field,
                              java.lang.String year_field,
                              java.lang.String name_to_display)
tries to parse the three fields, month_field, day_field, and year_field, and create a Date out of them. The month_field argument can be either a number from 1-12 or at least the first three letters of the name of a month, upper or lower case. This method uses the StringUtil.getDate() method. It will generate an error code of DOESNT_FIT_TYPE if it could not parse the field as a Date, and then, it will return null. This method uses the StringUtil.getDate() method.

getEmailAddress

public java.lang.String getEmailAddress(java.lang.String field_name,
                                        java.lang.String name_to_display,
                                        int minimum_length,
                                        int maximum_length)
Will return the email address no matter what, even if it doesn't fit, but if there are errors, will give IS_NULL, IS_EMPTY, TOO_SHORT, TOO_LONG, and DOESNT_FIT_TYPE. The email address should have at least one '@', at least one '.' after the '@', and contain only alphanumeric characters or characters in: [+@.'%-_!] (not including the brackets [ ]). (This method uses StringUtil.isEmailAddress().)