http://www.eclipse.org/platform: Eclipse Preferences Mechanism (Eclipse Foundation) 
Copyright (c) 2011, 2015 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation

/*******************************************************************************
 * Copyright (c) 2011, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.runtime.preferences;

import java.io.*;
import java.util.Properties;
import org.eclipse.core.internal.preferences.PrefsMessages;
import org.osgi.service.prefs.BackingStoreException;


Abstract class which can be used to help provide an alternate storage mechanism
for Eclipse preferences. Clients can over-ride this class and implement the appropriate
methods to read/persist preferences.

Since:3.5
/**
 * Abstract class which can be used to help provide an alternate storage mechanism
 * for Eclipse preferences. Clients can over-ride this class and implement the appropriate
 * methods to read/persist preferences.
 *
 * @since 3.5
 */
public abstract class AbstractPreferenceStorage {

	
Return a java.util.Properties object containing the preference
key/value pairs for the preference node with the specified path, and its children.


The table keys consist of an optional child node path and separator, followed by
the property key. The table values are the values of the properties.



    [childNodePath/]propertyKey=propertyValue




Note: Whether they are absolute or relative, the paths in the returned Properties
object are always interpreted as relative to the node specified by nodePath.



Params:
  • nodePath – the absolute path of the preference node
Throws:
Returns:a java.util.Properties object or null
/**
	 * Return a <code>java.util.Properties</code> object containing the preference
	 * key/value pairs for the preference node with the specified path, and its children.
	 * <p>
	 * The table keys consist of an optional child node path and separator, followed by
	 * the property key. The table values are the values of the properties.
	 * </p>
	 * <pre>
	 *     [childNodePath/]propertyKey=propertyValue
	 * </pre>
	 * <p>
	 * Note: Whether they are absolute or relative, the paths in the returned Properties
	 * object are always interpreted as relative to the node specified by nodePath.
	 * </p>
	 * @param nodePath the absolute path of the preference node
	 * @return a <code>java.util.Properties</code> object or <code>null</code>
	 * @throws BackingStoreException if there was a problem loading the properties
	 */
	public abstract Properties load(String nodePath) throws BackingStoreException;

	
Save the given java.util.Properties object which represents
preference key/value pairs for the preference node represented by the given
path.


Clients are reminded that if the given properties object is empty then
the preference node has been removed and they should react
accordingly (e.g. for instance by removing the file on disk)



Params:
  • nodePath – the absolute path of the preference node
  • properties – the java.util.Properties object to store
Throws:
/**
	 * Save the given <code>java.util.Properties</code> object which represents
	 * preference key/value pairs for the preference node represented by the given
	 * path.
	 * <p>
	 * Clients are reminded that if the given properties object is empty then
	 * the preference node has been removed and they should react
	 * accordingly (e.g. for instance by removing the file on disk)
	 * </p>
	 *
	 * @param nodePath the absolute path of the preference node
	 * @param properties the <code>java.util.Properties</code> object to store
	 * @throws BackingStoreException if there was a problem saving the properties
	 */
	public abstract void save(String nodePath, Properties properties) throws BackingStoreException;

	
Helper method to load a java.util.Properties file from the given
input stream. The stream will be closed on completion of the operation.

Params:
  • input – the stream to load from
Throws:
Returns:the java.util.Properties object loaded from the stream
/**
	 * Helper method to load a <code>java.util.Properties</code> file from the given
	 * input stream. The stream will be closed on completion of the operation.
	 *
	 * @param input the stream to load from
	 * @return the <code>java.util.Properties</code> object loaded from the stream
	 * @throws BackingStoreException if there was a problem loading the file
	 */
	protected Properties loadProperties(InputStream input) throws BackingStoreException {
		Properties result = new Properties();
		try {
			input = new BufferedInputStream(input);
			result.load(input);
		} catch (IOException | IllegalArgumentException e) {
			throw new BackingStoreException(PrefsMessages.preferences_loadProblems, e);
		} finally {
			if (input != null)
				try {
					input.close();
				} catch (IOException e) {
					// ignore
				}
		}
		return result;
	}

	
Helper method to save the given java.util.Properties object
to the given output stream. The stream will be closed at the end of the operation.

Params:
  • output – the stream to store the object to
  • properties – the object to store
Throws:
/**
	 * Helper method to save the given <code>java.util.Properties</code> object
	 * to the given output stream. The stream will be closed at the end of the operation.
	 *
	 * @param output the stream to store the object to
	 * @param properties the object to store
	 * @throws BackingStoreException if there was a problem saving the object
	 */
	protected void saveProperties(OutputStream output, Properties properties) throws BackingStoreException {
		try {
			output = new BufferedOutputStream(output);
			properties.store(output, null);
			output.flush();
		} catch (IOException e) {
			throw new BackingStoreException(PrefsMessages.preferences_saveProblems, e);
		} finally {
			if (output != null)
				try {
					output.close();
				} catch (IOException e) {
					// ignore
				}
		}
	}

	
Return a string array containing the names of the children for the node
with the given path. If there are no children then an empty array is returned.
One example where this method is commonly called, is at the scope root
when discovering the initial children.

Params:
  • nodePath – the path for the preference node
Throws:
Returns:the array of children names
/**
	 * Return a string array containing the names of the children for the node
	 * with the given path. If there are no children then an empty array is returned.
	 * One example where this method is commonly called, is at the scope root
	 * when discovering the initial children.
	 *
	 * @param nodePath the path for the preference node
	 * @return the array of children names
	 * @throws BackingStoreException if there was a problem retrieving the child names
	 */
	public abstract String[] childrenNames(String nodePath) throws BackingStoreException;

	
Callback to inform the client that the preference node with the specified
path has been deleted and the client should react accordingly and make
the appropriate changes to the storage. (e.g. delete the file/information
associated with that node)

Params:
  • nodePath – the absolute path of the preference node
/**
	 * Callback to inform the client that the preference node with the specified
	 * path has been deleted and the client should react accordingly and make
	 * the appropriate changes to the storage. (e.g. delete the file/information
	 * associated with that node)
	 *
	 * @param nodePath the absolute path of the preference node
	 */
	public abstract void removed(String nodePath);
}