/**
 * 
 */
package kanta;

import java.util.Iterator;
import java.util.List;



/**
 * Rajapinta rakenteelle, joka tallettaa tietueita.
 * @author vesal
 * @version 24.03.2012
 * @param <TYPE> talletettava tyyppi
 * @example
 * <pre name="testJAVA">
 * public static class Harrastus extends PerusTietue {
 *     private Kentta kentat[] = { 
 *        new IntKentta("id"),
 *        new IntKentta("jäsenId"),
 *        new JonoKentta("ala"),
 *        new IntKentta("aloitusvuosi"),
 *        new IntKentta("h/vko")
 *     };
 *     private static int seuraavaNro = 1;
 *     public Harrastus() { }
 *     public Harrastus(int jnro) { ((IntKentta)(kentat[1])).setValue(jnro); }
 *     @Override public int ekaKentta() { return 2; }
 *     @Override public Kentta[] getKentat() { return kentat; }
 *     @Override public int getSeuraavaNro() { return seuraavaNro; }
 *     @Override protected void setSeuraavaNro(int i) { seuraavaNro = i; }
 *     @Override protected void setKentat(Kentta[] kentat) { this.kentat = kentat; }
 *     @Override public Harrastus clone() throws CloneNotSupportedException {return (Harrastus)super.clone(); }
 *     public int getHarrastusNro() { return ((IntKentta)getKentta(1)).getValue(); }
 *     public void vastaaPitsinNyplays(int nro) {
 *       aseta(1,""+nro); aseta(2,"Pitsin nypläys"); aseta(3,"1952"); aseta(4,"30");
 *     }
 * }
 * public static class Harrastukset extends PerusTietueet<Harrastus> {
 *    public Harrastukset() { super(new Harrastus(),".har",".hbak"); }
 * }   
 */
public interface Tietueet<TYPE extends Tietue> extends Iterable<TYPE>{

    /**
     * @return uusi talletettavan tyyppinen alkio
     */
    public abstract TYPE luoUusi();

    /**
     * Lisää uuden harrastuksen tietorakenteeseen.  Ottaa harrastuksen omistukseensa.
     * @param har lisättävä harrastus.  Huom tietorakenne muuttuu omistajaksi
     */
    public abstract void lisaa(TYPE har);


    /**
     * Korvaa tietueen tietorakenteessa.  Ottaa tietueen omistukseensa.
     * Etsitään samalla tunnusnumerolla oleva tietue.  Jos ei löydy,
     * niin lisätään uutena tietueena.
     * @param tietue lisätäävän tietueen viite.  Huom tietorakenne muuttuu omistajaksi
     * @throws SailoException jos tietorakennen on jo täynnä
     * @example
     * <pre name="test">
     * #THROWS SailoException,CloneNotSupportedException
     * #PACKAGEIMPORT
     * Harrastukset harrastukset = new Harrastukset();
     * Harrastus har1 = new Harrastus(), har2 = new Harrastus();
     * har1.rekisteroi(); har2.rekisteroi();
     * harrastukset.getLkm() === 0;
     * harrastukset.korvaaTaiLisaa(har1); harrastukset.getLkm() === 1;
     * harrastukset.korvaaTaiLisaa(har2); harrastukset.getLkm() === 2;
     * Harrastus har3 = har1.clone();
     * har3.aseta(2,"kkk");
     * Iterator<Harrastus> i2=harrastukset.iterator();
     * i2.next() === har1;
     * harrastukset.korvaaTaiLisaa(har3); harrastukset.getLkm() === 2;
     * i2=harrastukset.iterator();
     * Harrastus h = i2.next();
     * h === har3;
     * h == har3 === true;
     * h == har1 === false;
     * </pre>
     */
    public abstract void korvaaTaiLisaa(TYPE tietue) throws SailoException;

    /**
     * Poistaa valitun harrastuksen
     * @param tietue poistettava harrastus
     * @return tosi jos löytyi poistettava harrastus 
     * @example
     * <pre name="test">
     * #THROWS SailoException 
     * #import java.io.File;
     *  Harrastukset harrasteet = new Harrastukset();
     *  Harrastus pitsi21 = new Harrastus(); pitsi21.vastaaPitsinNyplays(2);
     *  Harrastus pitsi11 = new Harrastus(); pitsi11.vastaaPitsinNyplays(1);
     *  Harrastus pitsi22 = new Harrastus(); pitsi22.vastaaPitsinNyplays(2); 
     *  Harrastus pitsi12 = new Harrastus(); pitsi12.vastaaPitsinNyplays(1); 
     *  Harrastus pitsi23 = new Harrastus(); pitsi23.vastaaPitsinNyplays(2); 
     *  harrasteet.lisaa(pitsi21);
     *  harrasteet.lisaa(pitsi11);
     *  harrasteet.lisaa(pitsi22);
     *  harrasteet.lisaa(pitsi12);
     *  harrasteet.poista(pitsi23) === false ; harrasteet.getLkm() === 4;
     *  harrasteet.poista(pitsi11) === true;   harrasteet.getLkm() === 3;
     *  List<Harrastus> h = harrasteet.annaTietueet(1,1);
     *  h.size() === 1; 
     *  h.get(0) === pitsi12;
     * </pre>
     */
    public abstract boolean poista(TYPE tietue);


    /**
     * Poistaa tietueen jolla on valittu tunnusnumero 
     * @param id poistettavan tietueen tunnusnumero
     * @return 1 jos poistettiin, 0 jos ei löydy
     * @example
     * <pre name="test">
     * PerusTietueet<Harrastus> harrastukset = new PerusTietueet(new Harrastus());
     * Harrastus har1 = new Harrastus(), har2 = new Harrastus(), har3 = new Harrastus();
     * har1.rekisteroi(); har2.rekisteroi(); har3.rekisteroi();
     * int id1 = har1.getTunnusNro();
     * harrastukset.lisaa(har1); harrastukset.lisaa(har2); harrastukset.lisaa(har3);
     * harrastukset.poista(id1+1) === 1;
     * harrastukset.poista(id1+1) === 0; harrastukset.getLkm() === 2;
     * harrastukset.poista(id1) === 1; harrastukset.getLkm() === 1;
     * harrastukset.poista(id1+3) === 0; harrastukset.getLkm() === 1;
     * </pre>
     * 
     */
    public abstract int poista(int id);


   /**
     * Poistaa kaikki tietyn viittauksen tietueet
     * @param viiteNro viite siihen, minkä jäsenen harrastukset poistetaan
     * @param kenttaNro mistä kentästä täytyy vastaava numero löytyä
     * @return montako poistettiin 
     * @example
     * <pre name="test">
     * #THROWS SailoException 
     * #import java.io.File;
     *  Harrastukset harrasteet = new Harrastukset();
     *  Harrastus pitsi21 = new Harrastus(); pitsi21.vastaaPitsinNyplays(2);
     *  Harrastus pitsi11 = new Harrastus(); pitsi11.vastaaPitsinNyplays(1);
     *  Harrastus pitsi22 = new Harrastus(); pitsi22.vastaaPitsinNyplays(2); 
     *  Harrastus pitsi12 = new Harrastus(); pitsi12.vastaaPitsinNyplays(1); 
     *  Harrastus pitsi23 = new Harrastus(); pitsi23.vastaaPitsinNyplays(2); 
     *  harrasteet.lisaa(pitsi21);
     *  harrasteet.lisaa(pitsi11);
     *  harrasteet.lisaa(pitsi22);
     *  harrasteet.lisaa(pitsi12);
     *  harrasteet.lisaa(pitsi23);
     *  harrasteet.poista(2,1) === 3;  harrasteet.getLkm() === 2;
     *  harrasteet.poista(3,1) === 0;  harrasteet.getLkm() === 2;
     *  List<Harrastus> h = harrasteet.annaTietueet(2,1);
     *  h.size() === 0; 
     *  h = harrasteet.annaTietueet(1,1);
     *  h.get(0) === pitsi11;
     *  h.get(1) === pitsi12;
     * </pre>
     */
    public abstract int poista(int viiteNro, int kenttaNro);


    /**
     * Lukee tietueet tiedostosta.
     * @param tied tiedoston nimen alkuosa
     * @throws SailoException jos lukeminen epäonnistuu
     * 
     * @example
     * <pre name="test">
     * #THROWS SailoException 
     * #import java.io.File;
     *  Harrastukset harrasteet = new Harrastukset();
     *  Harrastus pitsi21 = new Harrastus(); pitsi21.vastaaPitsinNyplays(2);
     *  Harrastus pitsi11 = new Harrastus(); pitsi11.vastaaPitsinNyplays(1);
     *  Harrastus pitsi22 = new Harrastus(); pitsi22.vastaaPitsinNyplays(2); 
     *  Harrastus pitsi12 = new Harrastus(); pitsi12.vastaaPitsinNyplays(1); 
     *  Harrastus pitsi23 = new Harrastus(); pitsi23.vastaaPitsinNyplays(2); 
     *  String tiedNimi = "testikelmit";
     *  File ftied = new File(tiedNimi+".har");
     *  ftied.delete();
     *  harrasteet.lueTiedostosta(tiedNimi); #THROWS SailoException
     *  harrasteet.lisaa(pitsi21);
     *  harrasteet.lisaa(pitsi11);
     *  harrasteet.lisaa(pitsi22);
     *  harrasteet.lisaa(pitsi12);
     *  harrasteet.lisaa(pitsi23);
     *  harrasteet.talleta();
     *  harrasteet = new Harrastukset();
     *  harrasteet.lueTiedostosta(tiedNimi);
     *  Iterator<Harrastus> i = harrasteet.iterator();
     *  i.next().toString() === pitsi21.toString();
     *  i.next().toString() === pitsi11.toString();
     *  i.next().toString() === pitsi22.toString();
     *  i.next().toString() === pitsi12.toString();
     *  i.next().toString() === pitsi23.toString();
     *  i.hasNext() === false;
     *  harrasteet.lisaa(pitsi23);
     *  harrasteet.talleta();
     *  ftied.delete() === true;
     *  File fbak = new File(tiedNimi+".hbak");
     *  fbak.delete() === true;
     * </pre>
     */
    public abstract void lueTiedostosta(String tied) throws SailoException;


    /**
     * Tallentaa harrastukset tiedostoon.
     * @throws SailoException jos talletus epäonnistuu
     */
    public abstract void talleta() throws SailoException;


    /**
     * Palauttaa kerhon harrastusten lukumäärän
     * @return harrastusten lukumäärä
     */
    public abstract int getLkm();


    /**
     * Asettaa tiedoston perusnimen ilan tarkenninta
     * @param tied tallennustiedoston perusnimi
     */
    public abstract void setTiedostonPerusNimi(String tied);


    /**
     * Palauttaa tiedoston nimen, jota käytetään tallennukseen
     * @return tallennustiedoston nimi
     */
    public abstract String getTiedostonPerusNimi();


    /**
     * Palauttaa tiedoston nimen, jota käytetään tallennukseen
     * @return tallennustiedoston nimi
     */
    public abstract String getTiedostonNimi();


    /**
     * Palauttaa varakopiotiedoston nimen
     * @return varakopiotiedoston nimi
     */
    public abstract String getBakNimi();


    /**
     * Iteraattori kaikkien harrastusten läpikäymiseen
     * @return harrastusiteraattori
     * 
     * @example
     * <pre name="test">
     * #PACKAGEIMPORT
     * #import java.util.*;
     * 
     *  Harrastukset harrasteet = new Harrastukset();
     *  Harrastus pitsi21 = new Harrastus(2); harrasteet.lisaa(pitsi21);
     *  Harrastus pitsi11 = new Harrastus(1); harrasteet.lisaa(pitsi11);
     *  Harrastus pitsi22 = new Harrastus(2); harrasteet.lisaa(pitsi22);
     *  Harrastus pitsi12 = new Harrastus(1); harrasteet.lisaa(pitsi12);
     *  Harrastus pitsi23 = new Harrastus(2); harrasteet.lisaa(pitsi23);
     * 
     *  Iterator<Harrastus> i2=harrasteet.iterator();
     *  i2.next() === pitsi21;
     *  i2.next() === pitsi11;
     *  i2.next() === pitsi22;
     *  i2.next() === pitsi12;
     *  i2.next() === pitsi23;
     *  i2.next() === pitsi12;  #THROWS NoSuchElementException  
     *  
     *  int n = 0;
     *  int jnrot[] = {2,1,2,1,2};
     *  
     *  for ( Harrastus har:harrasteet ) { 
     *    har.getHarrastusNro() === jnrot[n]; n++;  
     *  }
     *  
     *  n === 5;
     *  
     * </pre>
     */
    @Override
    public abstract Iterator<TYPE> iterator();


    /**
     * Laitetaan muutos, jolloin pakotetaan tallentamaan.  
     */
    public abstract void setMuutos();
    
    
    /**
     * Haetaan kaikki tietyn viitteen tietueet
     * @param tunnusnro etsittävän viitteen tunnusnumero jolle tietueita haetaan
     * @param k etsittävän kentän numero
     * @return tietorakenne jossa viiteet löydetteyihin tietueisiin
     * @example
     * <pre name="test">
     * #import java.util.*;
     * 
     *  Harrastukset harrasteet = new Harrastukset();
     *  Harrastus pitsi21 = new Harrastus(2); harrasteet.lisaa(pitsi21);
     *  Harrastus pitsi11 = new Harrastus(1); harrasteet.lisaa(pitsi11);
     *  Harrastus pitsi22 = new Harrastus(2); harrasteet.lisaa(pitsi22);
     *  Harrastus pitsi12 = new Harrastus(1); harrasteet.lisaa(pitsi12);
     *  Harrastus pitsi23 = new Harrastus(2); harrasteet.lisaa(pitsi23);
     *  Harrastus pitsi51 = new Harrastus(5); harrasteet.lisaa(pitsi51);
     *  
     *  List<Harrastus> loytyneet;
     *  loytyneet = harrasteet.annaTietueet(3,1);
     *  loytyneet.size() === 0; 
     *  loytyneet = harrasteet.annaTietueet(1,1);
     *  loytyneet.size() === 2; 
     *  loytyneet.get(0) == pitsi11 === true;
     *  loytyneet.get(1) == pitsi12 === true;
     *  loytyneet = harrasteet.annaTietueet(5,1);
     *  loytyneet.size() === 1; 
     *  loytyneet.get(0) == pitsi51 === true;
     * </pre> 
     */
    public abstract List<TYPE> annaTietueet(int tunnusnro, int k);
    

    /**
     * Palauttaa "taulukossa" hakuehtoon vastaavien tietueiden viitteet
     * @param hakuehto hakuehto
     * @param k etsittävän kentän indeksi 
     * @return tietorakenteen löytyneistä tietueista
     * @example
     * <pre name="test">
     * #THROWS SailoException 
     *  Harrastukset harrastukset = new Harrastukset();
     *  Harrastus har1 = new Harrastus(); har1.parse("1|2|Possujen jahtaaminen|1940|22");
     *  Harrastus har2 = new Harrastus(); har2.parse("2|1|Poikien hoitaminen|1953|1");
     *  Harrastus har3 = new Harrastus(); har3.parse("3|2|Kelmien kerho|1948|20");
     *  Harrastus har4 = new Harrastus(); har4.parse("4|1|Kalastus|1947|20");
     *  Harrastus har5 = new Harrastus(); har5.parse("5|3|Viulu|1952|15");
     *  harrastukset.lisaa(har1); harrastukset.lisaa(har2); harrastukset.lisaa(har3); 
     *  harrastukset.lisaa(har4); harrastukset.lisaa(har5);
     *  List<Harrastus> loytyneet;
     *  loytyneet = harrastukset.etsi("*s*",2);
     *  loytyneet.size() === 2;
     *  loytyneet.get(0) == har4 === true;
     *  loytyneet.get(1) == har1 === true;
     *   
     *  loytyneet = harrastukset.etsi("*5*",3);
     *  loytyneet.size() === 2;
     *  loytyneet.get(0) == har5 === true;
     *  loytyneet.get(1) == har2 === true;
     * </pre>
     */
    public abstract List<TYPE> etsi(String hakuehto, int k);

    
    /**
     * Etsii tietueen id:n perusteella
     * @param id tunnusnumero, jonka mukaan etsitään
     * @return tietue jolla etsittävä id tai null
     * @example
     * <pre name="test">
     *  Harrastukset harrastukset = new Harrastukset();
     *  Harrastus har1 = new Harrastus(); har1.parse("1|2|Possujen jahtaaminen|1940|22");
     *  Harrastus har2 = new Harrastus(); har2.parse("2|1|Poikien hoitaminen|1953|1");
     *  Harrastus har3 = new Harrastus(); har3.parse("3|2|Kelmien kerho|1948|20");
     *  harrastukset.lisaa(har1); harrastukset.lisaa(har2); harrastukset.lisaa(har3); 
     *  harrastukset.annaId(1) == har1 === true;
     *  harrastukset.annaId(2) == har2 === true;
     *  harrastukset.annaId(3) == har3 === true;
     * </pre>
     */
    public abstract TYPE annaId(int id);
}