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