Vyjímky a javadoc

Materiály

• The Java Tutorial: Exceptions
• Tutorialspoint: Javadoc

javadoc

Javadoc je program obsažený v JDK a slouží ke generování dokumentace ve formátu HTML ze zdrojového kódu, který vyžaduje psaní dokumentace v dané syntaxi. Dokumentace je podobná víceřádnovým komentářům, ale místo /* */ se používá /** */. Dokumentace může obsahovat HTML tagy.

Příklad

        
    /**
     * Třída reprezentující studenta.
     *
     * @author Roman Vyjidacek
     * @version 1.0
     * @since 2017-11-16
     */
    public class Student {

        private String name;
        private int age;
        private int clazz;

        /**
         * Konstruktor pro třídu Student
         * @param name Jméno studenta
         * @param age Věk studenta
         */
        public Student(String name, int age) {
            this.name = name;
            this.age = age;
            this.clazz = 1;
        }

        /**
         * Getter pro jmeno studenta.
         * @return Jmeno studenta
         */
        public String getName() {
            return name;
        }

        /**
         * Setter pro atribut name
         * @param name Nove jmeno studenta
         */
        public void setName(String name) {
            this.name = name;
        }

        /**
         * Metoda ktera vyvola vyjimku
         * @param a Cislo
         * @param b Retezec
         * @throws IOException Vyjimka pri cteni se souboru.
         */
        public void methodThatThrows(int a, String b) throws IOException {
            // Kod ktery vyvola vyjimku
        }
    }
        
    

Javadoc tagy

Generování dokumentace

Dokumentaci lze vygenerovat pomocí aplikace javadoc v terminálu nebo v IDE (IDEA: tools > Generate JavaDoc...)

    
    javadoc Student.java
    

Vyjímky

Vyjímka je událost, která nastane v průběhu vykonávání programu a narušuje očekáváné vykonávání programu.

Proč používat vyjímky

Uvažujme operaci čtení ze souboru.

    readFile {
        open the file;
        determine its size;
        allocate that much memory;
        read the file into memory;
        close the file;
    }
    

Jak je vidět může při otevření souboru nastat spousta nepředvídaných situací:

• Co se stane pokud soubor nelze otevřít?
• Co se stane když nejsme schopni zjístit velikost souboru?
• Co se stane když nemůžeme alokovat dostatek paměti?
• Co se stane pokud čtení nelze provést?
• Co se stane když nemůžeme uzavřít soubor.

Řešení bez vyjímek

    
    errorCodeType readFile {
        initialize errorCode = 0;

        open the file;
        if (theFileIsOpen) {
            determine the length of the file;
            if (gotTheFileLength) {
                allocate that much memory;
                if (gotEnoughMemory) {
                    read the file into memory;
                    if (readFailed) {
                        errorCode = -1;
                    }
                } else {
                    errorCode = -2;
                }
            } else {
                errorCode = -3;
            }
            close the file;
            if (theFileDidntClose && errorCode == 0) {
                errorCode = -4;
            } else {
                errorCode = errorCode and -4;
            }
        } else {
            errorCode = -5;
        }
        return errorCode;
    }
    

Výše uvedené řešení je velmi nepřehledné. Abychom se mohli podobnému kódu vyhnout tak použijeme vyjímky.

    
    readFile {
        try {
            open the file;
            determine its size;
            allocate that much memory;
            read the file into memory;
            close the file;
        } catch (fileOpenFailed) {
           doSomething;
        } catch (sizeDeterminationFailed) {
            doSomething;
        } catch (memoryAllocationFailed) {
            doSomething;
        } catch (readFailed) {
            doSomething;
        } catch (fileCloseFailed) {
            doSomething;
        }
    }
    

Použití vyjímek

    
    // Základní syntaxe

    try {
        // Kód který může vyvolat vyjímku.
    } catch (ExceptionType name) {
        // Kód pro odchycení vyjímky.
    } catch (ExceptionType name) {
        // Kód pro odchycení vyjímky.
    } finally {
        // Kód který se vykoná pokaždé.
    }

    // Vyvolání vyjímky

    throw new IOException("File not found");

    // Rozšíříme definici metody o klíčové slovo throws,
    // které říká jaké vyjímky může metoda vyvolat

    public void methodThatThrows(int a, String b) throws IOException, SQLException {
        // Kod ktery vyvola vyjimku
    }

    // Příklad který vyvolá vyjímku z důvodu existence souboru.

    private List<Integer> list;
    private static final int SIZE = 10;

    public void readList() {
        FileReader out = null;

        try {
            out = new FileReader(new File("OutFile.txt"));
        } catch (IOException e) {
            System.err.println(e.getMessage());
        }
    }
    

try-with-resources

try-with-resources je speciální přpad výrazu try který po vykonání bloku automaticky uzavře všechny zdroje.

Speciál

    
    // Metoda přeposílá vyjímku dále

    static String readFirstLineFromFile(String path) throws IOException {
        try (BufferedReader br = new BufferedReader(new FileReader(path))) {
            return br.readLine();
        }
    }

    // Metoda zpracuje vyjímku a neposílá ji dál

    static String readFirstLineFromFile(String path) {
        try (BufferedReader br = new BufferedReader(new FileReader(path))) {
            return br.readLine();
        } catch (IOException e) {
            System.err.println(e.getMessage());
        }
    }
    

Definice vlastní vyjímky

V Javě můžeme definovat vlastní typy vyjímek a do děděním třídy Exception.

    
    public class DatabaseException extends Exception {
        private static final long serialVersionUID = 1L;

        public DatabaseException() {
            super();
        }

        public DatabaseException(String e) {
            super(e);
        }

        public DatabaseException(Throwable throwable) {
            super(throwable);
        }

        public DatabaseException(String e, Throwable t) {
            super(e, t);
        }
    }
    

Úkoly

1. Třídy a metody ze druhého semináře rozšiřte o komentáře a vygenerujte dokumentaci.

2. Rozšiřte/upravte úkol č. 5 z předminulého semináře (RPN kalkulačku), tj. metodu rpnCalc(String expr, Map <String, Object> variables> o následující vlastnosti:

   Metoda by měla umět vyhodnocovat výrazy s celými čísly (např. 1, 12, -123) i s čísly s plovoucí řádovou čárkou (např. 1.0, 2.23, 45.56, -78.123). Pokud dojde k sečtení (odečtení, atd.) dvou čísel, kde jedno je číslo s plovoucí řádovou čárkou, výsledkem je číslo s plovoucí řádovou čárkou.

       1.1 2 +    -> 3.1
       1 2 +      -> 3
   

   Přidejte podporu pravdivostních hodnot reprezentovaných literály (#t, #f) a přidejte operátory <, > =, !=, <=, >=, porovnávající čísla a pravdivostní hodnoty. Pokud hodnoty nejde porovnat, skončí metoda vyjímkou.

       1.1 2 <    -> #t
       #f #t <    -> #t
       #f #t >    -> #f
       1 #f =     -> Exception - Neporovnatelne hodnoty
   

   Přidejte ternární operátor "?", který odebere z vrcholu zásobníku pravdivostní hodnotu a dvě další hodnoty. Pokud byla na vrcholu zásobníku hodnota #t, vrátí druhou odebranou hodnotu, jinak vrátí třetí. Pokud na vrcholu zásobníku nebude pravdivostní hodnota, skončí metoda vyjímkou.

       1 2 3 4 < ?    -> 2
       1 2 3 4 + ?    -> Exception - 7 neni pravdivostni hodnota
   

   Program napište tak, aby adekvátně ošetřil i další chybové stavy, např. dělení nulou, špatně zapsaný výraz, a podobně. Kód upravte tak, aby nebyl realizován jako jedna metoda a byl řádně rozčleněn a dokumentován.