Základním a standardním prostředkem je tzv. dokumentace API

Zde se budeme věnovat především dokumentaci programátorské, určené těm, kdo budou náš kód využívat ve svých programech, rozšiřovat jej, udržovat jej. Programátorské dokumentaci se říká dokumentace API (apidoc, apidocs).

Při jejím psaní dodržujeme tato pravidla:

Podobně jako např. v C/C++:

Dokumentační komentáře uvádíme:

Dokumentace má standardně podobu HTML stránek (s rámy i bez)

Dokumentace je generována nástrojem javadoc z

Lze tedy (základním způsobem) dokumentovat i program bez vložených komentářů!

Chování javadoc můžeme změnit

Princip generování ze zdrojových textů pomocí speciálních docletů se dnes používá i po jiné než dokumentační účely - např. pro generátory zdrojových kódu aplikací EJB apod.

javadoc můžeme podrobněji instruovat pomocí značek vkládaných do dokumentačních komentářů, např.:

Zdrojový text třídy Window:

/** 
 * Klasse, die ein Fenster auf dem Bildschirm repräsentiert 
 * Konstruktor zum Beispiel: 
 * <pre> 
 * Window win = new Window(parent); 
 * win.show(); 
 * </pre> 
 *
 * @see awt.BaseWindow 
 * @see awt.Button 
 * @version 1.2 31 Jan 1995 
 * @author Bozo the Clown 
 **/ 
class Window extends BaseWindow {
    ... 
}

Příklad dokumentačního komentáře k proměnné:

/** 
  * enthält die aktuelle Anzahl der Elemente. 
  * muss positiv und kleiner oder gleich der Kapazität sein 
  **/
protected int count;

Tyto a další příklady a odkazy lze vidět v původním materiálu JavaStyleGuide des IGE, odkud byly ukázky převzaty.

Zdroják s dokumentačními komentáři - Komentáře

Ukázkové spuštení

javadoc

javadoc -classpath . -d apidocs svet

vytvoří dokumentaci tříd z balíku svet do adresáře apidocs

Distribucí nemyslíme použití nástroje typu "InstallShield"..., ale spíše něčeho podobného tar/ZIPu

Volby JAR lze vypsat i spuštěním jar bez parametrů:

Obrázek 1.1. Volby nástroje JAR

Vezměme následující zdrojový text třídy JarDemo v balíku tomp.ucebnice.jar, tj. v adresáři c:\tomp\pb162\java\tomp\ucebnice\jar:

Obrázek 1.2. Třída JarDemo

Vytvoříme archív se všemi soubory z podadresáře tomp/ucebnice/jar (s volbou c - create, v - verbose, f - do souboru):

Obrázek 1.3. Vytvoření archívu se všemi soubory z podadresáře tomp/ucebnice/jar

Vzniklý .jar soubor lze prohlédnout/rozbalit také běžným nástrojem typu unzip, gunzip, WinZip, PowerArchiver nebo souborovým managerem typu Servant Salamander...

Obrázek 1.4. .jar archiv v okně PowerArchiveru

Tento archív rozbalíme v adresáři /temp následujícím způsobem:

Obrázek 1.5. Vybalení všech souborů z archívu

Formáty vycházející z JAR:

liší se podrobnějším předepsáním adresářové struktury a dalšími povinnými metainformacemi

Vytvoříme jar s manifestem obsahujícím tento řádek:

Main-Class: NázevSpouštěnéTřídy

poté zadáme:

java 
-jar
 
NázevBalíku
.jar

a spustí se metoda main třídy NázevSpouštěnéTřídy.

Nejprve vytvoříme soubor manifestu. Příklad jeho obsahu:

Obrázek 1.6. Soubor manifestu

Následně zabalíme archív s manifestem:

Obrázek 1.7. Zabalení archívu s manifestem

Spuštění aplikace zabalené ve spustitelném archívu je snadné:

java 
-jar
 jardemo.jar

a spustí se metoda main třídy tomp.ucebnice.jar.JarDemo:

Obrázek 1.8. Spuštění aplikace z arhcivu

založeny na v/v proudech

plně platformově nezávislé

V/V proudy jsou

koncipovány jako "stavebnice" - lze vkládat do sebe a tím přidávat vlastnosti, např.

is = new InputStream(...); 
bis = new BufferedInputStream(is);    

Téměř vše ze vstupních/výstupních tříd a rozhraní je v balíku java.io.

počínaje J2SDK1.4 se rozvíjí alternativní balík - java.nio (New I/O)

Blíže viz dokumentace API balíků java.io, java.nio.

vše je opět v balíku java.io

základem je třída java.io.File - nositel jména souboru, jakási "brána" k fyzickým souborům na disku.

používá se jak pro soubory, tak adresáře, linky i soubory identifikované UNC jmény (\\počítač\adresář...)

opět plně platformově nezávislé

na odstínění odlišností jednotlivých systémů souborů lze použít vlastností (uvádíme jejich hodnoty pro JVM pod systémem MS Windows):

Vytvoření konstruktorem - máme několik možností:

Testy existence a povahy souboru:

Test práv ke čtení/zápisu:

Vytvoření souboru nebo adresáře:

Vytvoření dočasného (temporary) souboru:

Zrušení:

Přejmenování (ne přesun mezi adresáři!):

Další vlastnosti:

Blíže viz dokumentace API třídy File.

Klíčem je opět třída File - použitelná i pro adresáře

Jak např. získat (filtrovaný) seznam souborů v adresáři?

pomocí metody File[] listFiles(FileFilter ff) nebo podobné

File[] listFiles(FilenameFilter fnf):

FileFilter je rozhraní s jedinou metodou boolean accept(File pathname), obdobně FilenameFilter, viz Popis API java.io.FilenameFilter

Vstupní jsou odvozeny od abstraktní třídy InputStream

Výstupní jsou odvozeny od abstraktní třídy OutputStream

Uvedené metody, kromě abstract byte read(), nemusejí být nutně v neabstraktní podtřídě překryty.

java.io.FilterInputStream - je bázová třída k odvozování všech vstupních proudů přidávajících vlastnost/schopnost filtrovat poskytnutý vstupní proud.

Příklady filtrů (ne všechny jsou v java.io!):

Příklad rekonstrukce objektů ze souborů

FileInputStream istream = new FileInputStream("t.tmp"); 
ObjectInputStream p = new ObjectInputStream(istream); 
int i = p.readInt(); 
String today = (String)p.readObject(); 
Date date = (Date)p.readObject(); 
istream.close();    

základem je abstraktní třída Reader, konkrétními implementacemi jsou:

nebudeme důkladně probírat všechny typy

principy:

Příklady:

Ze vstupního binárního proudu InputStream (čili každého) je možné vytvořit znakový Reader pomocí

// nejprve  binární vstupní proud - toho kódování znaků nezajímá 
InputStream is = ...

// znakový proud isr 
// použije pro dekódování standardní znakovou sadu
Reader isr = new InputStreamReader(is); 

// sady jsou definovány v balíku 
java.nio
 
Charset chrs = java.nio.Charset.forName("ISO-8859-2"); 

// znakový proud isr2 
// použije pro dekódování jinou znakovou sadu 
Reader isr2 = new InputStreamReader(is, chrs); 

Podporované názvy znakových sad naleznete na webu IANA Charsets.

Obdobně pro výstupní proudy - lze vytvořit Writer z OutputStream.

Tutoriály k Java I/O: kapitola z Sun Java Tutorial

Demo programy na serializaci (z učebnice): Serializace objektů