archive/net.sourceforge.phpeclipse.wiki/src/net/sourceforge/phpeclipse/wiki/internal/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.phpeclipse.wiki.internal;
  12
  13 import java.util.List;
  14 /**
  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.
  17  * <p>
  18  * Mementos were designed with the following requirements in mind:
  19  * <ol>
  20  *  <li>Certain objects need to be saved and restored across platform sessions.
  21  *    </li>
  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>
  27  * </ol>
  28  * </p>
  29  * <p>
  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.
  34  * </p><p>
  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.
  37  * </p><p>
  38  * This interface is not intended to be implemented by clients.
  39  * </p>
  40  *
  41  * @see IPersistableElement
  42  * @see IElementFactory
  43  */
  44 public interface IMemento {
  45         /**
  46          * Special reserved key used to store the memento id
  47          * (value <code>"org.eclipse.ui.id"</code>).
  48          *
  49          * @see #getId
  50          */
  51         public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$
  52
  53         /**
  54          * Creates a new child of this memento with the given fType.
  55          * <p>
  56          * The <code>getChild</code> and <code>getChildren</code> methods
  57          * are used to retrieve children of a given fType.
  58          * </p>
  59          *
  60          * @param fType the fType
  61          * @return a new child memento
  62          * @see #getChild
  63          * @see #getChildren
  64          */
  65         public IMemento createChild(String type);
  66
  67         /**
  68          * Creates a new child of this memento with the given fType 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>.
  71          * <p>
  72          * The <code>getChild</code> and <code>getChildren</code> methods
  73          * are used to retrieve children of a given fType.
  74          * </p>
  75          *
  76          * @param fType the fType
  77          * @param id the child id
  78          * @return a new child memento with the given fType and id
  79          * @see #getId
  80          */
  81         public IMemento createChild(String type, String id);
  82
  83         /**
  84          * Returns the first child with the given fType id.
  85          *
  86          * @param fType the fType id
  87          * @return the first child with the given fType
  88          */
  89         public IMemento getChild(String type);
  90
  91         /**
  92          * Returns all children with the given fType id.
  93          *
  94          * @param fType the fType id
  95          * @return the list of children with the given fType
  96          */
  97         public IMemento[] getChildren(String type);
  98
  99         /**
 100          * Returns the floating point value of the given key.
 101          *
 102          * @param key the 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
 105          */
 106         public Float getFloat(String key);
 107
 108         /**
 109          * Returns the id for this memento.
 110          *
 111          * @return the memento id, or <code>null</code> if none
 112          * @see #createChild(java.lang.String,java.lang.String)
 113          */
 114         public String getId();
 115
 116         /**
 117          * Returns the name for this memento.
 118          *
 119          * @return the memento name, or <code>null</code> if none
 120          * @see #createChild(java.lang.String,java.lang.String)
 121          */
 122         public String getName();
 123
 124         /**
 125          * Returns the integer 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 an integer
 130          */
 131         public Integer getInteger(String key);
 132
 133         /**
 134          * Returns the string value of the given key.
 135          *
 136          * @param key the key
 137          * @return the value, or <code>null</code> if the key was not found or was found
 138          *  but was not an integer
 139          */
 140         public String getString(String key);
 141
 142         /**
 143          * Returns the boolean value of the given key.
 144          *
 145          * @param key the key
 146          * @return the value, or <code>null</code> if the key was not found or was found
 147          *  but was not a boolean
 148          */
 149         public Boolean getBoolean(String key);
 150
 151         public List getNames();
 152
 153         /**
 154          * Sets the value of the given key to the given floating point number.
 155          *
 156          * @param key the key
 157          * @param value the value
 158          */
 159         public void putFloat(String key, float value);
 160
 161         /**
 162          * Sets the value of the given key to the given integer.
 163          *
 164          * @param key the key
 165          * @param value the value
 166          */
 167         public void putInteger(String key, int value);
 168
 169         /**
 170          * Sets the value of the given key to the given boolean value.
 171          *
 172          * @param key the key
 173          * @param value the value
 174          */
 175         public void putBoolean(String key, boolean value);
 176
 177         /**
 178          * Copy the attributes and children from  <code>memento</code>
 179          * to the receiver.
 180          *
 181          * @param memento the IMemento to be copied.
 182          */
 183         public void putMemento(IMemento memento);
 184
 185         /**
 186          * Sets the value of the given key to the given string.
 187          *
 188          * @param key the key
 189          * @param value the value
 190          */
 191         public void putString(String key, String value);
 192 }