Source code: org/jdaemon/util/data/DataRepresentation.java
1 /*
2 * Properties.java
3 *
4 * Copyright (C) 2002 Jonathan Essex
5 * This program is distributed under the terms of the Lesser GNU General Public
6 * License (v2 or later) per the included COPYING.txt file, or see www.fsf.org.
7 *
8 * Created on April 23, 2002, 3:58 PM
9 */
10
11 package org.jdaemon.util.data;
12
13 import java.util.Iterator;
14
15 /** Uberinterface for properties files, directory data, XML config, etc.
16 * <P>
17 * A DataRepresentation object represents two things: a named collection of simple attributes,
18 * and a named collection of child DataRepresentations (aka Elements). In addition, each
19 * DataRepresentation has a 'Type' value which can be retrieved through the getElementType method.
20 * </P><P>
21 * This paradigm works well for both data held in XML files and data held in JNDI directories.
22 * (Indeed, the API of DataRepresentation can be thought of as the lowest common denominator
23 * between the JNDI and DOM interfaces).
24 * </P><P>
25 * In the case of XML, a DataRepresentation maps to a Tag. The ElementType is the tag name.
26 * Attributes of the DataRepresentation are derived from attributes of the tag, and the
27 * Elements are derived from any enclosed tags. Every enclosed tag must have an additional
28 * 'key' attribute, which contains the key string used by the parent DataRepresentation to
29 * identify the child tags.
30 * </P><P>
31 * In the case of JNDI, a DataRepresentation maps to a Directory. The ElementType represented
32 * by the special objectClass attribute. Attributes of the DataRepresentation are derived
33 * from attributes of the directory, and Elements are derived from sub-directories.
34 * </P>
35 * @author jonathan
36 * @version
37 */
38 public interface DataRepresentation {
39
40 /** Get the value of a simple attribute of the DataRepresentation.
41 *
42 * @param key of attribute to be returned
43 * @return the string value of the attriubte
44 */
45 String getAttribute(Object key) throws ReadError;
46
47 /** Get a named child DataRepresentation.
48 *
49 * @param key of attribute to be returned
50 * @return A child DataRepresentation
51 */
52 DataRepresentation getElement(Object key) throws ReadError;
53
54 /** Get the type of data in this representation.
55 *
56 * @return A string which indicates the type of data stored by this DataRepresentation
57 */
58 String getElementType() throws ReadError;
59
60 /** Get all the valid attribute keys within this representation.
61 *
62 * @return an Iterator over all the keys which can be used to retrieve an attribute of this DataRepresentation
63 */
64 Iterator getAttributeKeys() throws ReadError;
65
66 /** Return all the valid Element keys within this representation.
67 *
68 * @return an Iterator over all the keys which can be used to retrieve child DataRepresentation
69 */
70 Iterator getElementKeys() throws ReadError;
71
72 /** Set an attribute of this representation.
73 *
74 * Sets an existing attribute or creates a new attribute if an attribute with the
75 * given key does not already exist.
76 *
77 * @param key Key of the attribute for which the value is to be set
78 * @param value New value for attribute identified by <I>key</I>
79 */
80 void setAttribute(Object key, String value) throws WriteError;
81
82 /** Add an element to this representation with the given key.
83 * <P>
84 * Creates a new child DataRepresentation with the given key and <B>copies</B> data from
85 * the given 'other' representation into it. If an element already exists, with the given
86 * key the entire old element is first deleted.
87 * </P><P>
88 * Note that we exlicity allow the given 'other' DataRepresentation to be a different
89 * class to this DataRepresentation. For example, it should be possible to use this method
90 * to copy data from an XML file to a JNDI directory.
91 * </P>
92 * @param key Key of the new child element for which the value is to be set
93 * @param other Data to copy into the new child element
94 */
95 void setElement(Object key, DataRepresentation other) throws WriteError, ReadError;
96
97 /** Create a new DataRepresentation to which we can freely add data.
98 *
99 * The created element is not a member of this or any parent representation.
100 *
101 * @param type The element type for the new DataRepresentation
102 * @return A new DataRepresentation
103 */
104 DataRepresentation newElement(String type);
105 }
106