001: /**
002: * ===========================================
003: * JFreeReport : a free Java reporting library
004: * ===========================================
005: *
006: * Project Info: http://reporting.pentaho.org/
007: *
008: * (C) Copyright 2001-2007, by Object Refinery Ltd, Pentaho Corporation and Contributors.
009: *
010: * This library is free software; you can redistribute it and/or modify it under the terms
011: * of the GNU Lesser General Public License as published by the Free Software Foundation;
012: * either version 2.1 of the License, or (at your option) any later version.
013: *
014: * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
015: * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: * See the GNU Lesser General Public License for more details.
017: *
018: * You should have received a copy of the GNU Lesser General Public License along with this
019: * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
020: * Boston, MA 02111-1307, USA.
021: *
022: * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
023: * in the United States and other countries.]
024: *
025: * ------------
026: * ReportProperties.java
027: * ------------
028: * (C) Copyright 2001-2007, by Object Refinery Ltd, Pentaho Corporation and Contributors.
029: */package org.jfree.report.util;
030:
031: import java.io.Serializable;
032: import java.util.HashMap;
033: import java.util.Iterator;
034: import java.util.TreeSet;
035:
036: /**
037: * The report properties is a hashtable with string keys. ReportProperties are bound to a
038: * report as a general purpose storage. ReportProperties bound to a JFreeReport object are
039: * visible to all generated report-state chains. A ReportState will inherit all
040: * ReportProperties bound to the JFreeReport-object when the ReportState.StartState object
041: * is created. Properties bound to the report definition after the report state is
042: * created are not visible to the ReportState and its children.
043: * <p/>
044: * ReportProperties bound to a ReportState are not visible to the report definition (the
045: * JFreeReport object), but are visible to all ReportStates of that ReportState-chain. So
046: * when you add a property at the end of a report run to a ReportState, the value of this
047: * property will be visible to all ReportStates when the report is restarted at a certain
048: * point.
049: * <p/>
050: * ReportProperties can be seen as a stateless shared report internal storage area. All
051: * functions have access to the properties by using the ReportState.getProperty() and
052: * ReportState.setProperty() functions.
053: * <p/>
054: * For a list of defined default properties, have a look at the
055: * {@link org.jfree.report.JFreeReport} class.
056: *
057: * @author Thomas Morgner
058: */
059: public class ReportProperties implements Serializable, Cloneable {
060: /**
061: * Storage for the properties.
062: */
063: private HashMap properties;
064:
065: /**
066: * The fall-back property-collection.
067: */
068: private ReportProperties masterProperties;
069:
070: /**
071: * Copy constructor.
072: *
073: * @param props an existing ReportProperties instance.
074: */
075: public ReportProperties(final ReportProperties props) {
076: this .properties = new HashMap(props.properties);
077: }
078:
079: /**
080: * Default constructor.
081: */
082: public ReportProperties() {
083: this .properties = new HashMap();
084: }
085:
086: /**
087: * Adds a property to this properties collection. If a property with the given name
088: * exist, the property will be replaced with the new value. If the value is null, the
089: * property will be removed.
090: *
091: * @param key the property key.
092: * @param value the property value.
093: */
094: public void put(final String key, final Object value) {
095: if (key == null) {
096: throw new NullPointerException(
097: "ReportProperties.put (..): Parameter 'key' must not be null");
098: }
099: if (value == null) {
100: this .properties.remove(key);
101: } else {
102: this .properties.put(key, value);
103: }
104: }
105:
106: /**
107: * Retrieves the value stored for a key in this properties collection.
108: *
109: * @param key the property key.
110: * @return The stored value, or <code>null</code> if the key does not exist in this
111: * collection.
112: */
113: public Object get(final String key) {
114: if (key == null) {
115: throw new NullPointerException(
116: "ReportProperties.get (..): Parameter 'key' must not be null");
117: }
118: return get(key, null);
119: }
120:
121: /**
122: * Retrieves the value stored for a key in this properties collection, and returning the
123: * default value if the key was not stored in this properties collection.
124: *
125: * @param key the property key.
126: * @param defaultValue the default value to be returned when the key is not stored in
127: * this properties collection.
128: * @return The stored value, or the default value if the key does not exist in this
129: * collection.
130: */
131: public Object get(final String key, final Object defaultValue) {
132: if (key == null) {
133: throw new NullPointerException(
134: "ReportProperties.get (..): Parameter 'key' must not be null");
135: }
136: final Object o = this .properties.get(key);
137: if (o == null) {
138: if (masterProperties != null) {
139: return masterProperties.get(key, defaultValue);
140: }
141: return defaultValue;
142: }
143: return o;
144: }
145:
146: /**
147: * Returns all property keys as enumeration.
148: *
149: * @return an enumeration of the property keys.
150: */
151: public Iterator keys() {
152: final TreeSet list = new TreeSet();
153: list.addAll(this .properties.keySet());
154:
155: return list.iterator();
156: }
157:
158: /**
159: * Removes all properties stored in this collection.
160: */
161: public void clear() {
162: this .properties.clear();
163: }
164:
165: /**
166: * Checks whether the given key is stored in this collection of ReportProperties.
167: *
168: * @param key the property key.
169: * @return true, if the given key is known.
170: */
171: public boolean containsKey(final String key) {
172: if (key == null) {
173: throw new NullPointerException(
174: "ReportProperties.containsKey (..): Parameter key must not be null");
175: }
176: return this .properties.containsKey(key);
177: }
178:
179: /**
180: * Clones the properties.
181: *
182: * @return a copy of this ReportProperties object.
183: *
184: * @throws CloneNotSupportedException this should never happen.
185: */
186: public Object clone() throws CloneNotSupportedException {
187: final ReportProperties p = (ReportProperties) super .clone();
188: p.properties = (HashMap) this .properties.clone();
189: p.masterProperties = null;
190: return p;
191: }
192:
193: /**
194: * Marks a property.
195: *
196: * @param property the property key.
197: * @param marked boolean.
198: * @deprecated marking is no longer necessary.
199: */
200: public void setMarked(final String property, final boolean marked) {
201: }
202:
203: /**
204: * Returns true if the specified property is marked, and false otherwise.
205: *
206: * @param property the property key.
207: * @return true for marked properties, false otherwise.
208: * @deprecated marking is no longer necessary.
209: */
210: public boolean isMarked(final String property) {
211: return true;
212: }
213:
214: /**
215: * Returns true, if there is at least one marked property.
216: *
217: * @return true, if there are some properties marked, false otherwise.
218: */
219: public boolean containsMarkedProperties() {
220: return true;
221: }
222:
223: /**
224: * Returns the fall-back property-collection. If defined, this collection will be used if a queried property is not
225: * defined in this collection.
226: *
227: * @return the fall-back collection.
228: */
229: public ReportProperties getMasterProperties() {
230: return masterProperties;
231: }
232:
233: /**
234: * Defines the fall-back property-collection. If defined, this collection will be used if a queried property is not
235: * defined in this collection.
236: *
237: * @param masterProperties the fall-back collection.
238: */
239: public void setMasterProperties(
240: final ReportProperties masterProperties) {
241: this .masterProperties = masterProperties;
242: }
243:
244: /**
245: * Marks a property. Marking was a historical process that made the property available in the report's datarow. Since
246: * version 0.8.9, all properties are part of the data-row by default.
247: *
248: * @deprecated marking is no longer necessary.
249: * @return all keys
250: */
251: public Iterator markedKeys() {
252: return keys();
253: }
254:
255: /**
256: * Returns all defined keys as string-array.
257: *
258: * @return the keys as array.
259: */
260: public String[] keyArray() {
261: return (String[]) properties.keySet().toArray(
262: new String[properties.size()]);
263: }
264:
265: /**
266: * Returns the number of entries in this collection.
267: *
268: * @return the number of properties defined here.
269: */
270: public int size() {
271: return properties.size();
272: }
273: }
|