net.sourceforge.phpeclipse.phphelp/src/net/sourceforge/phpdt/httpquery/config/IMemento.java

   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          */
  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          */
  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          */
  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          */
 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          */
 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          */
 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          */
 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          */
 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          */
 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          */
 164         public Boolean getBoolean(String key);
 165
 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          */
 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          */
 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          */
 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          */
 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          */
 215         public void putString(String key, String value);
 216 }