Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 13a0d3737a9004b2904a792387aa698c6ed2b2b3 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
/*******************************************************************************
 * 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 <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 <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 <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 <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.
	 *
	 * @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);
}

Back to the top