001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: /**
013: * Interface to a memento used for saving the important state of an object
014: * in a form that can be persisted in the file system.
015: * <p>
016: * Mementos were designed with the following requirements in mind:
017: * <ol>
018: * <li>Certain objects need to be saved and restored across platform sessions.
019: * </li>
020: * <li>When an object is restored, an appropriate class for an object might not
021: * be available. It must be possible to skip an object in this case.</li>
022: * <li>When an object is restored, the appropriate class for the object may be
023: * different from the one when the object was originally saved. If so, the
024: * new class should still be able to read the old form of the data.</li>
025: * </ol>
026: * </p>
027: * <p>
028: * Mementos meet these requirements by providing support for storing a
029: * mapping of arbitrary string keys to primitive values, and by allowing
030: * mementos to have other mementos as children (arranged into a tree).
031: * A robust external storage format based on XML is used.
032: * </p><p>
033: * The key for an attribute may be any alpha numeric value. However, the
034: * value of <code>TAG_ID</code> is reserved for internal use.
035: * </p><p>
036: * This interface is not intended to be implemented or extended by clients.
037: * </p>
038: *
039: * @see IPersistableElement
040: * @see IElementFactory
041: */
042: public interface IMemento {
043: /**
044: * Special reserved key used to store the memento id
045: * (value <code>"IMemento.internal.id"</code>).
046: *
047: * @see #getID()
048: */
049: public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$
050:
051: /**
052: * Creates a new child of this memento with the given type.
053: * <p>
054: * The <code>getChild</code> and <code>getChildren</code> methods
055: * are used to retrieve children of a given type.
056: * </p>
057: *
058: * @param type the type
059: * @return a new child memento
060: * @see #getChild
061: * @see #getChildren
062: */
063: public IMemento createChild(String type);
064:
065: /**
066: * Creates a new child of this memento with the given type and id.
067: * The id is stored in the child memento (using a special reserved
068: * key, <code>TAG_ID</code>) and can be retrieved using <code>getId</code>.
069: * <p>
070: * The <code>getChild</code> and <code>getChildren</code> methods
071: * are used to retrieve children of a given type.
072: * </p>
073: *
074: * @param type the type
075: * @param id the child id
076: * @return a new child memento with the given type and id
077: * @see #getID
078: */
079: public IMemento createChild(String type, String id);
080:
081: /**
082: * Returns the first child with the given type id.
083: *
084: * @param type the type id
085: * @return the first child with the given type
086: */
087: public IMemento getChild(String type);
088:
089: /**
090: * Returns all children with the given type id.
091: *
092: * @param type the type id
093: * @return an array of children with the given type
094: */
095: public IMemento[] getChildren(String type);
096:
097: /**
098: * Returns the floating point value of the given key.
099: *
100: * @param key the key
101: * @return the value, or <code>null</code> if the key was not found or was found
102: * but was not a floating point number
103: */
104: public Float getFloat(String key);
105:
106: /**
107: * Returns the type for this memento.
108: *
109: * @return the memento type
110: * @see #createChild(java.lang.String)
111: * @see #createChild(java.lang.String,java.lang.String)
112: * @since 3.4
113: */
114: public String getType();
115:
116: /**
117: * Returns the id for this memento.
118: *
119: * @return the memento id, or <code>null</code> if none
120: * @see #createChild(java.lang.String,java.lang.String)
121: */
122: public String getID();
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
138: */
139: public String getString(String key);
140:
141: /**
142: * Returns the boolean value of the given key.
143: *
144: * @param key the key
145: * @return the value, or <code>null</code> if the key was not found
146: * @since 3.4
147: */
148: public Boolean getBoolean(String key);
149:
150: /**
151: * Returns the data of the Text node of the memento. Each memento is allowed
152: * only one Text node.
153: *
154: * @return the data of the Text node of the memento, or <code>null</code>
155: * if the memento has no Text node.
156: * @since 2.0
157: */
158: public String getTextData();
159:
160: /**
161: * Returns an array of all the attribute keys of the memento. This will not
162: * be <code>null</code>. If there are no keys, an array of length zero will
163: * be returned.
164: * @return an array with all the attribute keys of the memento
165: * @since 3.4
166: */
167: public String[] getAttributeKeys();
168:
169: /**
170: * Sets the value of the given key to the given floating point number.
171: *
172: * @param key the key
173: * @param value the value
174: */
175: public void putFloat(String key, float value);
176:
177: /**
178: * Sets the value of the given key to the given integer.
179: *
180: * @param key the key
181: * @param value the value
182: */
183: public void putInteger(String key, int value);
184:
185: /**
186: * Copy the attributes and children from <code>memento</code>
187: * to the receiver.
188: *
189: * @param memento the IMemento to be copied.
190: */
191: public void putMemento(IMemento memento);
192:
193: /**
194: * Sets the value of the given key to the given string.
195: *
196: * @param key the key
197: * @param value the value
198: */
199: public void putString(String key, String value);
200:
201: /**
202: * Sets the value of the given key to the given boolean value.
203: *
204: * @param key the key
205: * @param value the value
206: * @since 3.4
207: */
208: public void putBoolean(String key, boolean value);
209:
210: /**
211: * Sets the memento's Text node to contain the given data. Creates the Text node if
212: * none exists. If a Text node does exist, it's current contents are replaced.
213: * Each memento is allowed only one text node.
214: *
215: * @param data the data to be placed on the Text node
216: * @since 2.0
217: */
218: public void putTextData(String data);
219: }
|