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.Collection;
20  import java.util.Iterator;
21  
22  /**
23   * Generic data storage facility for use by services that require some degree of persistence.
24   * 
25   * The storage service is partitioned. This is to allow different objects to use the service, each with its own
26   * partition, without the worry of conflicting keys.
27   * 
28   * @param <KeyType> object type of the keys
29   * @param <ValueType> object type of the values
30   */
31  public interface StorageService<KeyType, ValueType> {
32  
33      /**
34       * Checks if a given key exists.
35       * 
36       * @param partition partition on which to operate
37       * @param key the key to check
38       * 
39       * @return true of the given key exists, false if not
40       */
41      public boolean contains(String partition, KeyType key);
42  
43      /**
44       * Gets the partitions within the service. Removal of a partition identifier from the iterator removes the partition
45       * from the storage service.
46       * 
47       * @return partitions within the service
48       */
49      public Iterator<String> getPartitions();
50  
51      /**
52       * Gets the keys for entries in the storage service. Removal of a key from the iterator removes the the key and
53       * associated value from the store.
54       * 
55       * <strong>Note:</strong> this operation may be very expensive
56       * 
57       * @param partition partition on which to operate
58       * 
59       * @return list of keys currently within the store
60       */
61      public Iterator<KeyType> getKeys(String partition);
62  
63      /**
64       * Gets the value stored under a particular key.
65       * 
66       * @param partition partition on which to operate
67       * @param key the key
68       * 
69       * @return the value for that key, or null if there is no value for the given key
70       */
71      public ValueType get(String partition, KeyType key);
72  
73      /**
74       * Adds a value, indexed by a key, in to storage. Note that implementations of this service may determine, on its
75       * own, when to evict items from storage, the expiration time given here is meant only as a system provided hint.
76       * 
77       * @param partition partition on which to operate
78       * @param key the key
79       * @param value the value
80       * 
81       * @return the value that was registered under that key previously, if there was a previous value
82       */
83      public ValueType put(String partition, KeyType key, ValueType value);
84  
85      /**
86       * Removes an item from storage.
87       * 
88       * @param partition partition on which to operate
89       * @param key the key to the value to remove
90       * 
91       * @return the value that was removed
92       */
93      public ValueType remove(String partition, KeyType key);
94  }