Java > Open Source Codes > org > eclipse > ui > IMemento


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags