001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.jetspeed.prefs;
018:
019: import java.util.Collection;
020: import java.util.prefs.Preferences;
021:
022: import org.apache.jetspeed.prefs.om.Node;
023: import org.apache.jetspeed.prefs.om.Property;
024:
025: /**
026: * <p>
027: * Utility component used to pass the {@link PersistenceStoreContainer} and
028: * store name to the {@link Preferences} SPI implementation.
029: * </p>
030: *
031: * @author <a href="mailto:dlestrat@apache.org">David Le Strat</a>
032: */
033: public interface PreferencesProvider {
034: /**
035: * Given the fullpath to a node, retrieve the node associated with the node path
036: *
037: * @param fullPath the full path to the node such as "/portlet_entity/dp-1/guest/preferences/mypref"
038: * @param nodeType either System or User node type. A value of 0 is User, a value of 1 is System
039: * @return The Preference Node found when found
040: * @throws NodeDoesNotExistException when a node is not found, an exception is thrown
041: */
042: Node getNode(String fullPath, int nodeType)
043: throws NodeDoesNotExistException;
044:
045: /**
046: * Check for the existence of a node given the full path to the node
047: *
048: * @param fullPath the full path to the node such as "/portlet_entity/dp-1/guest/preferences/mypref"
049: * @param nodeType either System or User node type. A value of 0 is User, a value of 1 is System
050: * @return true if the node exists, false if it does not exist
051: */
052: boolean nodeExists(String fullPath, int nodeType);
053:
054: /**
055: * Create a preferences node given the following parameters. Will throw an exception if the node already exists.
056: *
057: * @param parent the existing parent node of this node to be created
058: * @param nodeName the name of the node, which should be the same value as the last value of the full path
059: * for example when the full path is "/portlet_entity/dp-1", the nodeName will be "dp-1"
060: * @param nodeType either System or User node type. A value of 0 is User, a value of 1 is System
061: * @param fullPath the full path to the node such as "/portlet_entity/dp-1/guest/preferences/mypref"
062: * @return the newly created node on success
063: * @throws FailedToCreateNodeException thrown when the node fails to create
064: * @throws NodeAlreadyExistsException thrown when a node already exists at the given full path
065: */
066: Node createNode(Node parent, String nodeName, int nodeType,
067: String fullPath) throws FailedToCreateNodeException,
068: NodeAlreadyExistsException;
069:
070: /**
071: * Create a property on the given node.
072: * @param node the node to have a property added to it
073: * @param name the name of the property to add to the node
074: * @param value the value of the property to add to the node
075: * @return the newly created property
076: * @since 2.1.2
077: */
078: Property createProperty(Node node, String name, Object value);
079:
080: /**
081: * Given a parent node, return a flat collection of immediate children of this node
082: *
083: * @param parentNode the parent node to be searched for children
084: * @return a Java collection of immediate children of this node
085: */
086: Collection getChildren(Node parentNode);
087:
088: /**
089: * Stores a preference node to the backing preferences persistent storage.
090: * If the node does not exist, it is created. If it does exist, the node
091: * is updated.
092: *
093: * @param node the node to be stored.
094: */
095: void storeNode(Node node);
096:
097: /**
098: * Removes a node from a given parent node, also removing the node from the preferences persistence store.
099: *
100: * @param parentNode the parent of the node to be deleted
101: * @param node the node to be deleted
102: */
103: void removeNode(Node parentNode, Node node);
104:
105: /**
106: * Lookup a preference node given the preference name, a property name and
107: * value. Options can be set to null if you dont want them included in the
108: * query.
109: *
110: * @param nodeName the name of the node to lookup, such as 'userinfo'
111: * @param propertyName the name of the property, such as 'user.email'
112: * @param propertyValue the value of the property, such as
113: * 'taylor@apache.org'
114: * @return a collection of found matching elements of type <code>Node</code>
115: */
116: Collection lookupPreference(String nodeName, String propertyName,
117: String propertyValue);
118:
119: /**
120: * Initializes the preferences node
121: *
122: * @throws Exception
123: */
124: void init() throws Exception;
125: }
|