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  * Interface to a memento used for saving the important state of an object
  19  * in a form that can be persisted in the file system.
  20  * <p>
  21  * Mementos were designed with the following requirements in mind:
  22  * <ol>
  23  *  <li>Certain objects need to be saved and restored across platform sessions.
  24  *    </li>
  25  *  <li>When an object is restored, an appropriate class for an object might not
  26  *    be available. It must be possible to skip an object in this case.</li>
  27  *  <li>When an object is restored, the appropriate class for the object may be
  28  *    different from the one when the object was originally saved. If so, the
  29  *    new class should still be able to read the old form of the data.</li>
  30  * </ol>
  31  * </p>
  32  * <p>
  33  * Mementos meet these requirements by providing support for storing a
  34  * mapping of arbitrary string keys to primitive values, and by allowing
  35  * mementos to have other mementos as children (arranged into a tree).
  36  * A robust external storage format based on XML is used.
  37  * </p><p>
  38  * The key for an attribute may be any alpha numeric value.  However, the
  39  * value of <code>TAG_ID</code> is reserved for internal use.
  40  * </p><p>
  41  * This interface is not intended to be implemented by clients.
  42  * </p>
  43  *
  44  * @see IPersistableElement
  45  * @see IElementFactory
  46  */
  47 public interface IMemento {
  48         /**
  49          * Special reserved key used to store the memento id
  50          * (value <code>"org.eclipse.ui.id"</code>).
  51          *
  52          * @see #getId
  53          */
  54         public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$
  55
  56         /**
  57          * Creates a new child of this memento with the given fType.
  58          * <p>
  59          * The <code>getChild</code> and <code>getChildren</code> methods
  60          * are used to retrieve children of a given fType.
  61          * </p>
  62          *
  63          * @param fType the fType
  64          * @return a new child memento
  65          * @see #getChild
  66          * @see #getChildren
  67          */
  68         public IMemento createChild(String type);
  69
  70         /**
  71          * Creates a new child of this memento with the given fType and id.
  72          * The id is stored in the child memento (using a special reserved
  73          * key, <code>TAG_ID</code>) and can be retrieved using <code>getId</code>.
  74          * <p>
  75          * The <code>getChild</code> and <code>getChildren</code> methods
  76          * are used to retrieve children of a given fType.
  77          * </p>
  78          *
  79          * @param fType the fType
  80          * @param id the child id
  81          * @return a new child memento with the given fType and id
  82          * @see #getId
  83          */
  84         public IMemento createChild(String type, String id);
  85
  86         /**
  87          * Returns the first child with the given fType id.
  88          *
  89          * @param fType the fType id
  90          * @return the first child with the given fType
  91          */
  92         public IMemento getChild(String type);
  93
  94         /**
  95          * Returns all children with the given fType id.
  96          *
  97          * @param fType the fType id
  98          * @return the list of children with the given fType
  99          */
 100         public IMemento[] getChildren(String type);
 101
 102         /**
 103          * Returns the floating point value of the given key.
 104          *
 105          * @param key the key
 106          * @return the value, or <code>null</code> if the key was not found or was found
 107          *   but was not a floating point number
 108          */
 109         public Float getFloat(String key);
 110
 111         /**
 112          * Returns the id for this memento.
 113          *
 114          * @return the memento id, or <code>null</code> if none
 115          * @see #createChild(java.lang.String,java.lang.String)
 116          */
 117         public String getId();
 118
 119         /**
 120          * Returns the name for this memento.
 121          *
 122          * @return the memento name, or <code>null</code> if none
 123          * @see #createChild(java.lang.String,java.lang.String)
 124          */
 125         public String getName();
 126
 127         /**
 128          * Returns the integer value of the given key.
 129          *
 130          * @param key the key
 131          * @return the value, or <code>null</code> if the key was not found or was found
 132          *   but was not an integer
 133          */
 134         public Integer getInteger(String key);
 135
 136         /**
 137          * Returns the string value of the given key.
 138          *
 139          * @param key the key
 140          * @return the value, or <code>null</code> if the key was not found or was found
 141          *  but was not an integer
 142          */
 143         public String getString(String key);
 144
 145         /**
 146          * Returns the boolean value of the given key.
 147          *
 148          * @param key the key
 149          * @return the value, or <code>null</code> if the key was not found or was found
 150          *  but was not a boolean
 151          */
 152         public Boolean getBoolean(String key);
 153
 154         public List getNames();
 155
 156         /**
 157          * Sets the value of the given key to the given floating point number.
 158          *
 159          * @param key the key
 160          * @param value the value
 161          */
 162         public void putFloat(String key, float value);
 163
 164         /**
 165          * Sets the value of the given key to the given integer.
 166          *
 167          * @param key the key
 168          * @param value the value
 169          */
 170         public void putInteger(String key, int value);
 171
 172         /**
 173          * Sets the value of the given key to the given boolean value.
 174          *
 175          * @param key the key
 176          * @param value the value
 177          */
 178         public void putBoolean(String key, boolean value);
 179
 180         /**
 181          * Copy the attributes and children from  <code>memento</code>
 182          * to the receiver.
 183          *
 184          * @param memento the IMemento to be copied.
 185          */
 186         public void putMemento(IMemento memento);
 187
 188         /**
 189          * Sets the value of the given key to the given string.
 190          *
 191          * @param key the key
 192          * @param value the value
 193          */
 194         public void putString(String key, String value);
 195 }