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.phpdt.httpquery.config; 12 13 import java.util.List; 14 15 import org.eclipse.ui.IElementFactory; 16 import org.eclipse.ui.IPersistableElement; 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 * <ol> 24 * <li>Certain objects need to be saved and restored across platform sessions. 25 * </li> 26 * <li>When an object is restored, an appropriate class for an object might not 27 * be available. It must be possible to skip an object in this case.</li> 28 * <li>When an object is restored, the appropriate class for the object may be 29 * different from the one when the object was originally saved. If so, the new 30 * class should still be able to read the old form of the data.</li> 31 * </ol> 32 * </p> 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. However, the value 41 * of <code>TAG_ID</code> is reserved for internal use. 42 * </p> 43 * <p> 44 * This interface is not intended to be implemented by clients. 45 * </p> 46 * 47 * @see IPersistableElement 48 * @see IElementFactory 49 */ 50 public interface IMemento { 51 /** 52 * Special reserved key used to store the memento id (value 53 * <code>"org.eclipse.ui.id"</code>). 54 * 55 * @see #getId 56 */ 57 public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$ 58 59 /** 60 * Creates a new child of this memento with the given fType. 61 * <p> 62 * The <code>getChild</code> and <code>getChildren</code> methods are 63 * used to retrieve children of a given fType. 64 * </p> 65 * 66 * @param fType 67 * the fType 68 * @return a new child memento 69 * @see #getChild 70 * @see #getChildren 71 */ createChild(String type)72 public IMemento createChild(String type); 73 74 /** 75 * Creates a new child of this memento with the given fType and id. The id 76 * is stored in the child memento (using a special reserved key, 77 * <code>TAG_ID</code>) and can be retrieved using <code>getId</code>. 78 * <p> 79 * The <code>getChild</code> and <code>getChildren</code> methods are 80 * used to retrieve children of a given fType. 81 * </p> 82 * 83 * @param fType 84 * the fType 85 * @param id 86 * the child id 87 * @return a new child memento with the given fType and id 88 * @see #getId 89 */ createChild(String type, String id)90 public IMemento createChild(String type, String id); 91 92 /** 93 * Returns the first child with the given fType id. 94 * 95 * @param fType 96 * the fType id 97 * @return the first child with the given fType 98 */ getChild(String type)99 public IMemento getChild(String type); 100 101 /** 102 * Returns all children with the given fType id. 103 * 104 * @param fType 105 * the fType id 106 * @return the list of children with the given fType 107 */ getChildren(String type)108 public IMemento[] getChildren(String type); 109 110 /** 111 * Returns the floating point value of the given key. 112 * 113 * @param key 114 * the key 115 * @return the value, or <code>null</code> if the key was not found or was 116 * found but was not a floating point number 117 */ getFloat(String key)118 public Float getFloat(String key); 119 120 /** 121 * Returns the id for this memento. 122 * 123 * @return the memento id, or <code>null</code> if none 124 * @see #createChild(java.lang.String,java.lang.String) 125 */ getId()126 public String getId(); 127 128 /** 129 * Returns the name for this memento. 130 * 131 * @return the memento name, or <code>null</code> if none 132 * @see #createChild(java.lang.String,java.lang.String) 133 */ getName()134 public String getName(); 135 136 /** 137 * Returns the integer value of the given key. 138 * 139 * @param key 140 * the key 141 * @return the value, or <code>null</code> if the key was not found or was 142 * found but was not an integer 143 */ getInteger(String key)144 public Integer getInteger(String key); 145 146 /** 147 * Returns the string value of the given key. 148 * 149 * @param key 150 * the key 151 * @return the value, or <code>null</code> if the key was not found or was 152 * found but was not an integer 153 */ getString(String key)154 public String getString(String key); 155 156 /** 157 * Returns the boolean value of the given key. 158 * 159 * @param key 160 * the key 161 * @return the value, or <code>null</code> if the key was not found or was 162 * found but was not a boolean 163 */ getBoolean(String key)164 public Boolean getBoolean(String key); 165 getNames()166 public List getNames(); 167 168 /** 169 * Sets the value of the given key to the given floating point number. 170 * 171 * @param key 172 * the key 173 * @param value 174 * the value 175 */ putFloat(String key, float value)176 public void putFloat(String key, float value); 177 178 /** 179 * Sets the value of the given key to the given integer. 180 * 181 * @param key 182 * the key 183 * @param value 184 * the value 185 */ putInteger(String key, int value)186 public void putInteger(String key, int value); 187 188 /** 189 * Sets the value of the given key to the given boolean value. 190 * 191 * @param key 192 * the key 193 * @param value 194 * the value 195 */ putBoolean(String key, boolean value)196 public void putBoolean(String key, boolean value); 197 198 /** 199 * Copy the attributes and children from <code>memento</code> to the 200 * receiver. 201 * 202 * @param memento 203 * the IMemento to be copied. 204 */ putMemento(IMemento memento)205 public void putMemento(IMemento memento); 206 207 /** 208 * Sets the value of the given key to the given string. 209 * 210 * @param key 211 * the key 212 * @param value 213 * the value 214 */ putString(String key, String value)215 public void putString(String key, String value); 216 }