/**
  * Interfaccia MyList
  * Tipo di dati astratto per esercitazione: laboratorio VIII
  * Rappresenta una sequenza di dati. A ciascun dato e' associata una posizione
  * espressa con un numero intero >= 0, detto indice.
  * E' una semplificazione dell'interfaccia List della API specification for
  * the Java 2 Platform Standard Edition
  * Non definisce l'iteratore perche' l'argomento deve essere ancora introdotto
  * nel corso.
  *
  * @author A. Luchetta
  * @version 24-Nov-2006
  * @see Container
  * @see java.util.List
  */
public interface MyList extends Container
{
   /**
      aggiunge l'elemento specificato alla fine della lista
      @param obj nuovo elemento da aggiungere
   */
   void add(Object obj);

   /**
      inserisce l'elemento specificato alla posizione specificata nella lista.
      Sposta a destra l'elemento attualmente in quella posizione (se esistente)
      e tutti gli elementi successivi (incrementa di uno i loro indici)
      @param index indice a cui inserire l'elemento
      @param obj nuovo elemento da aggiungere
      @throws ArrayIndexOutOfBoundsException se l'indice non e' nell'intervallo
      degli indici ammessi (index < 0 || index > size())
   */
   void add(int index, Object obj);

   /**
      verifica se l'elemento specificato e' un componente della lista
      @param obj elemento da verificare
      @return true se e solo se l'elemento specificato e' uguale a un
      componente della lista, come determinato dal metodo equals;
      false altrimenti
      @throws NullPointerException se obj e' uguale a null
   */
   boolean contains(Object obj);

   /**
      restituisce l'elemento all'indice specificato
      @param index indice
      @return elemento all'indice specificato
      @throws ArrayIndexOutOfBoundsException se (index < 0 || >= size())
   */
   Object get(int index);

   /**
       ricerca la prima occorrenza dell'elemento passato come parametro,
       verificando l'eguaglianza tramite il metodo equals
       iniziando la ricerca dall'indice zero
       @param obj l'elemento oggetto della verifica
       @return indice della prima occorrenza, -1 se l'elemento non e' presente
   */
   int indexOf(Object obj);

   /**
      rimuove l'elemento alla posizione specificata nella lista.
      Sposta ogni elemento successivo a sinistra (decrementa di uno i loro indici)
      Ritorna l'elemento che ha rimosso dalla lista.
      @param index indice dell'elemento da rimuovere
      @throws ArrayIndexOutOfBoundsException se (index < 0 || >= size())
   */
   Object remove(int index);

   /**
      rimuove la prima occorrenza nella lista dell'elemento specificato.
      Se la lista non contiene l'elemento, rimane immutata.
      @param obj elemento da rimuovere
      @return true se l'elemento e' rimosso, false altrimenti.
      @NullPointerException se obj e' uguale a null
   */
   boolean remove(Object obj);
}