package doc.walkthru;

import java.util.List;

import org.benow.java.resource.Publish;
import org.benow.repository.NoSuchObjectException;
import org.benow.security.permission.Permission.AnonymousAccess;
import org.benow.security.permission.Permission.RequiresPermission;
import org.benow.service.Service;

/**
 * Methods for interacting with the music library 
 * 
 * @author andy
 *
 */
@Publish
@AnonymousAccess
public interface AlbumService extends Service {

  /**
   * @return known albums
   */
  @AnonymousAccess
  public List<Album> getAlbums();


  /**
   * Create a new album with a given title and performer.
   * 
   * @param title
   * @param performer
   * @return the created album.
   */
  @RequiresPermission("modify")
  public Album createAlbum(String title, Performer performer);

  @RequiresPermission("modify")
  public Album createAlbum(Album album);

  /**
   * Adds the given track to the given album.
   * 
   * @param album
   * @param track
   * @return added track on album
   */
  @RequiresPermission("modify")
  public AlbumTrack addTrack(Album album, Track track);

  /**
   * Inserts the given track to the given album at the given position
   * 
   * @param album
   * @param track
   * @param pos
   * @return inserted track on album
   */
  @RequiresPermission("modify")
  public AlbumTrack insertTrack(Object albumKey, Track track, int pos);

  /**
   * Deletes a given album
   * 
   * @param album
   * @return true if successfully deleted
   */
  @RequiresPermission("delete")
  public boolean deleteAlbum(Album album);


  /**
   * Gets a specific album by key
   * 
   * @param key
   * @return
   * @throws NoSuchObjectException
   */
  @AnonymousAccess
  public Album getAlbumByKey(Object key) throws NoSuchObjectException;
}