View Javadoc

1   /* 
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
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 }