| /** |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.gora.store; |
| |
| import java.io.Closeable; |
| import java.io.DataInput; |
| import java.io.DataOutput; |
| import java.io.IOException; |
| import java.util.List; |
| import java.util.Properties; |
| |
| import org.apache.gora.persistency.BeanFactory; |
| import org.apache.gora.persistency.Persistent; |
| import org.apache.gora.query.PartitionQuery; |
| import org.apache.gora.query.Query; |
| import org.apache.gora.query.Result; |
| import org.apache.hadoop.conf.Configurable; |
| import org.apache.hadoop.conf.Configuration; |
| import org.apache.hadoop.io.Writable; |
| |
| /** |
| * DataStore handles actual object persistence. Objects can be persisted, |
| * fetched, queried or deleted by the DataStore methods. DataStores can be |
| * constructed by an instance of {@link DataStoreFactory}. |
| * |
| * <p> DataStores implementations should be thread safe. |
| * <p><a name="visibility"><b>Note:</b> Results of updates ({@link #put(Object, Persistent)}, |
| * {@link #delete(Object)} and {@link #deleteByQuery(Query)} operations) are |
| * guaranteed to be visible to subsequent get / execute operations ONLY |
| * after a subsequent call to {@link #flush()}. |
| * @param <K> the class of keys in the datastore |
| * @param <T> the class of persistent objects in the datastore |
| */ |
| public interface DataStore<K, T extends Persistent> extends Closeable, |
| Writable, Configurable { |
| |
| /** |
| * Initializes this DataStore. |
| * @param keyClass the class of the keys |
| * @param persistentClass the class of the persistent objects |
| * @param properties extra metadata |
| * @throws IOException |
| */ |
| void initialize(Class<K> keyClass, Class<T> persistentClass, |
| Properties properties) throws IOException; |
| |
| /** |
| * Sets the class of the keys |
| * @param keyClass the class of keys |
| */ |
| void setKeyClass(Class<K> keyClass); |
| |
| /** |
| * Returns the class of the keys |
| * @return class of the keys |
| */ |
| Class<K> getKeyClass(); |
| |
| /** |
| * Sets the class of the persistent objects |
| * @param persistentClass class of persistent objects |
| */ |
| void setPersistentClass(Class<T> persistentClass); |
| |
| /** |
| * Returns the class of the persistent objects |
| * @return class of the persistent objects |
| */ |
| Class<T> getPersistentClass(); |
| |
| /** |
| * Returns the schema name given to this DataStore |
| * @return schema name |
| */ |
| String getSchemaName(); |
| |
| /** |
| * Creates the optional schema or table (or similar) in the datastore |
| * to hold the objects. If the schema is already created previously, |
| * or the underlying data model does not support |
| * or need this operation, the operation is ignored. |
| */ |
| void createSchema() throws IOException; |
| |
| /** |
| * Deletes the underlying schema or table (or similar) in the datastore |
| * that holds the objects. This also deletes all the data associated with |
| * the schema. |
| */ |
| void deleteSchema() throws IOException; |
| |
| /** |
| * Deletes all the data associated with the schema, but keeps the |
| * schema (table or similar) intact. |
| */ |
| void truncateSchema() throws IOException; |
| |
| /** |
| * Returns whether the schema that holds the data exists in the datastore. |
| * @return whether schema exists |
| */ |
| boolean schemaExists() throws IOException; |
| |
| /** |
| * Returns a new instance of the key object. If the object cannot be instantiated |
| * (it the class is a Java primitive wrapper, or does not have no-arg |
| * constructor) it throws an exception. Only use this function if you can |
| * make sure that the key class has a no-arg constructor. |
| * @return a new instance of the key object. |
| */ |
| K newKey() throws IOException; |
| |
| /** |
| * Returns a new instance of the managed persistent object. |
| * @return a new instance of the managed persistent object. |
| */ |
| T newPersistent() throws IOException; |
| |
| /** |
| * Returns the object corresponding to the given key fetching all the fields. |
| * @param key the key of the object |
| * @return the Object corresponding to the key or null if it cannot be found |
| */ |
| T get(K key) throws IOException; |
| |
| /** |
| * Returns the object corresponding to the given key. |
| * @param key the key of the object |
| * @param fields the fields required in the object. Pass null, to retrieve all fields |
| * @return the Object corresponding to the key or null if it cannot be found |
| */ |
| T get(K key, String[] fields) throws IOException; |
| |
| /** |
| * Inserts the persistent object with the given key. If an |
| * object with the same key already exists it will silently |
| * be replaced. See also the note on |
| * <a href="#visibility">visibility</a>. |
| */ |
| void put(K key, T obj) throws IOException; |
| |
| /** |
| * Deletes the object with the given key |
| * @param key the key of the object |
| * @return whether the object was successfully deleted |
| */ |
| boolean delete(K key) throws IOException; |
| |
| /** |
| * Deletes all the objects matching the query. |
| * See also the note on <a href="#visibility">visibility</a>. |
| * @param query matching records to this query will be deleted |
| * @return number of deleted records |
| */ |
| long deleteByQuery(Query<K, T> query) throws IOException; |
| |
| /** |
| * Executes the given query and returns the results. |
| * @param query the query to execute. |
| * @return the results as a {@link Result} object. |
| */ |
| Result<K,T> execute(Query<K, T> query) throws IOException; |
| |
| /** |
| * Constructs and returns a new Query. |
| * @return a new Query. |
| */ |
| Query<K, T> newQuery(); |
| |
| /** |
| * Partitions the given query and returns a list of {@link PartitionQuery}s, |
| * which will execute on local data. |
| * @param query the base query to create the partitions for. If the query |
| * is null, then the data store returns the partitions for the default query |
| * (returning every object) |
| * @return a List of PartitionQuery's |
| */ |
| List<PartitionQuery<K,T>> getPartitions(Query<K,T> query) |
| throws IOException; |
| |
| /** |
| * Forces the write caches to be flushed. DataStore implementations may |
| * optimize their writing by deferring the actual put / delete operations |
| * until this moment. |
| * See also the note on <a href="#visibility">visibility</a>. |
| */ |
| void flush() throws IOException; |
| |
| /** |
| * Sets the {@link BeanFactory} to use by the DataStore. |
| * @param beanFactory the BeanFactory to use |
| */ |
| void setBeanFactory(BeanFactory<K,T> beanFactory); |
| |
| /** |
| * Returns the BeanFactory used by the DataStore |
| * @return the BeanFactory used by the DataStore |
| */ |
| BeanFactory<K,T> getBeanFactory(); |
| |
| /** |
| * Close the DataStore. This should release any resources held by the |
| * implementation, so that the instance is ready for GC. |
| * All other DataStore methods cannot be used after this |
| * method was called. Subsequent calls of this method are ignored. |
| */ |
| void close() throws IOException; |
| |
| Configuration getConf(); |
| |
| void setConf(Configuration conf); |
| |
| void readFields(DataInput in) throws IOException; |
| |
| void write(DataOutput out) throws IOException; |
| |
| } |