util/kvstore/KVIndex.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.lang.annotation.ElementType;
0021 import java.lang.annotation.Retention;
0022 import java.lang.annotation.RetentionPolicy;
0023 import java.lang.annotation.Target;
0024
0025 import org.apache.spark.annotation.Private;
0026
0027 /**
0028  * Tags a field to be indexed when storing an object.
0029  *
0030  * <p>
0031  * Types are required to have a natural index that uniquely identifies instances in the store.
0032  * The default value of the annotation identifies the natural index for the type.
0033  * </p>
0034  *
0035  * <p>
0036  * Indexes allow for more efficient sorting of data read from the store. By annotating a field or
0037  * "getter" method with this annotation, an index will be created that will provide sorting based on
0038  * the string value of that field.
0039  * </p>
0040  *
0041  * <p>
0042  * Note that creating indices means more space will be needed, and maintenance operations like
0043  * updating or deleting a value will become more expensive.
0044  * </p>
0045  *
0046  * <p>
0047  * Indices are restricted to String, integral types (byte, short, int, long, boolean), and arrays
0048  * of those values.
0049  * </p>
0050  */
0051 @Private
0052 @Retention(RetentionPolicy.RUNTIME)
0053 @Target({ElementType.FIELD, ElementType.METHOD})
0054 public @interface KVIndex {
0055
0056   String NATURAL_INDEX_NAME = "__main__";
0057
0058   /**
0059    * The name of the index to be created for the annotated entity. Must be unique within
0060    * the class. Index names are not allowed to start with an underscore (that's reserved for
0061    * internal use). The default value is the natural index name (which is always a copy index
0062    * regardless of the annotation's values).
0063    */
0064   String value() default NATURAL_INDEX_NAME;
0065
0066   /**
0067    * The name of the parent index of this index. By default there is no parent index, so the
0068    * generated data can be retrieved without having to provide a parent value.
0069    *
0070    * <p>
0071    * If a parent index is defined, iterating over the data using the index will require providing
0072    * a single value for the parent index. This serves as a rudimentary way to provide relationships
0073    * between entities in the store.
0074    * </p>
0075    */
0076   String parent() default "";
0077
0078   /**
0079    * Whether to copy the instance's data to the index, instead of just storing a pointer to the
0080    * data. The default behavior is to just store a reference; that saves disk space but is slower
0081    * to read, since there's a level of indirection.
0082    */
0083   boolean copy() default false;
0084
0085 }