001: /*
002: * $RCSfile: ParameterListDescriptor.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:14 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: import javax.media.jai.util.Range;
015:
016: /** A class that signifies that a parameter has no default value. */
017: class ParameterNoDefault implements java.io.Serializable {
018: ParameterNoDefault() {
019: }
020:
021: public String toString() {
022: return "No Parameter Default";
023: }
024: }
025:
026: /**
027: * This interface provides a comprehensive description of a set of
028: * parameters including parameter names, parameter defaults,
029: * valid parameter value ranges, etc.
030: *
031: * The parameter names should be used in a case retentive manner. i.e.
032: * all lookups and comparisons are case-insensitive but any request
033: * for a parameter name should return the original name with the case
034: * preserved.
035: *
036: * @see ParameterList
037: *
038: * @since JAI 1.1
039: */
040: public interface ParameterListDescriptor {
041:
042: /**
043: * An <code>Object</code> that signifies that a parameter has
044: * no default value.
045: */
046: public static final Object NO_PARAMETER_DEFAULT = ParameterNoDefault.class;
047:
048: /**
049: * Returns the total number of parameters.
050: */
051: int getNumParameters();
052:
053: /**
054: * Returns an array of <code>Class</code>es that describe the types
055: * of parameters. If there are no parameters, this method returns
056: * <code>null</code>.
057: */
058: Class[] getParamClasses();
059:
060: /**
061: * Returns an array of <code>String</code>s that are the
062: * names of the parameters associated with this descriptor. If there
063: * are no parameters, this method returns <code>null</code>.
064: */
065: String[] getParamNames();
066:
067: /**
068: * Returns an array of <code>Object</code>s that define the default
069: * values of the parameters. Since <code>null</code> might be a
070: * valid parameter value, the <code>NO_PARAMETER_DEFAULT</code>
071: * static <code>Object</code> is used to indicate that a parameter
072: * has no default value. If there are no parameters, this method
073: * returns <code>null</code>.
074: */
075: Object[] getParamDefaults();
076:
077: /**
078: * Returns the default value of a specified parameter. The default
079: * value may be <code>null</code>. If a parameter has no default
080: * value, this method returns <code>NO_PARAMETER_DEFAULT</code>.
081: *
082: * @param parameterName The name of the parameter whose default
083: * value is queried.
084: *
085: * @throws IllegalArgumentException if <code>parameterName</code> is null
086: * or if the parameter does not exist.
087: */
088: Object getParamDefaultValue(String parameterName);
089:
090: /**
091: * Returns the <code>Range</code> that represents the range of valid
092: * values for the specified parameter. Returns <code>null</code> if
093: * the parameter can take on any value or if the valid values are
094: * not representable as a Range.
095: *
096: * @param parameterName The name of the parameter whose valid range
097: * of values is to be determined.
098: *
099: * @throws IllegalArgumentException if <code>parameterName</code> is null
100: * or if the parameter does not exist.
101: */
102: Range getParamValueRange(String parameterName);
103:
104: /**
105: * Return an array of the names of all parameters the type of which is
106: * <code>EnumeratedParameter</code>.
107: *
108: * @return The requested array of names or <code>null</code> if there
109: * are no parameters with <code>EnumeratedParameter</code> type.
110: */
111: String[] getEnumeratedParameterNames();
112:
113: /**
114: * Return an array of <code>EnumeratedParameter</code> objects
115: * corresponding to the parameter with the specified name.
116: *
117: * @param parameterName The name of the parameter for which the
118: * <code>EnumeratedParameter</code> array is to be returned.
119: *
120: * @throws IllegalArgumentException if <code>parameterName</code> is null
121: * or if the parameter does not exist.
122: * @throws UnsupportedOperationException if there are no enumerated
123: * parameters associated with the descriptor.
124: * @throws IllegalArgumentException if <code>parameterName</code> is
125: * a parameter the class of which is not a subclass of
126: * <code>EnumeratedParameter</code>.
127: *
128: * @return An array of <code>EnumeratedParameter</code> objects
129: * representing the range of values for the named parameter.
130: */
131: EnumeratedParameter[] getEnumeratedParameterValues(
132: String parameterName);
133:
134: /**
135: * Checks to see whether the specified parameter can take on the specified
136: * value.
137: *
138: * @param parameterName The name of the parameter for which the
139: * validity check is to be performed.
140: *
141: * @throws IllegalArgumentException if <code>parameterName</code> is null
142: * or if the parameter does not exist.
143: * @throws IllegalArgumentException if the class of the object "value"
144: * is not an instance of the class type of parameter
145: * pointed to by the parameterName
146: *
147: * @return true, if it is valid to pass this value in for this
148: * parameter, false otherwise.
149: */
150: boolean isParameterValueValid(String parameterName, Object value);
151: }
|