1 /******************************************************************************* 2 * Copyright (c) 2000, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.ui; 15 16 import org.w3c.dom.DOMException; 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 * </p> 24 * <ol> 25 * <li>Certain objects need to be saved and restored across platform 26 * sessions.</li> 27 * <li>When an object is restored, an appropriate class for an object might not 28 * be available. It must be possible to skip an object in this case.</li> 29 * <li>When an object is restored, the appropriate class for the object may be 30 * different from the one when the object was originally saved. If so, the new 31 * class should still be able to read the old form of the data.</li> 32 * </ol> 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 that doesn't start 41 * with a number. eg: [A-Za-z][A-Za-z0-9]* Using '.' is unsupported. However, 42 * the value of <code>TAG_ID</code> is reserved for internal use. 43 * </p> 44 * <p> 45 * The default implementation can throw a {@link DOMException} for createChild 46 * and put operations. See {@link XMLMemento}. 47 * </p> 48 * <p> 49 * This interface is not intended to be implemented or extended by clients. 50 * </p> 51 * 52 * @see IPersistableElement 53 * @see IElementFactory 54 * @see XMLMemento 55 * @noimplement This interface is not intended to be implemented by clients. 56 */ 57 public interface IMemento { 58 /** 59 * Special reserved key used to store the memento id (value 60 * <code>"IMemento.internal.id"</code>). 61 * 62 * @see #getID() 63 */ 64 String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$ 65 66 /** 67 * Creates a new child of this memento with the given type. 68 * <p> 69 * The <code>getChild</code> and <code>getChildren</code> methods are used to 70 * retrieve children of a given type. 71 * </p> 72 * 73 * @param type the type 74 * @return a new child memento 75 * @see #getChild 76 * @see #getChildren 77 */ createChild(String type)78 IMemento createChild(String type); 79 80 /** 81 * Creates a new child of this memento with the given type and id. The id is 82 * stored in the child memento (using a special reserved key, 83 * <code>TAG_ID</code>) and can be retrieved using <code>getId</code>. 84 * <p> 85 * The <code>getChild</code> and <code>getChildren</code> methods are used to 86 * retrieve children of a given type. 87 * </p> 88 * 89 * @param type the type 90 * @param id the child id 91 * @return a new child memento with the given type and id 92 * @see #getID 93 */ createChild(String type, String id)94 IMemento createChild(String type, String id); 95 96 /** 97 * Returns the first child with the given type id. 98 * 99 * @param type the type id 100 * @return the first child with the given type. May return <code>null</code> . 101 */ getChild(String type)102 IMemento getChild(String type); 103 104 /** 105 * Returns all children of this node. 106 * 107 * @return an array of children of this node. This will not be 108 * <code>null</code>. If there are no children, an array of length zero 109 * will be returned. 110 * @since 3.8 111 */ getChildren()112 IMemento[] getChildren(); 113 114 /** 115 * Returns all children with the given type id. 116 * 117 * @param type the type id 118 * @return an array of children with the given type. This will not be 119 * <code>null</code>. If there are no keys, an array of length zero will 120 * be returned. 121 */ getChildren(String type)122 IMemento[] getChildren(String type); 123 124 /** 125 * Returns the floating point 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 a floating point number 130 */ getFloat(String key)131 Float getFloat(String key); 132 133 /** 134 * Returns the type for this memento. 135 * 136 * @return the memento type 137 * @see #createChild(java.lang.String) 138 * @see #createChild(java.lang.String,java.lang.String) 139 * @since 3.4 140 */ getType()141 String getType(); 142 143 /** 144 * Returns the id for this memento. 145 * 146 * @return the memento id, or <code>null</code> if none 147 * @see #createChild(java.lang.String,java.lang.String) 148 */ getID()149 String getID(); 150 151 /** 152 * Returns the integer value of the given key. 153 * 154 * @param key the key 155 * @return the value, or <code>null</code> if the key was not found or was found 156 * but was not an integer 157 */ getInteger(String key)158 Integer getInteger(String key); 159 160 /** 161 * Returns the string value of the given key. 162 * 163 * @param key the key 164 * @return the value, or <code>null</code> if the key was not found 165 */ getString(String key)166 String getString(String key); 167 168 /** 169 * Returns the boolean value of the given key. 170 * 171 * @param key the key 172 * @return the value, or <code>null</code> if the key was not found 173 * @since 3.4 174 */ getBoolean(String key)175 Boolean getBoolean(String key); 176 177 /** 178 * Returns the data of the Text node of the memento. Each memento is allowed 179 * only one Text node. 180 * 181 * @return the data of the Text node of the memento, or <code>null</code> if the 182 * memento has no Text node. 183 * @since 2.0 184 */ getTextData()185 String getTextData(); 186 187 /** 188 * Returns an array of all the attribute keys of the memento. This will not be 189 * <code>null</code>. If there are no keys, an array of length zero will be 190 * returned. 191 * 192 * @return an array with all the attribute keys of the memento 193 * @since 3.4 194 */ getAttributeKeys()195 String[] getAttributeKeys(); 196 197 /** 198 * Sets the value of the given key to the given floating point number. 199 * 200 * @param key the key 201 * @param value the value 202 */ putFloat(String key, float value)203 void putFloat(String key, float value); 204 205 /** 206 * Sets the value of the given key to the given integer. 207 * 208 * @param key the key 209 * @param value the value 210 */ putInteger(String key, int value)211 void putInteger(String key, int value); 212 213 /** 214 * Copy the attributes and children from <code>memento</code> to the receiver. 215 * 216 * @param memento the IMemento to be copied. 217 */ putMemento(IMemento memento)218 void putMemento(IMemento memento); 219 220 /** 221 * Sets the value of the given key to the given string. 222 * 223 * @param key the key 224 * @param value the value 225 */ putString(String key, String value)226 void putString(String key, String value); 227 228 /** 229 * Sets the value of the given key to the given boolean value. 230 * 231 * @param key the key 232 * @param value the value 233 * @since 3.4 234 */ putBoolean(String key, boolean value)235 void putBoolean(String key, boolean value); 236 237 /** 238 * Sets the memento's Text node to contain the given data. Creates the Text node 239 * if none exists. If a Text node does exist, it's current contents are 240 * replaced. Each memento is allowed only one text node. 241 * 242 * @param data the data to be placed on the Text node 243 * @since 2.0 244 */ putTextData(String data)245 void putTextData(String data); 246 } 247