/**
* The contents of this file are subject to the license and copyright
* detailed in the LICENSE and NOTICE files at the root of the source
* tree and available online at
*
* http://www.dspace.org/license/
*/
package org.dspace.discovery;
import org.dspace.content.DSpaceObject;
import org.dspace.content.Item;
import org.dspace.core.Context;
import org.dspace.discovery.configuration.DiscoveryMoreLikeThisConfiguration;
import java.io.InputStream;
import java.sql.SQLException;
import java.util.List;
/**
* Search interface that discovery uses
*
* @author Kevin Van de Velde (kevin at atmire dot com)
* @author Mark Diggory (markd at atmire dot com)
* @author Ben Bosman (ben at atmire dot com)
*/
public interface SearchService {
/**
* Convenient method to call @see #search(Context, DSpaceObject,
* DiscoverQuery) with a null DSpace Object as scope (i.e. all the
* repository)
*
* @param context
* DSpace Context object.
* @param query
* the discovery query object.
* @return discovery search result object
* @throws SearchServiceException if search error
*/
DiscoverResult search(Context context, DiscoverQuery query)
throws SearchServiceException;
/**
* Convenient method to call @see #search(Context, DSpaceObject,
* DiscoverQuery, boolean) with includeWithdrawn=false
*
* @param context
* DSpace Context object
* @param dso
* a DSpace Object to use as scope of the search (only results
* within this object)
* @param query
* the discovery query object
* @return discovery search result object
* @throws SearchServiceException if search error
*/
DiscoverResult search(Context context, DSpaceObject dso, DiscoverQuery query)
throws SearchServiceException;
/**
*
* @param context
* DSpace Context object.
* @param query
* the discovery query object.
* @param includeWithdrawn
* use <code>true</code> to include in the results also withdrawn
* items that match the query.
* @return discovery search result object
* @throws SearchServiceException if search error
*/
DiscoverResult search(Context context, DiscoverQuery query,
boolean includeWithdrawn) throws SearchServiceException;
/**
*
* @param context
* DSpace Context object
* @param dso
* a DSpace Object to use as scope of the search (only results
* within this object)
* @param query
* the discovery query object
* @param includeWithdrawn
* use <code>true</code> to include in the results also withdrawn
* items that match the query
* @return discovery search result object
* @throws SearchServiceException if search error
*/
DiscoverResult search(Context context, DSpaceObject dso, DiscoverQuery query, boolean includeWithdrawn) throws SearchServiceException;
InputStream searchJSON(Context context, DiscoverQuery query, String jsonIdentifier) throws SearchServiceException;
InputStream searchJSON(Context context, DiscoverQuery query, DSpaceObject dso, String jsonIdentifier) throws SearchServiceException;
List<DSpaceObject> search(Context context, String query, String orderfield, boolean ascending, int offset, int max, String... filterquery);
/**
* Transforms the given string field and value into a filter query
* @param context
* The relevant DSpace Context.
* @param field the field of the filter query
* @param operator equals/notequals/notcontains/authority/notauthority
* @param value the filter query value
* @return a filter query
* @throws SQLException if database error
* An exception that provides information on a database access error or other errors.
*/
DiscoverFilterQuery toFilterQuery(Context context, String field, String operator, String value) throws SQLException;
List<Item> getRelatedItems(Context context, Item item, DiscoveryMoreLikeThisConfiguration moreLikeThisConfiguration);
/**
* Method to create a Query that includes all
* communities and collections a user may administrate.
* If a user has the appropriate rights to administrate communities and/or
* collections we want to look up all contents of those communities and/or
* collections, ignoring the read policies of the items (e.g. to list all
* private items of communities/collections the user administrates). This
* method returns a query to filter for items that belong to those
* communities/collections only.
*
* @param context
* The relevant DSpace Context.
* @return query string specific to the user's rights
* @throws SQLException
* An exception that provides information on a database access error or other errors.
*/
String createLocationQueryForAdministrableItems(Context context) throws SQLException;
/**
* Transforms the metadata field of the given sort configuration into the indexed field which we can then use in our Solr queries.
*
* @param metadataField the metadata field
* @param type see {@link org.dspace.discovery.configuration.DiscoveryConfigurationParameters}
* @return the indexed field
*/
String toSortFieldIndex(String metadataField, String type);
/**
* Utility method to escape any special characters in a user's query
*
* @param query
* User's query to escape.
* @return query with any special characters escaped
*/
String escapeQueryChars(String query);
}