1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.jetspeed.prefs;
18
19 import java.util.Collection;
20 import java.util.prefs.Preferences;
21
22 import org.apache.jetspeed.prefs.om.Node;
23 import org.apache.jetspeed.prefs.om.Property;
24
25 /***
26 * <p>
27 * Utility component used to pass the {@link PersistenceStoreContainer} and
28 * store name to the {@link Preferences} SPI implementation.
29 * </p>
30 *
31 * @author <a href="mailto:dlestrat@apache.org">David Le Strat</a>
32 */
33 public interface PreferencesProvider
34 {
35 /***
36 * Given the fullpath to a node, retrieve the node associated with the node path
37 *
38 * @param fullPath the full path to the node such as "/portlet_entity/dp-1/guest/preferences/mypref"
39 * @param nodeType either System or User node type. A value of 0 is User, a value of 1 is System
40 * @return The Preference Node found when found
41 * @throws NodeDoesNotExistException when a node is not found, an exception is thrown
42 */
43 Node getNode(String fullPath, int nodeType) throws NodeDoesNotExistException;
44
45 /***
46 * Check for the existence of a node given the full path to the node
47 *
48 * @param fullPath the full path to the node such as "/portlet_entity/dp-1/guest/preferences/mypref"
49 * @param nodeType either System or User node type. A value of 0 is User, a value of 1 is System
50 * @return true if the node exists, false if it does not exist
51 */
52 boolean nodeExists(String fullPath, int nodeType);
53
54 /***
55 * Create a preferences node given the following parameters. Will throw an exception if the node already exists.
56 *
57 * @param parent the existing parent node of this node to be created
58 * @param nodeName the name of the node, which should be the same value as the last value of the full path
59 * for example when the full path is "/portlet_entity/dp-1", the nodeName will be "dp-1"
60 * @param nodeType either System or User node type. A value of 0 is User, a value of 1 is System
61 * @param fullPath the full path to the node such as "/portlet_entity/dp-1/guest/preferences/mypref"
62 * @return the newly created node on success
63 * @throws FailedToCreateNodeException thrown when the node fails to create
64 * @throws NodeAlreadyExistsException thrown when a node already exists at the given full path
65 */
66 Node createNode(Node parent, String nodeName, int nodeType, String fullPath) throws FailedToCreateNodeException,
67 NodeAlreadyExistsException;
68
69 /***
70 * Create a property on the given node.
71 * @param node the node to have a property added to it
72 * @param name the name of the property to add to the node
73 * @param value the value of the property to add to the node
74 * @return the newly created property
75 * @since 2.1.2
76 */
77 Property createProperty(Node node, String name, Object value);
78
79 /***
80 * Given a parent node, return a flat collection of immediate children of this node
81 *
82 * @param parentNode the parent node to be searched for children
83 * @return a Java collection of immediate children of this node
84 */
85 Collection getChildren(Node parentNode);
86
87 /***
88 * Stores a preference node to the backing preferences persistent storage.
89 * If the node does not exist, it is created. If it does exist, the node
90 * is updated.
91 *
92 * @param node the node to be stored.
93 */
94 void storeNode(Node node);
95
96 /***
97 * Removes a node from a given parent node, also removing the node from the preferences persistence store.
98 *
99 * @param parentNode the parent of the node to be deleted
100 * @param node the node to be deleted
101 */
102 void removeNode(Node parentNode, Node node);
103
104 /***
105 * Lookup a preference node given the preference name, a property name and
106 * value. Options can be set to null if you dont want them included in the
107 * query.
108 *
109 * @param nodeName the name of the node to lookup, such as 'userinfo'
110 * @param propertyName the name of the property, such as 'user.email'
111 * @param propertyValue the value of the property, such as
112 * 'taylor@apache.org'
113 * @return a collection of found matching elements of type <code>Node</code>
114 */
115 Collection lookupPreference(String nodeName, String propertyName, String propertyValue);
116
117 /***
118 * Initializes the preferences node
119 *
120 * @throws Exception
121 */
122 void init() throws Exception;
123 }