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
9 * IBM Corporation - Initial API and implementation
10 **********************************************************************/
11 package net.sourceforge.phpdt.monitor.core.internal;
13 import java.util.List;
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.
18 * Mementos were designed with the following requirements in mind:
20 * <li>Certain objects need to be saved and restored across platform sessions.
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>
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.
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.
38 * This interface is not intended to be implemented by clients.
41 * @see IPersistableElement
42 * @see IElementFactory
44 public interface IMemento {
46 * Special reserved key used to store the memento id
47 * (value <code>"org.eclipse.ui.id"</code>).
51 public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$
54 * Creates a new child of this memento with the given type.
56 * The <code>getChild</code> and <code>getChildren</code> methods
57 * are used to retrieve children of a given type.
60 * @param type the type
61 * @return a new child memento
65 public IMemento createChild(String type);
68 * Creates a new child of this memento with the given type 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>.
72 * The <code>getChild</code> and <code>getChildren</code> methods
73 * are used to retrieve children of a given type.
76 * @param type the type
77 * @param id the child id
78 * @return a new child memento with the given type and id
81 public IMemento createChild(String type, String id);
84 * Returns the first child with the given type id.
86 * @param type the type id
87 * @return the first child with the given type
89 public IMemento getChild(String type);
92 * Returns all children with the given type id.
94 * @param type the type id
95 * @return the list of children with the given type
97 public IMemento[] getChildren(String type);
100 * Returns the floating point value of the given 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
106 public Float getFloat(String key);
109 * Returns the id for this memento.
111 * @return the memento id, or <code>null</code> if none
112 * @see #createChild(java.lang.String,java.lang.String)
114 public String getId();
117 * Returns the name for this memento.
119 * @return the memento name, or <code>null</code> if none
120 * @see #createChild(java.lang.String,java.lang.String)
122 public String getName();
125 * Returns the integer value of the given key.
128 * @return the value, or <code>null</code> if the key was not found or was found
129 * but was not an integer
131 public Integer getInteger(String key);
134 * Returns the string value of the given key.
137 * @return the value, or <code>null</code> if the key was not found or was found
138 * but was not an integer
140 public String getString(String key);
143 * Returns the boolean value of the given key.
146 * @return the value, or <code>null</code> if the key was not found or was found
147 * but was not a boolean
149 public Boolean getBoolean(String key);
151 public List getNames();
154 * Sets the value of the given key to the given floating point number.
157 * @param value the value
159 public void putFloat(String key, float value);
162 * Sets the value of the given key to the given integer.
165 * @param value the value
167 public void putInteger(String key, int value);
170 * Sets the value of the given key to the given boolean value.
173 * @param value the value
175 public void putBoolean(String key, boolean value);
178 * Copy the attributes and children from <code>memento</code>
181 * @param memento the IMemento to be copied.
183 public void putMemento(IMemento memento);
186 * Sets the value of the given key to the given string.
189 * @param value the value
191 public void putString(String key, String value);