/*
    * Licensed to The Apereo Foundation under one or more contributor license
    * agreements. See the NOTICE file distributed with this work for additional
    * information regarding copyright ownership.
    *
    *
    * The Apereo Foundation licenses this file to you under the Educational
    * Community 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://opensource.org/licenses/ecl2.txt
   *
   * 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.opencastproject.series.api;
  
  import org.opencastproject.metadata.dublincore.DublinCoreCatalog;
  import org.opencastproject.security.api.AccessControlList;
  import org.opencastproject.security.api.UnauthorizedException;
  import org.opencastproject.util.NotFoundException;
  
  import com.entwinemedia.fn.data.Opt;
  
  import java.util.Date;
  import java.util.List;
  import java.util.Map;
  import java.util.Optional;
  
  /**
   * Series service API for creating, removing and searching over series.
   *
   */
  public interface SeriesService {
  
    /**
     * Identifier for service registration and location
     */
    String JOB_TYPE = "org.opencastproject.series";
  
    /**
     * Adds or updates series. IllegalArgumentException is thrown if dc argument is null.
     *
     * @param dc
     *          {@link DublinCoreCatalog} representing series
     * @return Dublin Core catalog of newly created series or null if series Dublin Core was just updated
     * @throws SeriesException
     *           if adding or updating fails
     * @throws UnauthorizedException
     *           if the current user is not authorized to perform this action
     */
    DublinCoreCatalog updateSeries(DublinCoreCatalog dc) throws SeriesException, UnauthorizedException;
  
  
    /**
     * Updates access control rules for specified series. Not specifying series ID or trying to update
     * series with null value will throw IllegalArgumentException.
     *
     * @param seriesID
     *          series to be updated
     * @param accessControl
     *          {@link AccessControlList} defining access control rules
     * @return true if ACL was updated and false it if was created
     * @throws NotFoundException
     *           if series with given ID cannot be found
     * @throws UnauthorizedException
     *           if the current user is not authorized to perform this action
     * @throws SeriesException
     *           if exception occurred
     */
    boolean updateAccessControl(String seriesID, AccessControlList accessControl) throws NotFoundException,
            SeriesException, UnauthorizedException;
  
    /**
     * Updates access control rules for specified series. Allows to set the override parameter that
     * controls whether the episode ACLs of the contained media packages will be removed on update.
     * Not specifying series ID or trying to update series with null value will throw
     * IllegalArgumentException.
     *
     * @param seriesID
     *          series to be updated
     * @param accessControl
     *          {@link AccessControlList} defining access control rules
     * @param overrideEpisodeAcl
     *          Whether the new series acl should override the episode acl
     * @return true if ACL was updated and false it if was created
     * @throws NotFoundException
     *           if series with given ID cannot be found
     * @throws UnauthorizedException
     *           if the current user is not authorized to perform this action
     * @throws SeriesException
     *           if exception occurred
     */
   boolean updateAccessControl(String seriesID, AccessControlList accessControl, boolean overrideEpisodeAcl)
           throws NotFoundException, SeriesException, UnauthorizedException;
 
   /**
    * Removes series
    *
    * @param seriesID
    *          ID of the series to be removed
    * @throws SeriesException
    *           if deleting fails
    * @throws NotFoundException
    *           if series with specified ID does not exist
    * @throws UnauthorizedException
    *           if the current user is not authorized to perform this action
    */
   void deleteSeries(String seriesID) throws SeriesException, NotFoundException, UnauthorizedException;
 
   /**
    * Returns Dublin core representing series by series ID.
    *
    * @param seriesID
    *          series to be retrieved
    * @return {@link DublinCoreCatalog} representing series
    * @throws SeriesException
    *           if retrieving fails
    * @throws UnauthorizedException
    *           if the current user is not authorized to perform this action
    */
   DublinCoreCatalog getSeries(String seriesID) throws SeriesException, NotFoundException, UnauthorizedException;
 
   /**
    * Returns access control rules for series with given ID.
    *
    * @param seriesID
    *          ID of the series for which access control rules will be retrieved
    * @return {@link AccessControlList} defining access control rules
    * @throws NotFoundException
    *           if series with given ID cannot be found
    * @throws SeriesException
    *           if exception occurred
    */
   AccessControlList getSeriesAccessControl(String seriesID) throws NotFoundException, SeriesException;
 
   /**
    * Returns all series (including deleted ones!) that have been modified in the
    * given date range {@code from} (inclusive) -- {@code to} (exclusive). At
    * most {@code limit} many series are returned. ACLs/permissions are NOT
    * checked as this is only intended to be used in an administrative context.
    */
   List<Series> getAllForAdministrativeRead(Date from, Optional<Date> to, int limit)
           throws SeriesException, UnauthorizedException;
 
   /**
    * Updates the extended metadata of a series from a Dublin Core catalog.
    *
    * @param seriesId
    *         the series identifier
    * @param type
    *         the type of dublin core catalog
    * @param dc
    *         the dublin core catalog with extended metadata
    *
    * @return true if the extended metadata could be updated
    * @throws SeriesException
    *           if an error occurred during updating of the extended metadata
    */
   boolean updateExtendedMetadata(String seriesId, String type, DublinCoreCatalog dc) throws SeriesException;
 
   /**
    * Returns all the elements of a series in a map. The key of the map marks the element type. If
    * the series does not contain any elements, an empty map is returned. If the series does not
    * exist, {@code Opt.none()} is returned.
    *
    * @param seriesId
    *          the series identifier
    * @return the map of elements
    * @throws SeriesException
    *           if an error occurred during loading the series elements
    */
   Opt<Map<String, byte[]>> getSeriesElements(String seriesId) throws SeriesException;
 
   /**
    * Returns the element data of the series with the given type. If the series or the element with
    * the given type do not exist, {@code Opt.none()} is returned.
    *
    * @param seriesId
    *          the series identifier
    * @param type
    *          the element type
    * @return the series element data
    * @throws SeriesException
    *           if an error occurred during loading the series element
    */
   Opt<byte[]> getSeriesElementData(String seriesId, String type) throws SeriesException;
 
   /**
    * Creates or updates an element of a series.
    *
    * @param seriesId
    *          the series identifier
    * @param type
    *          the type of the element
    * @param data
    *          the data of the element
    * @return true if the element could be created or updated
    * @throws SeriesException
    *           if an error occurs while updating the element
    */
   boolean updateSeriesElement(String seriesId, String type, byte[] data) throws SeriesException;
 
   /**
    * Deletes an element from a series.
    *
    * @param seriesId
    *          the series identifier
    * @param type
    *          the element type
    * @return true if the element could be deleted; false if no such element/series exists
    * @throws SeriesException
    *           if an error occurs while deleting the element
    */
   boolean deleteSeriesElement(String seriesId, String type) throws SeriesException;
 
   int getSeriesCount() throws SeriesException;
 
   /**
    * Returns the properties for a series.
    *
    * @param seriesID
    *          series to be retrieved
    * @return representing series properties
    * @throws SeriesException
    *           if retrieving fails
    * @throws NotFoundException
    *           Thrown if the series or property cannot be found.
    * @throws UnauthorizedException
    *           if the current user is not authorized to perform this action
    */
   Map<String, String> getSeriesProperties(String seriesID) throws SeriesException, NotFoundException,
           UnauthorizedException;
 
   /**
    * Get a series property.
    *
    * @param seriesID
    *          The id of the series to get the property from.
    * @param propertyName
    *          The name of the property to retrieve
    * @return The string value of the property.
    * @throws SeriesException
    *           Thrown for all other exceptions.
    * @throws NotFoundException
    *           Thrown if the series or property cannot be found.
    * @throws UnauthorizedException
    *           Thrown if the user is not able to read the series' properties.
    */
   String getSeriesProperty(String seriesID, String propertyName) throws SeriesException, NotFoundException,
           UnauthorizedException;
 
   /**
    * Update a series property or create a new one if it doesn't exist.
    *
    * @param seriesID
    *          The series to attach the property to.
    * @param propertyName
    *          The unique name of the series property
    * @param propertyValue
    *          The value to assign the series property
    * @throws SeriesException
    *           Thrown for all other exceptions.
    * @throws NotFoundException
    *           Thrown if the series or property cannot be found.
    * @throws UnauthorizedException
    *           Thrown if the user is not able to write the series' properties.
    */
   void updateSeriesProperty(String seriesID, String propertyName, String propertyValue) throws SeriesException,
           NotFoundException, UnauthorizedException;
 
   /**
    *
    * @param seriesID
    *          The series to attach the property to.
    * @param propertyName
    *          The unique name of the series property
    * @throws SeriesException
    *           Thrown for all other exceptions.
    * @throws NotFoundException
    *           Thrown if the series or property cannot be found.
    * @throws UnauthorizedException
    *           Thrown if the user is not able to write the series' properties.
    */
   void deleteSeriesProperty(String seriesID, String propertyName) throws SeriesException, NotFoundException,
           UnauthorizedException;
 }