org.eclipse.ui.IMemento Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of workbench Show documentation
This plug-in contains the bulk of the Workbench implementation, and depends on JFace, SWT, and Core Runtime. It cannot be used independently from org.eclipse.ui. Workbench client plug-ins should not depend directly on this plug-in.
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui;

/**
 * Interface to a memento used for saving the important state of an object
 * in a form that can be persisted in the file system.
 * 
 * Mementos were designed with the following requirements in mind:
 * 

 *  Certain objects need to be saved and restored across platform sessions.
 *    
 *  When an object is restored, an appropriate class for an object might not
 *    be available. It must be possible to skip an object in this case.
 *  When an object is restored, the appropriate class for the object may be
 *    different from the one when the object was originally saved. If so, the
 *    new class should still be able to read the old form of the data.
 * 
 * 
 * 
 * Mementos meet these requirements by providing support for storing a
 * mapping of arbitrary string keys to primitive values, and by allowing
 * mementos to have other mementos as children (arranged into a tree).
 * A robust external storage format based on XML is used.
 * 

 * The key for an attribute may be any alpha numeric value.  However, the
 * value of TAG_ID is reserved for internal use.
 * 

 * This interface is not intended to be implemented or extended by clients.
 * 
 *
 * @see IPersistableElement
 * @see IElementFactory
 */
public interface IMemento {
    /**
     * Special reserved key used to store the memento id 
     * (value "IMemento.internal.id").
     *
     * @see #getID()
     */
    public static final String TAG_ID = "IMemento.internal.id"; //$NON-NLS-1$

    /**
     * Creates a new child of this memento with the given type.
     * 
     * The getChild and getChildren methods
     * are used to retrieve children of a given type.
     * 
     *
     * @param type the type
     * @return a new child memento
     * @see #getChild
     * @see #getChildren
     */
    public IMemento createChild(String type);

    /**
     * Creates a new child of this memento with the given type and id.
     * The id is stored in the child memento (using a special reserved
     * key, TAG_ID) and can be retrieved using getId.
     * 
     * The getChild and getChildren methods
     * are used to retrieve children of a given type.
     * 
     *
     * @param type the type
     * @param id the child id
     * @return a new child memento with the given type and id
     * @see #getID
     */
    public IMemento createChild(String type, String id);

    /**
     * Returns the first child with the given type id.
     *
     * @param type the type id
     * @return the first child with the given type
     */
    public IMemento getChild(String type);

    /**
     * Returns all children with the given type id.
     *
     * @param type the type id
     * @return an array of children with the given type
     */
    public IMemento[] getChildren(String type);

    /**
     * Returns the floating point value of the given key.
     *
     * @param key the key
     * @return the value, or null if the key was not found or was found
     *   but was not a floating point number
     */
    public Float getFloat(String key);

    /**
     * Returns the id for this memento.
     *
     * @return the memento id, or null if none
     * @see #createChild(java.lang.String,java.lang.String)
     */
    public String getID();

    /**
     * Returns the integer value of the given key.
     *
     * @param key the key
     * @return the value, or null if the key was not found or was found
     *   but was not an integer
     */
    public Integer getInteger(String key);

    /**
     * Returns the string value of the given key.
     *
     * @param key the key
     * @return the value, or null if the key was not found
     */
    public String getString(String key);

    /**
     * Returns the data of the Text node of the memento. Each memento is allowed
     * only one Text node.
     * 
     * @return the data of the Text node of the memento, or null
     * if the memento has no Text node.
     * @since 2.0
     */
    public String getTextData();

    /**
     * Sets the value of the given key to the given floating point number.
     *
     * @param key the key
     * @param value the value
     */
    public void putFloat(String key, float value);

    /**
     * Sets the value of the given key to the given integer.
     *
     * @param key the key
     * @param value the value
     */
    public void putInteger(String key, int value);

    /**
     * Copy the attributes and children from  memento
     * to the receiver.
     *
     * @param memento the IMemento to be copied.
     */
    public void putMemento(IMemento memento);

    /**
     * Sets the value of the given key to the given string.
     *
     * @param key the key
     * @param value the value
     */
    public void putString(String key, String value);

    /**
     * Sets the memento's Text node to contain the given data. Creates the Text node if
     * none exists. If a Text node does exist, it's current contents are replaced. 
     * Each memento is allowed only one text node.
     * 
     * @param data the data to be placed on the Text node
     * @since 2.0
     */
    public void putTextData(String data);
}