/*
 * #%L
 * Wisdom-Framework
 * %%
 * Copyright (C) 2013 - 2014 Wisdom Framework
 * %%
 * Licensed 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.
 * #L%
 */
package org.wisdom.api.model;

import java.io.Serializable;
import java.util.concurrent.Callable;

/**
 * A service to let components access entities stored in a repository (i.e. persistence layer).
 * This service manages only one type of entity (i.e. class). For example, the entity Task would have its own
 * CrudService<Task> while the entity User would have another one.
 *
 * The CRUD Service is independent of the persistent layer used. If you need to access low-level API,
 * use the getRepository method.
 *
 * Providers must register the 'entity.class' and 'entity.classname' properties in their service registration. The
 * first property register the class object, while the second only its name.
 *
 * @param <T> the type of the entity
 * @param <I> the type of the ids
 */
public interface Crud<T, I extends Serializable> {

    /**
     * The service property that <strong>must</strong> be published to indicate the entity class.
     */
    public static final String ENTITY_CLASS_PROPERTY = "entity.class";

    /**
     * The service property that <strong>must</strong> be published to indicate the entity qualified class name.
     */
    public static final String ENTITY_CLASSNAME_PROPERTY = "entity.classname";

    /**
     * Gets the class of the represented entity.
     * @return the repository managing this entity.
     */
    Class<T> getEntityClass();

    /**
     * Gets the class of the Id used by the persistent layer.
     * @return the type of the id.
     */
    Class<I> getIdClass();

    /**
     * Deletes the given entity instance. The instance is removed from the persistent layer.
     * @param t the instance
     * @return the entity instance, may be the same as the parameter t but can also be different
     */
    T delete(T t);

    /**
     * Deletes the given entity instance (specified by its id). The instance is removed from the persistent layer.
     * @param id the id
     */
    void delete(I id);

    /**
     * Deletes the given entity instances. The instances are removed from the persistent layer.
     * @param entities the entities to remove from the persistent layer
     * @return the set of entity instances
     */
    Iterable<T> delete(Iterable<T> entities);

    /**
     * Saves a given entity. Use the returned instance for further operations as the operation might have
     * changed the entity instance completely.
     *
     * This method is used to save a new entity or to update it.
     * @param t the instance to save
     * @return the saved entity
     */
    T save(T t);

    /**
     * Saves all given entities. Use the returned instances for further operations as the operation might have
     * changed the entity instances completely.
     * @param entities the entities to save, must not contains {@literal null} values
     * @return the saved entities
     */
    Iterable<T> save(Iterable<T> entities);

    /**
     * Retrieves an entity by its id.
     * @param id the id, must not be null
     * @return the entity instance, {@literal null} if there are no entities matching the given id.
     */
    T findOne(I id);

    /**
     * Retrieves the entity matching the given filter. If several entities matches, the first is returned.
     * @param filter the filter
     * @return the first matching instance, {@literal null} if none
     */
    T findOne(EntityFilter<T> filter);

    /**
     * Checks whether an entity instance with the given id exists, i.e. has been saved and is persisted.
     * @param id the id, must not be null
     * @return {@literal true} if an entity with the given id exists, {@literal false} otherwise.
     */
    boolean exists(I id);

    /**
     * Returns all instances of the entity.
     * @return the instances, empty if none.
     */
    Iterable<T> findAll();

    /**
     * Returns all instances of the type with the given IDs.
     * @param ids the ids.
     * @return the instances, empty if none.
     */
    Iterable<T> findAll(Iterable<I> ids);

    /**
     * Retrieves the entities matching the given filter.
     * Be aware that the implementation may load all stored entities in memory to retrieve the right set of entities.
     * @param filter the filter
     * @return the matching instances, empty if none.
     */
    Iterable<T> findAll(EntityFilter<T> filter);

    /**
     * Gets the number of stored instances.
     * @return the number of stored instances, 0 if none.
     */
    long count();

    /**
     * Gets the repository storing the instances of this entity.
     * @return the repository object, may be {@literal null} if there are no repository.
     */
    Repository getRepository();

    /**
     * Executes the given runnable in a transaction. If the block throws an exception, the transaction is rolled back.
     * This method may not be supported by all persistent technologies, as they are not necessary supporting
     * transactions. In that case, this method throw a {@link java.lang.UnsupportedOperationException}.
     *
     * @param runnable the runnable to execute in a transaction
     * @throws HasBeenRollBackException if the transaction has been rollback.
     * @throws java.lang.UnsupportedOperationException if transactions are not supported.
     * @throws org.wisdom.api.model.InitTransactionException if an exception occurred before running the transaction block.
     * @throws RollBackHasCauseAnException if an exception occurred when the transaction is rollback.
     */
    void executeTransactionalBlock(Runnable runnable) throws HasBeenRollBackException;

    /**
     * Executes the given runnable in a transaction. If the block throws an exception, the transaction is rolled back.
     * This method may not be supported by all persistent technologies, as they are not necessary supporting
     * transactions. In that case, this method throw a {@link java.lang.UnsupportedOperationException}.
     * @param callable the block to execute in a transaction
     * @return A the result
     * @throws HasBeenRollBackException if the transaction has been rollback.
     * @throws java.lang.UnsupportedOperationException if transactions are not supported.
     * @throws org.wisdom.api.model.InitTransactionException if an exception occurred before running the transaction block.
     * @throws RollBackHasCauseAnException if an exception occurred when the transaction is rollback.
     */
    <A> A executeTransactionalBlock(Callable<A> callable) throws HasBeenRollBackException;

    /**
     * @return The {@link TransactionManager} used by this crud in order to run the transaction.
     */
    TransactionManager getTransactionManager();

    /**
     * Create a FluentTransaction with this Crud service,
     *
     * @param <R> the return type of the transaction block.
     * @return a new FluentTransaction.
     * @throws java.lang.UnsupportedOperationException if transactions are not supported.
     * @throws org.wisdom.api.model.InitTransactionException if an exception occurred before running the transaction block.
     * @throws RollBackHasCauseAnException if an exception occurred when the transaction is rollback.
     */
    <R> FluentTransaction<R> transaction();

    /**
     * Create a FluentTransaction, with the given transaction block.
     *
     * @param <R> the return type of the transaction block
     * @param callable, The transaction block to be executed by the returned FluentTransaction
     * @return a new FluentTransaction with a transaction block already defined.
     * @throws java.lang.UnsupportedOperationException if transactions are not supported.
     */
    <R> FluentTransaction<R>.Intermediate transaction(Callable<R> callable);
}

@@ -1964,39 +1964,22 @@
 the 
-repository managing this entity
+entity's class
 .%0A  

Fix typo in javadoc