/**
 * Copyright (c) 2011, 2015 - Lunifera GmbH (Gross Enzersdorf, Austria), Loetz GmbH&Co.KG (69115 Heidelberg, Germany)
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *         Florian Pirchner - Initial implementation
 */
package org.eclipse.osbp.runtime.common.filter;

import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.eclipse.osbp.runtime.common.validation.IStatus;
import org.eclipse.osbp.runtime.common.validation.ValidationKind;

// TODO: Auto-generated Javadoc
/**
 * The Interface IDTOService.
 *
 * @param <A>
 *            the generic type
 */
public interface IDTOService<A> extends IService {

	/** The Constant PROP_MAX_COLLECTION_CONTENT. */
	public static final int PROP_MAX_COLLECTION_CONTENT = 2000;

	/**
	 * Returns the dto for the given id.
	 *
	 * @param id
	 *            the id
	 * @return the a
	 */
	A get(Object id);

	/**
	 * Reloads the given dto and returns the refreshed values by a new
	 * instance.<br>
	 * If the data basis for the dto is not available anymore. For instance the
	 * entity was deleted, then <code>null</code> will be returned.
	 *
	 * @param dto
	 *            the dto
	 * @return A
	 */
	A reload(A dto);

	/**
	 * Returns a collection of dtos matching the filter in the query. <br>
	 * The maximum amount of contained elements is limited by
	 * {@link #PROP_MAX_COLLECTION_CONTENT}.
	 *
	 * @param query
	 *            the query
	 * @return the collection
	 */
	Collection<A> find(IQuery query);

	/**
	 * Returns a collection of dtos matching the filter defined in the query and
	 * starting from the given startIndex. <br>
	 * May be used for lazy loading issues. Ensure that a sort order is used in
	 * that case.
	 * 
	 * The maximum amount of contained elements is limited by
	 * {@link #PROP_MAX_COLLECTION_CONTENT}.
	 *
	 * @param query
	 *            the query
	 * @param startIndex
	 *            the start index
	 * @return the collection
	 */
	Collection<A> find(IQuery query, int startIndex);

	/**
	 * Returns a collection of dtos selected by the given jpql. <br>
	 * This method throws an {@link IllegalArgumentException} if the defined
	 * jpql does not select dtos.
	 *
	 * @param query
	 *            the query
	 * @return the collection
	 */
	Collection<A> findDtos(IJPQL jpql);

	/**
	 * Returns a list of values selected by the given jpql. <br>
	 * The values are at the same index as in the JPQL "select"-statement. Eg.
	 * "select p.name, p.postalcode from Person p".
	 *
	 * @param query
	 *            the query
	 * @return the collection
	 */
	List<?> findValues(IJPQL jpql);

	/**
	 * Updates the given DTO.
	 *
	 * @param dto
	 *            the dto
	 */
	void update(A dto);

	/**
	 * Deletes the given DTO.
	 *
	 * @param dto
	 *            the dto
	 * @throws DtoServiceException
	 *             if the record can not be deleted
	 */
	void delete(A dto) throws DtoServiceException;

	/**
	 * Returns the count of all dto matching the filter.
	 *
	 * @param query
	 *            the query
	 * @return the int
	 */
	int size(IQuery query);

	/**
	 * Returns true, if the dto exists for the given filter.
	 *
	 * @param dto
	 *            the dto
	 * @param query
	 *            the query
	 * @return true, if successful
	 */
	boolean contains(Object dto, IQuery query);
	
	/**
	 * Returns true, if a dto exists for the given filter.
	 *
	 * @param query
	 *            the query
	 * @return true, if successful
	 */
	boolean contains(IQuery query);

	/**
	 * Returns the next dto for the given one using the filter and the
	 * sortOrder.
	 *
	 * @param dto
	 *            the dto
	 * @param query
	 *            the query
	 * @return the next
	 */
	A getNext(A dto, IQuery query);

	/**
	 * Returns the previous dto for the given one using the filter and the
	 * sortOrder.
	 *
	 * @param dto
	 *            the dto
	 * @param query
	 *            the query
	 * @return the previous
	 */
	A getPrevious(A dto, IQuery query);

	/**
	 * Returns the first dto for the given filter and the sortOrder.
	 *
	 * @param query
	 *            the query
	 * @return the first
	 */
	A getFirst(IQuery query);

	/**
	 * Returns the last dto for the given filter and the sortOrder.
	 *
	 * @param query
	 *            the query
	 * @return the last
	 */
	A getLast(IQuery query);

	/**
	 * Returns true, if the given dto is the first one for the filter and
	 * sortOrder.
	 *
	 * @param dto
	 *            the dto
	 * @param query
	 *            the query
	 * @return true, if is first
	 */
	boolean isFirst(A dto, IQuery query);

	/**
	 * Returns true, if the given dto is the last one for the filter and
	 * sortOrder.
	 *
	 * @param dto
	 *            the dto
	 * @param query
	 *            the query
	 * @return true, if is last
	 */
	boolean isLast(A dto, IQuery query);

	/**
	 * Returns the index of the given dto for the filter and sortOrder.
	 *
	 * @param dto
	 *            the dto
	 * @param query
	 *            the query
	 * @return the int
	 */
	int indexOf(A dto, IQuery query);

	/**
	 * Returns the dto for the given index, filter and sortOrder.
	 *
	 * @param index
	 *            the index
	 * @param query
	 *            the query
	 * @return the by index
	 */
	A getByIndex(int index, IQuery query);

	/**
	 * Returns a list of dtos with size &lt;= numberOfItems, starting from the
	 * startIndex in respect to the filter and sortOrder.
	 *
	 * @param startIndex
	 *            the start index
	 * @param numberOfItems
	 *            the number of items
	 * @param query
	 *            the query
	 * @return the by index
	 */
	List<A> getByIndex(int startIndex, int numberOfItems, IQuery query);

	/**
	 * Validates the given DTO.
	 *
	 * @param object
	 *            the object
	 * @param kind
	 *            the kind of validation
	 * @param properties
	 *            any kind of properties required in validation
	 * @return the sets the
	 * @throws IllegalStateException
	 *             if no Validator is available
	 */
	Set<IStatus> validate(A object, ValidationKind kind, Map<String, Object> properties) throws IllegalStateException;

	/**
	 * Gets the id.
	 *
	 * @param dto
	 *            the dto
	 * @return the id
	 */
	Object getId(A dto);
}