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