package elte.java2_utikalauz5.programok;

/**
Forrásfájlok megtekintését, valamint egyéb fájlok letöltését biztosító taglet.
Forrásfájl megadása a {@code @link.forrásfájl}, letöltendő fájl megadása pedig a
{@code @link.letöltés} új dokumentációs blokkleíró elemekkel történik, melyek
feldolgozását ez a <A href="http://java.sun.com/j2se/1.5.0/docs/guide/javadoc"
target=_blank>{@code javadoc}</A> taglet végzi.<P>
Az elemek szintaxisa a következő:<P>
{@code @link.forrásfájl} <I>URL</I>&nbsp;&nbsp;<I>forrásfájlnév</I><BR>
további opcionális magyarázó szöveg.<P>
{@code @link.letöltés} <I>URL</I>&nbsp;&nbsp;<I>fájlnév</I><BR>
további opcionális magyarázó szöveg.

@link.forrásfájl {@docRoot}/../data/programok/src TagletTeszt.java
@link.letöltés {@docRoot}/../data/programok TagletTeszt.jar
@since Java 2 Útikalauz programozóknak 5.0
*/
public class TagletTeszt implements com.sun.tools.doclets.Taglet,  //hagyományos
        com.sun.tools.doclets.internal.toolkit.taglets.Taglet{//és direkt taglet

    /** A feldolgozandó dokumentációs blokkleíró elem neve.  */
    private final String elemnév;

    /** A hivatkozás megjelenítéséhez használt cél neve.  */
    private final String cél;

    /**
    Taglet konstruktor.

    @param elemnév A feldolgozandó dokumentációs blokkleíró elem neve.
    @param cél A hivatkozás megjelenítéséhez használt cél neve.
    */
    public TagletTeszt(String elemnév, String cél) {
        this.elemnév=elemnév;
        this.cél=cél;
    }

    /**
    Megadja a kezelt dokumentációs elem nevét.

    @return A kezelt dokumentációs elem neve.
    */
    public String getName() {
        return elemnév;
    }

    /**
    Megadja, hogy a kezelt elem használható-e mezők dokumentációs leírásában.

    @return Hamisat ad vissza, mert nem használható mezők leírásában.
    */
    public boolean inField() {
        return false;
    }

    /**
    Megadja, hogy a kezelt elem használható-e konstruktorok leírásában.

    @return Hamisat ad vissza, mert nem használható konstruktorok leírásában.
    */
    public boolean inConstructor() {
        return false;
    }

    /**
    Megadja, hogy a kezelt elem használható-e metódusok leírásában.

    @return Hamisat ad vissza, mert nem használható metódusok leírásában.
    */
    public boolean inMethod() {
        return false;
    }

    /**
    Megadja, hogy a kezelt elem használható-e az áttekintő leírásban.

    @return Hamisat ad vissza, mert nem használható az áttekintő leírásban.
    */
    public boolean inOverview() {
        return false;
    }

    /**
    Megadja, hogy a kezelt elem használható-e csomagok dokumentációs leírásában.

    @return Igazat ad vissza, mert használható csomagok leírásában.
    */
    public boolean inPackage() {
        return true;
    }

    /**
    Megadja, hogy a kezelt elem használható-e típusok dokumentációs leírásában.

    @return Igazat ad vissza, mert használható interfészek leírásában.
    */
    public boolean inType() {
        return true;
    }

    /**
    Megadja, hogy a kezelt elem beágyazható dokumentációs elem-e.

    @return Hamisat ad vissza, mert blokkleíró elemeket kezelünk.
    */
    public boolean isInlineTag() {
        return false;
    }

    /**
    Adott blokkleíró elemet kezelő taglet regisztrálása.

    @param elemnév A feldolgozandó dokumentációs blokkleíró elem neve.
    @param cél A hivatkozás megjelenítéséhez használt cél neve.
    @param tagletek A tagletek bejegyzéseinek regisztrációja.
    */
    private static void regisztrálás(String elemnév, String cél,
    java.util.Map<String, com.sun.tools.doclets.internal.toolkit.taglets.Taglet>
            tagletek) {
        TagletTeszt teszt = new TagletTeszt(elemnév, cél);  //taglet létrehozása
        com.sun.tools.doclets.internal.toolkit.taglets.Taglet taglet =
        teszt instanceof com.sun.tools.doclets.internal.toolkit.taglets.Taglet ?
                                         //direkt taglet megvalósítás vizsgálata
                  (com.sun.tools.doclets.internal.toolkit.taglets.Taglet)teszt :
                                                            //be kell csomagolni
         new com.sun.tools.doclets.internal.toolkit.taglets.LegacyTaglet(teszt);
        tagletek.put(elemnév, taglet);                 //új taglet regisztrálása
    }

    /**
    Saját tagletek regisztrálása.

    @param tagletek A tagletek bejegyzéseinek regisztrációja.
    */
    public static void register(java.util.Map<String,
            com.sun.tools.doclets.internal.toolkit.taglets.Taglet> tagletek) {
        regisztrálás("link.forrásfájl", "_blank", tagletek);
        regisztrálás("link.letöltés", null, tagletek);
    }

    /**
    Hagyományos taglet dokumentációs elemet kezelő metódusa.

    @param elem Az aktuális dokumentációs elem tartalma.
    @return A kapott dokumentációs elem feldolgozásának eredménye HTML formában.
    */
    public String toString(com.sun.javadoc.Tag elem) {
        return toHTML(elem.text());   //HTML létrehozása az elem szövege alapján
    }

    /**
    Hagyományos taglet dokumentációs elemeket kezelő metódusa.

    @param elemek Az aktuális dokumentációs elemek tartalma.
    @return A kapott elemek feldolgozásának eredménye HTML formában.
    */
    public String toString(com.sun.javadoc.Tag[] elemek) {
        String html = "";                                     //visszaadott HTML
        for (com.sun.javadoc.Tag elem:elemek) html+=toString(elem); //eredmények
        return html;                                //összefűzése és visszaadása
    }

    /**
    Direkt taglet dokumentációs elemet kezelő metódusa.

    @param elem Az aktuális dokumentációs elem tartalma.
    @param kimenet A taglet kimeneti kapcsolata.
    @return A kapott dokumentációs elem feldolgozásának eredménye HTML formában.
    */
    public com.sun.tools.doclets.internal.toolkit.taglets.TagletOutput
           getTagletOutput(com.sun.javadoc.Tag elem,
           com.sun.tools.doclets.internal.toolkit.taglets.TagletWriter kimenet){
        com.sun.tools.doclets.internal.toolkit.taglets.TagletOutput html =
            kimenet.commentTagsToOutput(elem, elem.inlineTags());
         //az eredeti tartalomban a beágyazott dokumentációs elemek kiértékelése
        html.setOutput(toHTML(html.toString()));         //majd HTML létrehozása
        return html;                                            //és visszaadása
    }

    /**
    Direkt taglet dokumentációs elemeket kezelő metódusa.

    @param elemek Az aktuális dokumentációs elemek tartalma.
    @param kimenet A taglet kimeneti kapcsolata.
    @return A kapott elemek feldolgozásának eredménye HTML formában.
    */
    public com.sun.tools.doclets.internal.toolkit.taglets.TagletOutput
           getTagletOutput(com.sun.javadoc.Doc elemek,
           com.sun.tools.doclets.internal.toolkit.taglets.TagletWriter kimenet){
        com.sun.tools.doclets.internal.toolkit.taglets.TagletOutput html = null;
        StringBuilder sb = new StringBuilder();            //eredmények tárolója
        for (com.sun.javadoc.Tag elem : elemek.tags(getName())) {
            html = getTagletOutput(elem, kimenet);
            sb.append(html.toString());                 //eredmények összefűzése
        }
        if (html!=null) html.setOutput(sb.toString());    //eredmény visszaadása
        return html;
    }

    /**
    Dokumentációs elem szövegének alapján HTML generálása.

    @param elem Az aktuális dokumentációs elem szövegtartalma.
    @return A tartalom feldolgozásának eredménye HTML formában.
    */
    private String toHTML(String elem) {
        int pozíció = elem.indexOf('\n');                 //első sor megkeresése
        String részletek = "";
        if (pozíció > 0) {
            részletek = elem.substring(pozíció);          //magyarázó szövegrész
            elem = elem.substring(0, pozíció);           //első sor leválasztása
        }
        pozíció=elem.lastIndexOf(' ');//fájlnév és URL kiolvasása az első sorból
        String url = elem.substring(0, pozíció);
        String fájlnév = elem.substring(pozíció+1);
        StringBuilder html = new StringBuilder();  //visszaadott HTML felépítése
        html.append("<DT><B>");
        html.append(       //Nagykezdőbetűs listafejléc generálása az elemnévből
            Character.toUpperCase(elemnév.charAt(elemnév.indexOf('.')+1)));
        html.append(elemnév.substring(elemnév.indexOf('.')+2));
        html.append(":</B><DD>");
        html.append("<A href=\"");                 //hiperhivatkozás létrehozása
        html.append(url);
        html.append('/');
        html.append(fájlnév);
        html.append('"');
        if (cél!=null) {            //ha van cél megadva, akkor annak generálása
            html.append(" target=");
            html.append(cél);
        }
        html.append('>');
        html.append(fájlnév);       //hiperlinkhivatkozás szövege a fájlnév lesz
        html.append("</A>");
        html.append(részletek); //utána esetleges magyarázó szöveg megjelenítése
        html.append("</DD>\n");
        return html.toString();                      //generált HTML visszaadása
    }
}