ibookmarkservice.java

esri的ArcGIS Server超级学习模板程序（for java）

package com.esri.solutions.jitk.services.personalization;

import java.util.List;

import com.esri.solutions.jitk.personalization.dao.Criteria;
import com.esri.solutions.jitk.personalization.dao.IBookmarkDAO;
import com.esri.solutions.jitk.personalization.dao.PageInfo;
import com.esri.solutions.jitk.services.common.ServicesException;
import com.esri.solutions.jitk.services.personalization.data.BookmarkData;

/**
 * Interface defining methods that are necessary for the implementation of a Web Service that
 * manages and queries Bookmarks.  The bookmarks are stored in some form of a datastore, which is
 * accessed through a {@link IBookmarkDAO}.
 * <p>
 * The {@link IBookmarkDAO} is responsible for all aspects of creating, selecting, updating and deleting
 * bookmarks.  Thus, it is the DAO that builds the queries, whereas this object simply abstracts away that
 * DAO for the purposes of creating a web service.
 * </p>
 */
public interface IBookmarkService {

	/**
	 * Retrieves the Data Access Object (DAO) that accesses the bookmark datastore. 
	 * @return {@link IBookmarkDAO} implementation 
	 */
	public IBookmarkDAO getDAO();

	/**
	 * Inserts a single bookmark into the datastore.
	 * @param data The {@link BookmarkData} representation of the bookmark to insert.
	 */
	public void insert(BookmarkData data) throws ServicesException;

	/**
	 * Updates a bookmark with the given {@link BookmarkData#getId() id} with the specified information.
	 * @param data The {@link BookmarkData} encapsulation of the new bookmark information.
	 */
	public void update(BookmarkData data) throws ServicesException;

	/**
	 * Removes a single bookmark from the datastore.
	 * @param id {@link String} containing the ID of the bookmark to remove.
	 */
	public void delete(String id) throws ServicesException;

	/**
	 * Retrieves a single bookmark, specified by its ID, from the datastore.
	 * @param id {@link String} containing the ID of the bookmark to retrieve.
	 * @return {@link BookmarkData} representation of the requested bookmark.
	 */
	public BookmarkData selectOne(String id) throws ServicesException;

	/**
	 * Retrieves all bookmarks whose properties match those specified by the {@code criteria} parameter.
	 * @param criteria {@link Criteria} encapsulation of the bookmark query parameters
	 * @return A {@link List} of {@link BookmarkData} objects that match the specified criteria.
	 */
	public List<BookmarkData> selectAll(Criteria criteria)
			throws ServicesException;

	/**
	 * Selects a count of all bookmarks whose properties match those specified by the {@code criteria} parameter.
	 * @param criteria {@link Criteria} encapsulation of the bookmark query parameters
	 * @return {@code int} containing the count.
	 */
	public int selectAllCount(Criteria criteria) throws ServicesException;

	/**
	 * Retrieves a subset of the bookmarks whose criteria match those specified by the {@code criteria} parameter.
	 * <p>
	 * This method is similar to {@link #selectAll(Criteria)}, except in that it utilizes the {@code pageInfo} parameter
	 * to determine a subset of results to display.  This method is useful, in particular, for displaying paged results
	 * and limiting the amount of data returned to the client.
	 * </p>
	 * {@code pageInfo} parameter to specify the subset 
	 * @param criteria {@link Criteria} encapsulation of the bookmark query parameters
	 * @param pageInfo {@link PageInfo} encapsulating the information used to determine the page of results
	 * @return A {@link List} of {@link BookmarkData} objects that match the specified criteria, and fall within the specified subset
	 *         of the actual results.
	 */
	public List<BookmarkData> selectPage(Criteria criteria, PageInfo pageInfo)
			throws ServicesException;
}