com.arconsis.android.datarobot.cursor.ObjectCursor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of datarobot.api Show documentation
Datarobot for Android is a lightweight framework, which frees you from the burden of dealing with Androids SQLite database directly if you don't want to and let's you access it directly if you have to.
The newest version!
/*
 * Copyright (C) 2014 The Datarobot Authors
 *
 * 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.
 */
package com.arconsis.android.datarobot.cursor;

import android.content.ContentProvider;
import android.content.ContentResolver;
import android.database.Cursor;

import com.arconsis.android.datarobot.BaseContentProvider;
import com.arconsis.android.datarobot.CursorUtil;

import java.io.Closeable;
import java.util.Collection;
import java.util.Iterator;
import java.util.NoSuchElementException;

/**
 * Cursor for objects of type T which works on the original {@link Cursor}. 

 * If the position of the original {@link Cursor} is changed, the position of the {@code ObjectCursor} is also changed
 * and vice versa.

 * 

 * Resolve the {@code ObjectCursor} with an {@link CursorUtil#getObjectCursor(Cursor cursor)} from a {@link Cursor}
 * resolved with a {@link ContentResolver} from a {@link ContentProvider} derived by {@link BaseContentProvider}.
 *
 * @param  Type of the entity.
 * @author Falk Appel
 * @author Alexander Frank
 */
public interface ObjectCursor extends Iterable, Closeable {

	/**
	 * @return a new mutable {@code Collection} containing all elements contained in this {@code ObjectCursor}. If the
	 * {@code ObjectCursor} is empty an empty {@code Collection} is returned.
	 */
	Collection getAll();

	/**
	 * @return the element at the current position of the {@code ObjectCursor}.
	 * 

	 * If the {@link Cursor} is before the first element, the position is changed to the first position, if the
	 * {@link Cursor} is after the last element, the position is changed to the last elements position
	 * @throws NoSuchElementException if there are no elements to be returned.
	 */
	T getCurrent();

	/**
	 * @return the element at the first position of the {@code ObjectCursor}.
	 * 

	 * The {@link Cursor} is moved to the first position.
	 * @throws NoSuchElementException if there is no element to be returned.
	 */
	T getFirst();

	/**
	 * @return the element at the last position of the {@code ObjectCursor}.
	 * 

	 * The {@link Cursor} is moved to the last position.
	 * @throws NoSuchElementException if there is no element to be returned.
	 */
	T getLast();

	/**
	 * Returns the element at the next position of the {@code ObjectCursor}.
	 * 

	 * The {@link Cursor} is moved to the next position.
	 *
	 * @return Element at next position
	 * @throws NoSuchElementException if there is no element to be returned.
	 * @see #hasNext
	 */
	T getNext();

	/**
	 * @param amount Number of positions to move forward
	 * @return a new mutable {@code Collection} containing the next amount elements contained in this
	 * {@code ObjectCursor}. If the {@code ObjectCursor} contains less than amount elements
	 * following the current position a collection with less than amount elements is returned.
	 * @throws NoSuchElementException if there are no next elements at all
	 */
	Collection getNext(int amount);

	/**
	 * @return the element at the first position of the {@code ObjectCursor}. It is expected, that the {@link Cursor}
	 * contains exactly one element.
	 * @throws NoSuchElementException if there is no element to be returned.
	 * @throws IllegalStateException  if the {@link Cursor} contains more than one element
	 */
	T getOne();

	/**
	 * @return the element at the position before the current position of the {@code ObjectCursor}.
	 * 

	 * The {@link Cursor} is moved to the previous position.
	 * @throws NoSuchElementException if there is no element to be returned.
	 * @see #hasPrevious
	 */
	T getPrevious();

	/**
	 * @param amount Number of positions to move backwards
	 * @return a new mutable {@code Collection} containing the previous amount elements contained in this
	 * {@code ObjectCursor}. If the {@code ObjectCursor} contains less than amount elements
	 * preceding the current position a collection with less than amount elements is returned.
	 * @throws NoSuchElementException if there are no preceding elements at all
	 */
	Collection getPrevious(int amount);

	/**
	 * @return true if there is at least one more element after the current position, false
	 * otherwise.
	 * @see #getNext
	 */
	boolean hasNext();

	/**
	 * @return true if there is at least one more element before the current position, false
	 * otherwise.
	 * @see #getPrevious
	 */
	boolean hasPrevious();

	/**
	 * @return an {@link Iterator} which does not support the {@link Iterator#remove()} operation.
	 * @see java.lang.Iterable#iterator()
	 */
	@Override
	public Iterator iterator();

	/**
	 * @return a count of how many elements this {@code ObjectCursor} contains.
	 */
	int size();

	/**
	 * @return true if this {@code ObjectCursor} is closed, otherwise false;
	 */
	boolean isClosed();

	/**
	 * @return the current position of the cursor.
	 */
	int getPosition();

	/**
	 * Move the cursor to an absolute position.
	 *
	 * @param position Position to move to
	 * @return true if the move was succesful.
	 */
	boolean moveToPosition(int position);

	/**
	 * Move the cursor to the first row.
	 *
	 * @return true if the move was succesful.
	 */
	boolean moveToFirst();

	/**
	 * Move the cursor to the last row.
	 *
	 * @return true if the move was succesful.
	 */
	boolean moveToLast();

	/**
	 * Move the cursor to the next row.
	 *
	 * @return true if the move was succesful.
	 */
	boolean moveToNext();

	/**
	 * Move the cursor to the previous row.
	 *
	 * @return true if the move was succesful.
	 */
	boolean moveToPrevious();
}