001: /*
002: * Parameters.java February 2001
003: *
004: * Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013: * GNU Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General
016: * Public License along with this library; if not, write to the
017: * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
018: * Boston, MA 02111-1307 USA
019: */
020:
021: package simple.util.net;
022:
023: import java.util.Enumeration;
024: import java.util.Map;
025:
026: /**
027: * The <code>Parameters</code> object is used to represent HTTP
028: * parameters. Parameters are acquired by name and can be either a
029: * string, float, int, or boolean value. This ensures that data can
030: * be conviniently extracted in the correct type. This follows the
031: * parameter methods found in the Java Servlet API Specification.
032: * The parameter values found in a parameter set can extracted via
033: * farmiliar methods such as <code>getParameter</code>. However,
034: * unlike the Java servlet API this wrapper for HTTP parameters is
035: * modifiable, that is, parameters can be added and removed.
036: *
037: * @author Niall Gallagher
038: */
039: public interface Parameters extends Map {
040:
041: /**
042: * This enumerates the names of every parameter. This enables
043: * the parameter values to be extracted by providing the name
044: * to the <code>getParameter</code> method. The resulting
045: * <code>Enumeration</code> contains string objects.
046: *
047: * @return this returns an <code>Enumeration</code> of names
048: */
049: public Enumeration getParameterNames();
050:
051: /**
052: * This extracts a value for the given name. The name issued
053: * to this method must be from the <code>Enumeration</code>
054: * issued. If there is no parameter of this name this will
055: * return a null value.
056: *
057: * @param name the name of the parameter value to retrieve
058: *
059: * @return this returns the first value for the given name
060: */
061: public String getParameter(Object name);
062:
063: /**
064: * This extracts an integer parameter for the named value.
065: * If the named parameter does not exist this will return
066: * a zero value. If however the parameter exists but is
067: * not in the format of a decimal integer value then this
068: * will throw a <code>NumberFormatException</code>.
069: *
070: * @param name the name of the parameter value to retrieve
071: *
072: * @return this returns the parameter value as an integer
073: *
074: * @throws NumberFormatException if the value is not valid
075: */
076: public int getInteger(Object name);
077:
078: /**
079: * This extracts a float parameter for the named value.
080: * If the named parameter does not exist this will return
081: * a zero value. If however the parameter exists but is
082: * not in the format of a floating point number then this
083: * will throw a <code>NumberFormatException</code>.
084: *
085: * @param name the name of the parameter value to retrieve
086: *
087: * @return this returns the parameter value as a float
088: *
089: * @throws NumberFormatException if the value is not valid
090: */
091: public float getFloat(Object name);
092:
093: /**
094: * This extracts a boolean parameter for the named value.
095: * If the named parameter does not exist this will return
096: * false otherwize the value is evaluated. If it is either
097: * <code>true</code> or <code>false</code> then those
098: * boolean values are returned, otherwize it is false.
099: *
100: * @param name the name of the parameter value to retrieve
101: *
102: * @return this returns the parameter value as an float
103: */
104: public boolean getBoolean(Object name);
105:
106: /**
107: * This will return all parameters represented using the HTTP
108: * URL query format. The <code>x-www-form-urlencoded</code>
109: * format is used to encode the attributes, see RFC 2616.
110: * <p>
111: * This will also encode any special characters that appear
112: * within the name and value pairs as an escaped sequence.
113: * If there are no parameters an empty string is returned.
114: *
115: * @return returns an empty string if the is no parameters
116: */
117: public String toString();
118: }
|