util/kvstore/KVStore.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *    http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.util.kvstore;
0019
0020 import java.io.Closeable;
0021 import java.util.Collection;
0022
0023 import org.apache.spark.annotation.Private;
0024
0025 /**
0026  * Abstraction for a local key/value store for storing app data.
0027  *
0028  * <p>
0029  * There are two main features provided by the implementations of this interface:
0030  * </p>
0031  *
0032  * <h3>Serialization</h3>
0033  *
0034  * <p>
0035  * If the underlying data store requires serialization, data will be serialized to and deserialized
0036  * using a {@link KVStoreSerializer}, which can be customized by the application. The serializer is
0037  * based on Jackson, so it supports all the Jackson annotations for controlling the serialization of
0038  * app-defined types.
0039  * </p>
0040  *
0041  * <p>
0042  * Data is also automatically compressed to save disk space.
0043  * </p>
0044  *
0045  * <h3>Automatic Key Management</h3>
0046  *
0047  * <p>
0048  * When using the built-in key management, the implementation will automatically create unique
0049  * keys for each type written to the store. Keys are based on the type name, and always start
0050  * with the "+" prefix character (so that it's easy to use both manual and automatic key
0051  * management APIs without conflicts).
0052  * </p>
0053  *
0054  * <p>
0055  * Another feature of automatic key management is indexing; by annotating fields or methods of
0056  * objects written to the store with {@link KVIndex}, indices are created to sort the data
0057  * by the values of those properties. This makes it possible to provide sorting without having
0058  * to load all instances of those types from the store.
0059  * </p>
0060  *
0061  * <p>
0062  * KVStore instances are thread-safe for both reads and writes.
0063  * </p>
0064  */
0065 @Private
0066 public interface KVStore extends Closeable {
0067
0068   /**
0069    * Returns app-specific metadata from the store, or null if it's not currently set.
0070    *
0071    * <p>
0072    * The metadata type is application-specific. This is a convenience method so that applications
0073    * don't need to define their own keys for this information.
0074    * </p>
0075    */
0076   <T> T getMetadata(Class<T> klass) throws Exception;
0077
0078   /**
0079    * Writes the given value in the store metadata key.
0080    */
0081   void setMetadata(Object value) throws Exception;
0082
0083   /**
0084    * Read a specific instance of an object.
0085    *
0086    * @param naturalKey The object's "natural key", which uniquely identifies it. Null keys
0087    *                   are not allowed.
0088    * @throws java.util.NoSuchElementException If an element with the given key does not exist.
0089    */
0090   <T> T read(Class<T> klass, Object naturalKey) throws Exception;
0091
0092   /**
0093    * Writes the given object to the store, including indexed fields. Indices are updated based
0094    * on the annotated fields of the object's class.
0095    *
0096    * <p>
0097    * Writes may be slower when the object already exists in the store, since it will involve
0098    * updating existing indices.
0099    * </p>
0100    *
0101    * @param value The object to write.
0102    */
0103   void write(Object value) throws Exception;
0104
0105   /**
0106    * Removes an object and all data related to it, like index entries, from the store.
0107    *
0108    * @param type The object's type.
0109    * @param naturalKey The object's "natural key", which uniquely identifies it. Null keys
0110    *                   are not allowed.
0111    * @throws java.util.NoSuchElementException If an element with the given key does not exist.
0112    */
0113   void delete(Class<?> type, Object naturalKey) throws Exception;
0114
0115   /**
0116    * Returns a configurable view for iterating over entities of the given type.
0117    */
0118   <T> KVStoreView<T> view(Class<T> type) throws Exception;
0119
0120   /**
0121    * Returns the number of items of the given type currently in the store.
0122    */
0123   long count(Class<?> type) throws Exception;
0124
0125   /**
0126    * Returns the number of items of the given type which match the given indexed value.
0127    */
0128   long count(Class<?> type, String index, Object indexedValue) throws Exception;
0129
0130   /**
0131    * A cheaper way to remove multiple items from the KVStore
0132    */
0133   <T> boolean removeAllByIndexValues(Class<T> klass, String index, Collection<?> indexValues)
0134       throws Exception;
0135 }