001: package org.igfay.jfig;
002:
003: import java.util.List;
004: import java.util.Map;
005: import java.util.Properties;
006:
007: /**
008: * Interface for JFig
009: *
010: * The JFig package provides very simple, flexible and powerful
011: * functionality for managing one or more configurations in a java environment.
012: *
013: * <P>It allows for a combination of a hierarchy of configuration files,
014: * substitution variables and property variables. Methods are provided to get
015: * values stored in a configuration dictionary with a variety of types (String,
016: * array, integer, float, boolean, etc) and default values.
017: *<P>
018: * Usage:
019: * <BR>To get an instance of the JFig singleton, use:
020: * JFig. getInstance();
021: *
022: * <P>There are a number of helper methods to retrieve configuration values. The
023: * most common is:
024: * <BR>String value = JFig. getInstance().getValue ("aSection","aKey","aDefaultValue");
025: *
026: * <P>See the javadocs for additional helper methods to retrieve values as
027: * different java types and with different exception handling.
028: *
029: *@author bconrad
030: *@created July 10, 2003
031: */
032: public interface JFigIF {
033: /**
034: * Add ConfigEvent listeners to vector so they can be notified when there
035: * is a significant change in the configuration.
036: *
037: *@param listener The feature to be added to the ConfigEventListener
038: * attribute
039: */
040: public abstract void addConfigEventListener(JFigListener listener);
041:
042: /**
043: * Print the values in the configuration dictionary.
044: */
045: public abstract void print();
046:
047: /**
048: * Print the values in the configuration dictionary.
049: * @deprecated
050: */
051: public abstract void printConfigurationDictionary();
052:
053: /**
054: * reprocess the configuration creating a new config dictionary
055: */
056: public abstract void reprocessConfiguration() throws JFigException;
057:
058: /**
059: * reprocess the configuration creating a new config dictionary
060: */
061: public abstract void reprocessConfiguration(JFigLocator locator)
062: throws JFigException;
063:
064: /**
065: * return the ConfigurationDictionary
066: * Made public so we can access this from a jsp and show the configuration
067: * via html.
068: */
069: public abstract JFigDictionary getConfigDictionary();
070:
071: /**
072: * convenience method for getting values as array
073: * The value is tokenized depending on the first token found in
074: * the following order: comma, semicolon, colon, space
075: *
076: */
077: public abstract String[] getArrayValue(String section, String key)
078: throws JFigException;
079:
080: /**
081: * convenience method for getting values as boolean
082: */
083: public abstract boolean getBooleanValue(String section, String key,
084: String notFoundValue);
085:
086: /**
087: * getFloatValue() convenience method for getting values as float
088: *
089: *@param section Description of Parameter
090: *@param key Description of Parameter
091: *@param notFoundValue Description of Parameter
092: *@return The FloatValue value
093: *@exception JFigException Description of Exception
094: */
095: public abstract float getFloatValue(String section, String key,
096: String notFoundValue) throws JFigException;
097:
098: /**
099: * convenience method for getting values as int
100: */
101: public abstract int getIntegerValue(String section, String key)
102: throws JFigException;
103:
104: /**
105: * convenience method for getting values as int, with default value
106: */
107: public abstract int getIntegerValue(String section, String key,
108: String notFoundValue);
109:
110: /**
111: * First look in given section. Try again for default section.
112: *
113: *@param section Description of Parameter
114: *@param key Description of Parameter
115: *@param defaultValue Description of Parameter
116: *@return The Value value
117: */
118: public abstract String getValue(String section, String key,
119: String defaultValue);
120:
121: /**
122: * Return a list of all values starting with "key" in the scetcion.
123: * If section xxx contains x.1, x.2, and x.3,
124: * getValuesStartingWith("xxx", "x.") returns a list containing
125: * x.1, x.2, and x.3.
126: *
127: * @param section
128: * @param key
129: * @param defaultValue
130: * @return List
131: */
132: public abstract List getValuesStartingWith(String section,
133: String key);
134:
135: /**
136: * Return a map of all values starting with "key" in the scetcion.
137: * If section xxx contains x.1=a, x.2=b, and x.3=c,
138: * getValuesStartingWith("xxx", "x.") returns a map containing
139: * x.1,a x.2,b and x.3,c.
140: *
141: * @param section
142: * @param key
143: * @param defaultValue
144: * @return List
145: */
146: public Map getEntriesStartingWith(String section, String key);
147:
148: /**
149: * Call configParser to get the value for a key in a given section.
150: *
151: */
152: public abstract String getValue(String section, String key)
153: throws JFigException;
154:
155: /**
156: * Return an entire section
157: * @param section
158: * @return
159: */
160: public Map getSection(String section);
161:
162: /**
163: * Return a section converted to a Properties object (but not system properties)
164: * @param section
165: * @return
166: */
167: public abstract Properties getSectionAsProperties(String section);
168:
169: /**
170: * Return a section added to the supplied Properties object
171: * @param section
172: * @return
173: */
174: public abstract Properties getSectionAsProperties(String section,
175: Properties properties);
176:
177: /**
178: * Set a configuration value.
179: * Most values are set during initial parsing so this is rarely used.
180: */
181: public abstract void setConfigurationValue(String sectionName,
182: String keyString, String valueString);
183:
184: /**
185: * convenience method for getting values as array with default value
186: */
187: public abstract String[] getArrayValue(String section, String key,
188: String notFoundValue);
189: }
|