ResourceManager.java

/*
 * Copyright 2015-2016 OpenCB
 *
 * 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 org.opencb.opencga.catalog.managers.api;

import org.opencb.commons.datastore.core.ObjectMap;
import org.opencb.commons.datastore.core.Query;
import org.opencb.commons.datastore.core.QueryOptions;
import org.opencb.commons.datastore.core.QueryResult;
import org.opencb.opencga.catalog.exceptions.CatalogException;

import javax.annotation.Nullable;
import java.io.IOException;
import java.util.List;

/**
 * @author Jacobo Coll <jacobo167@gmail.com>
 */
public interface ResourceManager<I, R> {

    /**
     * Reads an object from Catalog given an ID.
     *
     * @param id        Id of the object to read
     * @param options   Read options
     * @param sessionId sessionId
     * @return The specified object
     * @throws CatalogException CatalogException
     */
    QueryResult<R> get(I id, QueryOptions options, String sessionId) throws CatalogException;

    /**
     * Read all the R objects matching with the query on the QueryOptions.
     *
     * @param query     Query to catalog.
     * @param options   Query options, like "include", "exclude", "limit" and "skip"
     * @param sessionId sessionId
     * @return All matching elements.
     * @throws CatalogException CatalogException
     */
    QueryResult<R> get(Query query, QueryOptions options, String sessionId) throws CatalogException;

    /**
     * Update an existing catalog entry.
     *
     * @param id         Id of the object to update
     * @param parameters Parameters to change.
     * @param options    options
     * @param sessionId  sessionId
     * @return The modified entry.
     * @throws CatalogException CatalogException
     */
    QueryResult<R> update(I id, ObjectMap parameters, QueryOptions options, String sessionId) throws CatalogException;

    /**
     * Delete the entries satisfying the query.
     *
     * @param query     Query of the objects to be deleted.
     * @param options   Deleting options.
     * @param sessionId sessionId.
     * @return A list with the deleted objects.
     * @throws CatalogException CatalogException
     * @throws IOException IOException.
     */
    List<QueryResult<R>> delete(Query query, QueryOptions options, String sessionId) throws CatalogException, IOException;

    /**
     * Restore deleted entries from Catalog.
     *
     * @param ids       Comma separated list of ids of the objects to restore.
     * @param options   Restore options.
     * @param sessionId sessionId.
     * @return A list with the restored objects.
     * @throws CatalogException CatalogException
     */
    List<QueryResult<R>> restore(String ids, QueryOptions options, String sessionId) throws CatalogException;

    /**
     * Restore the entries satisfying the query.
     *
     * @param query     Query of the objects to be restored.
     * @param options   Restore options.
     * @param sessionId sessionId.
     * @return A list with the restored objects.
     * @throws CatalogException CatalogException
     */
    List<QueryResult<R>> restore(Query query, QueryOptions options, String sessionId) throws CatalogException;


    /**
     * Ranks the elements queried, groups them by the field(s) given and return it sorted.
     *
     *
     * @param query      Query object containing the query that will be executed.
     * @param field      A field or a comma separated list of fields by which the results will be grouped in.
     * @param numResults Maximum number of results to be reported.
     * @param asc        Order in which the results will be reported.
     * @param sessionId  sessionId.
     * @return           A QueryResult object containing each of the fields in field and the count of them matching the query.
     * @throws CatalogException CatalogException
     */
    QueryResult rank(Query query, String field, int numResults, boolean asc, String sessionId) throws CatalogException;

    /**
     * Groups the elements queried by the field(s) given.
     *
     *
     * @param query   Query object containing the query that will be executed.
     * @param field   Field by which the results will be grouped in.
     * @param options QueryOptions object.
     * @param sessionId  sessionId.
     * @return        A QueryResult object containing the results of the query grouped by the field.
     * @throws CatalogException CatalogException
     */
    QueryResult groupBy(Query query, String field, QueryOptions options, String sessionId) throws CatalogException;

    /**
     * Groups the elements queried by the field(s) given.
     *
     * @param query   Query object containing the query that will be executed.
     * @param fields  List of fields by which the results will be grouped in.
     * @param options QueryOptions object.
     * @param sessionId  sessionId.
     * @return        A QueryResult object containing the results of the query grouped by the fields.
     * @throws CatalogException CatalogException
     */
    QueryResult groupBy(Query query, List<String> fields, QueryOptions options, String sessionId) throws CatalogException;

    /**
     * Change the status of an entry.
     *
     * @param id id of the entry.
     * @param status new status that will be set.
     * @param message message of the status.
     * @param sessionId session id of the user ordering the action.
     * @throws CatalogException if any error occurs (user with no permissions, invalid status, id not found).
     */
    void setStatus(String id, @Nullable String status, @Nullable String message, String sessionId) throws CatalogException;

}