View Javadoc

1   /*
2    * Copyright 2006 University Corporation for Advanced Internet Development, Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.opensaml.util.storage;
18  
19  import java.util.Iterator;
20  
21  /**
22   * Generic data storage facility for use by services that require some degree of persistence.
23   * 
24   * The storage service is partitioned. This is to allow different objects to use the service, each with its own
25   * partition, without the worry of conflicting keys.
26   * 
27   * @param <KeyType> object type of the keys
28   * @param <ValueType> object type of the values
29   */
30  public interface StorageService<KeyType, ValueType> {
31  
32      /**
33       * Checks if a given key exists.
34       * 
35       * @param partition partition on which to operate
36       * @param key the key to check
37       * 
38       * @return true of the given key exists, false if not
39       */
40      public boolean contains(String partition, KeyType key);
41  
42      /**
43       * Gets the partitions within the service. Removal of a partition identifier from the iterator removes the partition
44       * from the storage service.
45       * 
46       * @return partitions within the service
47       */
48      public Iterator<String> getPartitions();
49  
50      /**
51       * Gets the keys for entries in the storage service. Removal of a key from the iterator removes the the key and
52       * associated value from the store.
53       * 
54       * <strong>Note:</strong> this operation may be very expensive
55       * 
56       * @param partition partition on which to operate
57       * 
58       * @return list of keys currently within the store
59       */
60      public Iterator<KeyType> getKeys(String partition);
61  
62      /**
63       * Gets the value stored under a particular key.
64       * 
65       * @param partition partition on which to operate
66       * @param key the key
67       * 
68       * @return the value for that key, or null if there is no value for the given key
69       */
70      public ValueType get(String partition, KeyType key);
71  
72      /**
73       * Adds a value, indexed by a key, in to storage. Note that implementations of this service may determine, on its
74       * own, when to evict items from storage, the expiration time given here is meant only as a system provided hint.
75       * 
76       * @param partition partition on which to operate
77       * @param key the key
78       * @param value the value
79       * 
80       * @return the value that was registered under that key previously, if there was a previous value
81       */
82      public ValueType put(String partition, KeyType key, ValueType value);
83  
84      /**
85       * Removes an item from storage.
86       * 
87       * @param partition partition on which to operate
88       * @param key the key to the value to remove
89       * 
90       * @return the value that was removed
91       */
92      public ValueType remove(String partition, KeyType key);
93  }