RecipeDao.java

/*******************************************************************************
 * Copyright (c) 2012-2017 Codenvy, S.A.
 * 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:
 *   Codenvy, S.A. - initial API and implementation
 *******************************************************************************/
package org.eclipse.che.api.machine.server.spi;

import org.eclipse.che.api.core.ConflictException;
import org.eclipse.che.api.core.NotFoundException;
import org.eclipse.che.api.core.ServerException;
import org.eclipse.che.api.machine.server.recipe.RecipeImpl;
import org.eclipse.che.api.machine.shared.ManagedRecipe;

import java.util.List;

/**
 * Data access object for {@link ManagedRecipe}.
 *
 * @author Eugene Voevodin
 */
public interface RecipeDao {

    /**
     * Creates recipe
     *
     * @param recipe
     *         recipe to create
     * @throws NullPointerException
     *         when {@code recipe} is not specified
     * @throws ConflictException
     *         when recipe with id equal to {@code recipe.getId()} already exists
     * @throws ServerException
     *         when any other error occurs
     */
    void create(RecipeImpl recipe) throws ConflictException, ServerException;

    /**
     * Updates existing recipe
     * <p/>
     * All data except of recipe identifier and recipe creator may be updated
     *
     * @param recipe
     *         recipe update
     * @return updated instance of the recipe
     * @throws NullPointerException
     *         when {@code recipe} is not specified
     * @throws NotFoundException
     *         when recipe with id equal to {@code recipe.getId()} doesn't exist
     * @throws ServerException
     *         when any other error occurs
     */
    RecipeImpl update(RecipeImpl recipe) throws NotFoundException, ServerException;

    /**
     * Removes existing recipe
     * <p/>
     * If recipe with specified {@code id} doesn't exist nothing will be done
     *
     * @param id
     *         recipe identifier to remove recipe
     * @throws NullPointerException
     *         when recipe {@code id} is not specified
     * @throws ServerException
     *         when any error occurs
     */
    void remove(String id) throws ServerException;

    /**
     * Returns recipe with specified {@code id} or throws {@link NotFoundException}
     * when recipe with such identifier doesn't exist
     *
     * @param id
     *         recipe identifier to search recipe
     * @return recipe with specified {@code id}
     * @throws NullPointerException
     *         when recipe {@code id} is not specified
     * @throws NotFoundException
     *         when recipe with specified {@code id} doesn't exist
     * @throws ServerException
     *         when any error occurs
     */
    RecipeImpl getById(String id) throws NotFoundException, ServerException;

    /**
     * Searches for recipes which have read permissions for specified user and type is equal to specified {@code type}
     * and tags contain all of specified {@code tags}.
     * <p/>
     * Not specified {@code tags} or {@code type} will not take a part of search,
     * i.e. when {@code type} is {@code null} then only recipes which tags
     * contain all of specified {@code tags} will be returned,
     * when {@code tags} are {@code null} then only recipes which type
     * is equal to specified {@code type} will be returned,
     * when both {@code type} and {@code tags} are {@code null} then all available
     * recipes will be returned.
     *
     * @param user
     *         user id for permission checking
     * @param tags
     *         recipe tags to search recipes, may be {@code null}
     * @param type
     *         recipe type to search recipes, may be {@code null}
     * @param skipCount
     *         count of items which should be skipped,
     *         if found items contain fewer than {@code skipCount} items
     *         then empty list will be returned
     * @param maxItems
     *         max count of items to fetch
     * @return recipes which type is equal to specified {@code type}
     * and tags contain all of specified {@code tags}
     * @throws ServerException
     *         when any error occurs
     */
    List<RecipeImpl> search(String user, List<String> tags, String type, int skipCount, int maxItems) throws ServerException;
}