bundles/org.eclipse.jface/src/org/eclipse/jface/dialogs/IDialogSettings.java

/*******************************************************************************
 * Copyright (c) 2000, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.dialogs;

import java.io.*;

/**
 * An interface to a storage mechanism for making dialog settings
 * persistent. The store manages a collection of key/value pairs.
 * The key must be a string and the values can be either, strings or
 * array of strings. Convenience API to convert primitive 
 * types to strings is provided.
 */

public interface IDialogSettings {
/**
 * Create a new section in the receiver and return it.
 *
 * @param name the name of the new section
 * @return the new section
 */
public IDialogSettings addNewSection(String name);
/**
 * Add a section in the receiver.
 *
 * @param section the section to be added
 */
public void addSection(IDialogSettings section);
/**
 * Returns the value of the given key in this dialog settings.
 *
 * @param key the key
 * @return the value, or <code>null</code> if none
 */
public String get(String key);
/**
 * Returns the value, an array of strings, of the given key in 
 * this dialog settings.
 *
 * @param key the key
 * @return the array of string, or <code>null</code> if none
 */
public String[] getArray(String key);
/**
 * Convenience API.
 * Convert the value of the given key in this dialog settings
 * to a boolean and return it.
 *
 * @param key the key
 * @return the boolean value, or <code>false</code> if none
 */
public boolean getBoolean(String key);
/**
 * Convenience API.
 * Convert the value of the given key in this dialog settings
 * to a double and return it.
 *
 * @param key the key
 * @return the value coverted to double, or throws <code>NumberFormatException</code> if none
 *
 * @exception  NumberFormatException  if the string value does not contain a
 *               parsable number.
 * @see        java.lang.Double#valueOf(java.lang.String)
 */
public double getDouble(String key) throws NumberFormatException;
/**
 * Convenience API.
 * Convert the value of the given key in this dialog settings
 * to a float and return it.
 *
 * @param key the key
 * @return the value coverted to float, or throws <code>NumberFormatException</code> if none
 *
 * @exception  NumberFormatException  if the string value does not contain a
 *               parsable number.
 * @see        java.lang.Float#valueOf(java.lang.String)
 */
public float getFloat(String key) throws NumberFormatException;
/**
 * Convenience API.
 * Convert the value of the given key in this dialog settings
 * to a int and return it.
 *
 * @param key the key
 * @return the value coverted to int, or throws <code>NumberFormatException</code> if none
 *
 * @exception  NumberFormatException  if the string value does not contain a
 *               parsable number.
 * @see        java.lang.Integer#valueOf(java.lang.String)
 */
public int getInt(String key) throws NumberFormatException;
/**
 * Convenience API.
 * Convert the value of the given key in this dialog settings
 * to a long and return it.
 *
 * @param key the key
 * @return the value coverted to long, or throws <code>NumberFormatException</code> if none
 *
 * @exception  NumberFormatException  if the string value does not contain a
 *               parsable number.
 * @see        java.lang.Long#valueOf(java.lang.String)
 */
public long getLong(String key) throws NumberFormatException;
/**
 * Returns the IDialogSettings name.
 *
 * @return the name
 */
public String getName();
/**
 * Returns the section with the given name in this dialog settings.
 *
 * @param key the key
 * @return the section, or <code>null</code> if none
 */
public IDialogSettings getSection(String sectionName);
/**
 * Returns all the sections in this dialog settings.
 *
 * @return the section, or <code>null</code> if none
 */
public IDialogSettings[] getSections();
/**
 * Load a dialog settings from a stream and fill the receiver with its
 * content.
 *
 * @param reader a Reader specifying the stream where the settings are read from.
 */
public void load(Reader reader) throws IOException;
/**
 * Load a dialog settings from a file and fill the receiver with its
 * content.
 *
 * @param fileName the name of the file the settings are read from.
 */
public void load(String fileName) throws IOException;
/**
 * Adds the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,String[] value);
/**
 * Convenience API.
 * Converts the double <code>value</code> to a string and adds
 * the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,double value);
/**
 * Convenience API.
 * Converts the float <code>value</code> to a string and adds
 * the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,float value);
/**
 * Convenience API.
 * Converts the int <code>value</code> to a string and adds
 * the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,int value);
/**
 * Convenience API.
 * Converts the long <code>value</code> to a string and adds
 * the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,long value);
/**
 * Adds the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,String value);
/**
 * Convenience API.
 * Converts the boolean <code>value</code> to a string and adds
 * the pair <code>key/value</code> to this dialog settings.
 *
 * @param key the key.
 * @param value the value to be associated with the <code>key</code>
 */
public void put(String key,boolean value);
/**
 * Save a dialog settings to a stream
 *
 * @param writer a Writer specifying the stream the settings are written in.
 */
public void save(Writer writer) throws IOException;
/**
 * Save a dialog settings to a file.
 *
 * @param fileName the name of the file the settings are written in.
 */
public void save(String fileName) throws IOException;
}