<commit_before>package org.simpleds;

import java.util.Collection;
import java.util.List;

import org.simpleds.annotations.Cacheable;
import org.simpleds.cache.CacheManager;
import org.simpleds.exception.EntityNotFoundException;
import org.simpleds.metadata.ClassMetadata;

import com.google.appengine.api.datastore.DatastoreService;
import com.google.appengine.api.datastore.Entity;
import com.google.appengine.api.datastore.Key;
import com.google.appengine.api.datastore.Transaction;

public interface EntityManager {

	/**
	 * Convert a Datastore representation to a Java object
	 * @param entity the Entity returned by the Datastore
	 * @return the Java equivalent to the provided {@link Entity}
	 */
	<T> T datastoreToJava(Entity entity);

	/**
	 * Convert a Java Object to its Datastore representation
	 * @param javaObject the Java Object to transform
	 * @return the {@link Entity} equivalent to the provided Java Object
	 */
	Entity javaToDatastore(Object javaObject);

	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Object javaObject);
	
	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param transaction the transaction instance to use.  May be null.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Transaction transaction, Object javaObject);

	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param parentKey the parent entity key to use while generating the persistent entity key. May be null.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Key parentKey, Object javaObject);

	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param parentKey the parent entity key to use while generating the persistent entity key. May be null.
	 * @param transaction the transaction instance to use.  May be null.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Transaction transaction, Key parentKey, Object javaObject);
	
	/**
	 * Store a collection of persistent objects into the datastore. 
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * 
	 * @param javaObjects the Collection of java objects to store
	 */
	<T> void put(Collection<T> javaObjects);
	
	/**
	 * Store a collection of persistent objects into the datastore.
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * @param javaObjects the Collection of java objects to store
	 * @param transaction the transaction instance to use.  May be null.
	 */
	<T> void put(Transaction transaction, Collection<T> javaObjects);

	/**
	 * Store a collection of persistent objects into the datastore.
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * @param parentKey the key of the parent instance. If not null, it will be used as parent
	 * of the generated entity Keys
	 * @param javaObjects the Collection of java objects to store
	 */
	<T> void put(Key parentKey, Collection<T> javaObjects);
	
	/**
	 * Store a collection of persistent objects into the datastore.
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * @param parentKey the key of the parent instance. If not null, it will be used as parent
	 * of the generated entity Keys
	 * @param transaction the transaction instance to use.  May be null.
	 * @param javaObjects the Collection of java objects to store
	 */
	<T> void put(Transaction transaction, Key parentKey, Collection<T> javaObjects);

	/**
	 * Return a persistent java instance by key
	 * @param key the key of the persistent entity to retrieve
	 * @return the persistent java instance
	 */
	<T> T get(Key key);
	
	/**
	 * Return a persistent java instance by key. If transaction is not null any {@link Cacheable}
	 * settings will be ignored. 
	 * @param key the key of the persistent entity to retrieve
	 * @param transaction the transaction instance to use. May be null.
	 * @return the persistent java instance
	 */
	<T> T get(Transaction transaction, Key key);

	/**
	 * Return a set of persistent entities, by key
	 * @param keys the keys of the persistent entities to retrieve
	 * @return a Map of the retrieved entities, by Key
	 */
	<T> List<T> get(Iterable<Key> keys);
	
	/**
	 * Return a collection of persistent entities. If transaction is not null any {@link Cacheable}
	 * settings will be ignored. 
	 * @param keys the keys of the persistent entities to retrieve
	 * @param transaction the transaction instance to use.  May be null.
	 * @return a Map of the retrieved entities, by Key
	 */
	<T> List<T> get(Transaction transaction, Iterable<Key> keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 */
	void delete(Key... keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 * @param transaction the transaction instance to use.  May be null.
	 */
	void delete(Transaction transaction, Key... keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 */
	void delete(Iterable<Key> keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param transaction the transaction instance to use.  May be null.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 */
	void delete(Transaction transaction, Iterable<Key> keys);


	/**<commit_msg>Improved javadoc<commit_after>package org.simpleds;

import java.util.Collection;
import java.util.List;

import org.simpleds.annotations.Cacheable;
import org.simpleds.cache.CacheManager;
import org.simpleds.exception.EntityNotFoundException;
import org.simpleds.metadata.ClassMetadata;

import com.google.appengine.api.datastore.DatastoreService;
import com.google.appengine.api.datastore.Entity;
import com.google.appengine.api.datastore.Key;
import com.google.appengine.api.datastore.Transaction;

public interface EntityManager {

	/**
	 * Convert a Datastore representation to a Java object
	 * @param entity the Entity returned by the Datastore
	 * @return the Java equivalent to the provided {@link Entity}
	 */
	<T> T datastoreToJava(Entity entity);

	/**
	 * Convert a Java Object to its Datastore representation
	 * @param javaObject the Java Object to transform
	 * @return the {@link Entity} equivalent to the provided Java Object
	 */
	Entity javaToDatastore(Object javaObject);

	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Object javaObject);
	
	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param transaction the transaction instance to use.  May be null.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Transaction transaction, Object javaObject);

	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param parentKey the parent entity key to use while generating the persistent entity key. May be null.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Key parentKey, Object javaObject);

	/**
	 * Persists a java object to the datastore. If the entity is cacheable, it will be written to the cache.
	 * If the primary key has not yet been assigned, a new one will be generated and assigned to the Java object.
	 * @param parentKey the parent entity key to use while generating the persistent entity key. May be null.
	 * @param transaction the transaction instance to use.  May be null.
	 * @param javaObject the instance to persist.
	 * @return the allocated/existing key
	 */
	Key put(Transaction transaction, Key parentKey, Object javaObject);
	
	/**
	 * Store a collection of persistent objects into the datastore. 
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * 
	 * @param javaObjects the Collection of java objects to store
	 */
	<T> void put(Collection<T> javaObjects);
	
	/**
	 * Store a collection of persistent objects into the datastore.
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * @param javaObjects the Collection of java objects to store
	 * @param transaction the transaction instance to use.  May be null.
	 */
	<T> void put(Transaction transaction, Collection<T> javaObjects);

	/**
	 * Store a collection of persistent objects into the datastore.
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * @param parentKey the key of the parent instance. If not null, it will be used as parent
	 * of the generated entity Keys
	 * @param javaObjects the Collection of java objects to store
	 */
	<T> void put(Key parentKey, Collection<T> javaObjects);
	
	/**
	 * Store a collection of persistent objects into the datastore.
	 * Primary keys will be generated and assigned if needed. If these objects are cacheable,
	 * the cache contents will also be updated.
	 * @param parentKey the key of the parent instance. If not null, it will be used as parent
	 * of the generated entity Keys
	 * @param transaction the transaction instance to use.  May be null.
	 * @param javaObjects the Collection of java objects to store
	 */
	<T> void put(Transaction transaction, Key parentKey, Collection<T> javaObjects);

	/**
	 * Return a persistent java instance by key
	 * @param key the key of the persistent entity to retrieve
	 * @return the persistent java instance
	 * @throws EntityNotFoundException if the entity could  not be found
	 */
	<T> T get(Key key);
	
	/**
	 * Return a persistent java instance by key. If transaction is not null any {@link Cacheable}
	 * settings will be ignored. 
	 * @param key the key of the persistent entity to retrieve
	 * @param transaction the transaction instance to use. May be null.
	 * @return the persistent java instance
	 * @throws EntityNotFoundException if the entity could  not be found
	 */
	<T> T get(Transaction transaction, Key key);

	/**
	 * Return a set of persistent entities, by key
	 * @param keys the keys of the persistent entities to retrieve
	 * @return a Map of the retrieved entities, by Key
	 * @throws EntityNotFoundException if any entity could not be found
	 */
	<T> List<T> get(Iterable<Key> keys);
	
	/**
	 * Return a collection of persistent entities. If transaction is not null any {@link Cacheable}
	 * settings will be ignored. 
	 * @param keys the keys of the persistent entities to retrieve
	 * @param transaction the transaction instance to use.  May be null.
	 * @return a Map of the retrieved entities, by Key
	 * @throws EntityNotFoundException if any entity could not be found
	 */
	<T> List<T> get(Transaction transaction, Iterable<Key> keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 */
	void delete(Key... keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 * @param transaction the transaction instance to use.  May be null.
	 */
	void delete(Transaction transaction, Key... keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 */
	void delete(Iterable<Key> keys);
	
	/**
	 * Delete multiple instances from the Datastore. Cached keys will also be removed from the datastore.
	 * @param transaction the transaction instance to use.  May be null.
	 * @param keys the keys to delete. Notice that they can reference different entity kinds.
	 */
	void delete(Transaction transaction, Iterable<Key> keys);


	/**
{'fraction_non_alphanumeric': 0.06852955965807055, 'fraction_numerical': 0.0, 'mean_word_length': 3.728940217391304, 'pattern_counts': {'":': 0, '<': 41, '<?xml version=': 0, '>': 41, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5554666', 'n_tokens_mistral': 3721, 'n_tokens_neox': 3433, 'n_words': 1861}