org.eclipse.core.runtime.preferences.AbstractPreferenceStorage Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of aspectjtools Show documentation

AspectJ tools most notably contains the AspectJ compiler (AJC). AJC applies aspects to Java classes during compilation, fully replacing Javac for plain Java classes and also compiling native AspectJ or annotation-based @AspectJ syntax. Furthermore, AJC can weave aspects into existing class files in a post-compile binary weaving step. This library is a superset of AspectJ weaver and hence also of AspectJ runtime.

There is a newer version: 1.9.22.1

Show newest version

/*******************************************************************************
 * 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
 */
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.
	 * 
	 * @param nodePath the absolute path of the preference node
	 * @return a java.util.Properties object or null
	 * @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)
	 * 
	 *
	 * @param nodePath the absolute path of the preference node
	 * @param properties the java.util.Properties 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.
	 *
	 * @param input the stream to load from
	 * @return the java.util.Properties 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.
	 *
	 * @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.
	 *
	 * @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)
	 *
	 * @param nodePath the absolute path of the preference node
	 */
	public abstract void removed(String nodePath);
}