001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.lib.conf;
020:
021: import java.beans.BeanInfo;
022: import java.beans.PropertyChangeListener;
023: import java.io.Serializable;
024: import java.util.Map;
025: import java.util.Properties;
026:
027: import org.apache.openjpa.lib.log.Log;
028: import org.apache.openjpa.lib.log.LogFactory;
029: import org.apache.openjpa.lib.util.Closeable;
030:
031: /**
032: * Interface for generic configuration objects. Includes the ability
033: * to write configuration to and from {@link Properties} instances. Instances
034: * are threadsafe for reads, but not for writes.
035: *
036: * @author Marc Prud'hommeaux
037: * @author Abe White
038: */
039: public interface Configuration extends BeanInfo, Serializable,
040: Closeable, Cloneable {
041:
042: /**
043: * Attribute of returned {@link Value} property descriptors listing
044: * recognized values for the property.
045: */
046: public static final String ATTRIBUTE_ALLOWED_VALUES = "allowedValues";
047:
048: /**
049: * Attribute of the returned {@link Value} property descriptors naming
050: * the property's type or category.
051: */
052: public static final String ATTRIBUTE_TYPE = "propertyType";
053:
054: /**
055: * Attribute of the returned {@link Value} property descriptors naming
056: * the property' hierarchical category.
057: */
058: public static final String ATTRIBUTE_CATEGORY = "propertyCategory";
059:
060: /**
061: * Attribute of the returned {@link Value} property descriptors naming
062: * the property's ordering in its category.
063: */
064: public static final String ATTRIBUTE_ORDER = "propertyCategoryOrder";
065:
066: /**
067: * Attribute of the returned {@link Value} property descriptors naming
068: * the interface that plugin values for this property must implement.
069: */
070: public static final String ATTRIBUTE_INTERFACE = "propertyInterface";
071:
072: /**
073: * Attribute of the returned {@link Value} property descriptors naming
074: * the property's name in XML format (i.e. two-words instead of TwoWords).
075: */
076: public static final String ATTRIBUTE_XML = "xmlName";
077:
078: public static final int INIT_STATE_LIQUID = 0;
079: public static final int INIT_STATE_FREEZING = 1;
080: public static final int INIT_STATE_FROZEN = 2;
081:
082: /**
083: * Return the product name. Defaults to <code>openjpa</code>.
084: */
085: public String getProductName();
086:
087: /**
088: * Set the product name.
089: */
090: public void setProductName(String name);
091:
092: /**
093: * The log factory. If no log factory has been set explicitly,
094: * this method will create one.
095: */
096: public LogFactory getLogFactory();
097:
098: /**
099: * The log factory.
100: */
101: public void setLogFactory(LogFactory factory);
102:
103: /**
104: * Log plugin setting.
105: */
106: public String getLog();
107:
108: /**
109: * Log plugin setting.
110: */
111: public void setLog(String log);
112:
113: /**
114: * Return the log for the given category.
115: *
116: * @see #getLogFactory
117: */
118: public Log getLog(String category);
119:
120: /**
121: * Return the log to use for configuration messages.
122: */
123: public Log getConfigurationLog();
124:
125: /**
126: * An environment-specific identifier for this configuration. This
127: * might correspond to a JPA persistence-unit name, or to some other
128: * more-unique value available in the current environment.
129: *
130: * @since 0.9.7
131: */
132: public String getId();
133:
134: /**
135: * An environment-specific identifier for this configuration. This
136: * might correspond to a JPA persistence-unit name, or to some other
137: * more-unique value available in the current environment.
138: *
139: * @since 0.9.7
140: */
141: public void setId(String id);
142:
143: /**
144: * Return the {@link Value} for the given property, or null if none.
145: */
146: public Value getValue(String property);
147:
148: /**
149: * Return the set of all {@link Value}s.
150: */
151: public Value[] getValues();
152:
153: /**
154: * Add the given value to the set of configuration properties. This
155: * method replaces any existing value under the same property.
156: */
157: public Value addValue(Value val);
158:
159: /**
160: * Remove the given value from the set of configuration properties.
161: */
162: public boolean removeValue(Value val);
163:
164: /**
165: * A properties representation of this Configuration.
166: * Note that changes made to this properties object will
167: * not be automatically reflected in this Configuration object.
168: *
169: * @param storeDefaults if true, then properties will be written
170: * out even if they match the default value for a property
171: */
172: public Map toProperties(boolean storeDefaults);
173:
174: /**
175: * Set this Configuration via the given map. Any keys missing from
176: * the given map will not be set. Note that changes made to this map
177: * will not be automatically reflected in this Configuration object.
178: * IMPORTANT: If the map contains instantiated objects(rather than
179: * string values), only the string representation of those objects
180: * are considered in this configuration's <code>equals</code> and
181: * <code>hashCode</code> methods. If the object's property has no
182: * string form(such as an {@link ObjectValue}), the object is not
183: * part of the equality and hashing calculations.
184: */
185: public void fromProperties(Map map);
186:
187: /**
188: * Adds a listener for any property changes. The property events fired
189: * will <b>not</b> include the old value.
190: *
191: * @param listener the listener to receive notification of property changes
192: */
193: public void addPropertyChangeListener(
194: PropertyChangeListener listener);
195:
196: /**
197: * Removes a listener for any property changes.
198: *
199: * @param listener the listener to remove
200: */
201: public void removePropertyChangeListener(
202: PropertyChangeListener listener);
203:
204: /**
205: * Lock down the configuration's state. Attempting to set state on a
206: * read-only configuration results in an exception.
207: */
208: public void setReadOnly(int readOnly);
209:
210: /**
211: * Return true if this configuration is immutable.
212: */
213: public boolean isReadOnly();
214:
215: /**
216: * Call the instantiating get methods for all values. Up-front
217: * instantiation allows one to avoid the synchronization necessary with
218: * lazy instantiation.
219: */
220: public void instantiateAll();
221:
222: /**
223: * Free the resources used by this object.
224: */
225: public void close();
226:
227: /**
228: * Return a copy of this configuration.
229: */
230: public Object clone();
231:
232: /**
233: * Modifies a <em>dynamic</em> property of this receiver even when
234: * {@link #setReadOnly(boolean) frozen}.
235: *
236: * @since 1.0.0
237: */
238: // public void modifyDynamic(String property, Object newValue);
239: //
240: // /**
241: // * Affirms if the given property can be modified <em>dynamically</em> i.e.
242: // * even after the receiver is {@link #setReadOnly(boolean) frozen}.
243: // *
244: // * @since 1.0.0
245: // */
246: // public boolean isDynamic(String property);
247: //
248: // /**
249: // * Gets the values that can be modified <em>dynamically</em> i.e.
250: // * even after the receiver is {@link #setReadOnly(boolean) frozen}.
251: // *
252: // * @since 1.0.0
253: // */
254: // public Value[] getDynamicValues();
255: }
|