A placeholder module for build, to support the CVS modules reorg
[phpeclipse.git] / net.sourceforge.phpeclipse.phphelp / src / net / sourceforge / phpdt / httpquery / config / IMemento.java
1 /**********************************************************************
2  * Copyright (c) 2003 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Common Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v10.html
7  *
8  * Contributors:
9  *     IBM Corporation - Initial API and implementation
10  **********************************************************************/
11 package net.sourceforge.phpdt.httpquery.config;
12
13 import java.util.List;
14
15 import org.eclipse.ui.IElementFactory;
16 import org.eclipse.ui.IPersistableElement;
17 /**
18  * Interface to a memento used for saving the important state of an object
19  * in a form that can be persisted in the file system.
20  * <p>
21  * Mementos were designed with the following requirements in mind:
22  * <ol>
23  *  <li>Certain objects need to be saved and restored across platform sessions.
24  *    </li>
25  *  <li>When an object is restored, an appropriate class for an object might not
26  *    be available. It must be possible to skip an object in this case.</li>
27  *  <li>When an object is restored, the appropriate class for the object may be
28  *    different from the one when the object was originally saved. If so, the
29  *    new class should still be able to read the old form of the data.</li>
30  * </ol>
31  * </p>
32  * <p>
33  * Mementos meet these requirements by providing support for storing a
34  * mapping of arbitrary string keys to primitive values, and by allowing
35  * mementos to have other mementos as children (arranged into a tree).
36  * A robust external storage format based on XML is used.
37  * </p><p>
38  * The key for an attribute may be any alpha numeric value.  However, the
39  * value of <code>TAG_ID</code> is reserved for internal use.
40  * </p><p>
41  * This interface is not intended to be implemented by clients.
42  * </p>
43  *
44  * @see IPersistableElement
45  * @see IElementFactory
46  */
47 public interface IMemento {
48         /**
49          * Special reserved key used to store the memento id
50          * (value <code>"org.eclipse.ui.id"</code>).
51          *
52          * @see #getId
53          */
54         public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$
55
56         /**
57          * Creates a new child of this memento with the given fType.
58          * <p>
59          * The <code>getChild</code> and <code>getChildren</code> methods
60          * are used to retrieve children of a given fType.
61          * </p>
62          *
63          * @param fType the fType
64          * @return a new child memento
65          * @see #getChild
66          * @see #getChildren
67          */
68         public IMemento createChild(String type);
69
70         /**
71          * Creates a new child of this memento with the given fType and id.
72          * The id is stored in the child memento (using a special reserved
73          * key, <code>TAG_ID</code>) and can be retrieved using <code>getId</code>.
74          * <p>
75          * The <code>getChild</code> and <code>getChildren</code> methods
76          * are used to retrieve children of a given fType.
77          * </p>
78          *
79          * @param fType the fType
80          * @param id the child id
81          * @return a new child memento with the given fType and id
82          * @see #getId
83          */
84         public IMemento createChild(String type, String id);
85
86         /**
87          * Returns the first child with the given fType id.
88          *
89          * @param fType the fType id
90          * @return the first child with the given fType
91          */
92         public IMemento getChild(String type);
93
94         /**
95          * Returns all children with the given fType id.
96          *
97          * @param fType the fType id
98          * @return the list of children with the given fType
99          */
100         public IMemento[] getChildren(String type);
101
102         /**
103          * Returns the floating point value of the given key.
104          *
105          * @param key the key
106          * @return the value, or <code>null</code> if the key was not found or was found
107          *   but was not a floating point number
108          */
109         public Float getFloat(String key);
110
111         /**
112          * Returns the id for this memento.
113          *
114          * @return the memento id, or <code>null</code> if none
115          * @see #createChild(java.lang.String,java.lang.String)
116          */
117         public String getId();
118
119         /**
120          * Returns the name for this memento.
121          *
122          * @return the memento name, or <code>null</code> if none
123          * @see #createChild(java.lang.String,java.lang.String)
124          */
125         public String getName();
126
127         /**
128          * Returns the integer value of the given key.
129          *
130          * @param key the key
131          * @return the value, or <code>null</code> if the key was not found or was found
132          *   but was not an integer
133          */
134         public Integer getInteger(String key);
135
136         /**
137          * Returns the string value of the given key.
138          *
139          * @param key the key
140          * @return the value, or <code>null</code> if the key was not found or was found
141          *  but was not an integer
142          */
143         public String getString(String key);
144
145         /**
146          * Returns the boolean value of the given key.
147          *
148          * @param key the key
149          * @return the value, or <code>null</code> if the key was not found or was found
150          *  but was not a boolean
151          */
152         public Boolean getBoolean(String key);
153
154         public List getNames();
155
156         /**
157          * Sets the value of the given key to the given floating point number.
158          *
159          * @param key the key
160          * @param value the value
161          */
162         public void putFloat(String key, float value);
163
164         /**
165          * Sets the value of the given key to the given integer.
166          *
167          * @param key the key
168          * @param value the value
169          */
170         public void putInteger(String key, int value);
171
172         /**
173          * Sets the value of the given key to the given boolean value.
174          *
175          * @param key the key
176          * @param value the value
177          */
178         public void putBoolean(String key, boolean value);
179
180         /**
181          * Copy the attributes and children from  <code>memento</code>
182          * to the receiver.
183          *
184          * @param memento the IMemento to be copied.
185          */
186         public void putMemento(IMemento memento);
187
188         /**
189          * Sets the value of the given key to the given string.
190          *
191          * @param key the key
192          * @param value the value
193          */
194         public void putString(String key, String value);
195 }