Kapitola 1. Přednáška 11 - Použití javadoc a jar. Vstupy a výstupy
Obsah
Dokumentace a distribuce aplikací..................................................................................1
Dokumentace javových programů ..........................................................................2
Typy komentáru..................................................................................................2
Kde uvádíme dokumentační komentáře ...................................................................3
Generování dokumentace......................................................................................3
Značky javadoc ...............................................................................................3
Příklad zdrojového textu se značkami javadoc ..........................................................4
Spouštění j a vado c............................................................................................4
Příklady ............................................................................................................5
Distribuce aplikací ..............................................................................................5
Spustení jar .....................................................................................................5
Vo lby j a r.........................................................................................................6
j a r - příklad .....................................................................................................6
Rozšíření .jar archívů .......................................................................................8
Tvorba spustitelných archívů.................................................................................8
Vytvoření spustitelného archívu - příklad.................................................................9
Spuštění archívu - příklad .....................................................................................9
Další příklad spuštění jar ....................................................................................9
Vstupy a výstupy v Jávě .............................................................................................10
Koncepce vstupně/výstupních operací v Jávě..........................................................10
Práce se soubory ...............................................................................................10
Třída File......................................................................................................11
Třída File (2) .................................................................................................12
Třída File (3) .................................................................................................12
Práce s adresáři.................................................................................................14
Práce s binárními proudy ....................................................................................14
Vstupní binární proudy.......................................................................................14
Důležité neabstraktní třídy odvozené od InputStream..........................................14
Další vstupní proudy..........................................................................................15
Práce se znakovými proudy.................................................................................15
Výstupní proudy ...............................................................................................16
Konverze: znakové <-> binární proudy..................................................................16
Serializace objektů ............................................................................................17
Odkazy ...........................................................................................................17
Dokumentace a distribuce aplikací
i
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
• Dokumentace javových programů, dokumentace API
• Typy komentářů - dokumentační komentáře Generování dokumentace
• Značky javadoc
• Distribuční archívy jar
• Vytvoření archívu, metainformace Spustitelné archívy
Dokumentace javových programů
Základním a standardním prostředkem je tzv. dokumentace API
• Dokumentace j e naprosto nezbytnou součástí j avových programů.
• Rozlišujeme dokumentaci např. instalační, systémovou, uživatelskou, programátorskou...
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:
Dokumentujeme především veřejné (public) a chráněné (protected) prvky (metody, proměnné). Ostatní dle potřeby.
• Dokumentaci píšeme přímo do zdrojového kódu programu ve speciálních dokumentačních komentářích vpisovaných před příslušné prvky (metody, proměnné).
Dovnitř metod píšeme jen pomocné komentáře pro programátory (nebo pro nás samotné).
Typy komentářů
Podobně jako např. v C/C++:
řádkové od značky // do konce řádku, nepromítnou se do dokumentace API
blokové začínají / * pak je text komentáře, končí */ na libovolném počtu řádků
dokumentační od značky /** po značku */ může být opět na libovolném počtu řádků
Každý další řádek může začínat mezerami či *, hvězdička se v komentáři neprojeví.
2
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
Kde uvádíme dokumentační komentáře
Dokumentační komentáře uvádíme:
Před hlavičkou třídy - pak komentuje třídu jako celek.
Před hlavičkou metody nebo proměnné - pak komentuje příslušnou metodu nebo proměnnou.
• Celý balík (package) je možné komentovat speciálním samostatným HTML souborem package-summary . html uloženým v adresáři balíku.
Generování dokumentace
Dokumentace má standardně podobu HTML stránek (s rámy i bez) Dokumentace je generována nástrojem j a vado c z
1. dokumentačních komentářů
2. i ze samotného zdrojového textu
Lze tedy (základním způsobem) dokumentovat i program bez vložených komentářů! Chování j a vado c můžeme změnit
1. volbami (options) při spuštění,
2. použitím jiného tzv. docletu, což je třída implementující potřebné metody pro generování komentářů.
Princip generování ze zdrojových textů pomocí speciálních docletu se dnes používá i po jiné než dokumentační účely - např. pro generátory zdrojových kódu aplikací EJB apod.
Značky javadoc
javadoc můžeme podrobněji instruovat pomocí značek vkládaných do dokumentačních komentářů, např.:
@author specifikuje autora API/programu
@version označuje verzi API, např. "1.0"
@deprecated informuje, že prvek je zavrhovaný
3
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
©exception popisuje informace o výjimce, kterou metoda propouští ("vyhazuje")
@param popisuje jeden parametr metody
@since uvedeme, od kdy (od které verze pg.) je věc podporována/přítomna
@see uvedeme odkaz, kam je také doporučeno nahlédnout (související věci)
Příklad zdrojového textu se značkami javadoc
Zdrojový text třídy Window:
* Klasse, die ein Fenster auf dem Bildschirm repräsentiert
* Konstruktor zum Beispiel:
*
* Window win = new Window(parent);
* win.show();
*
*
* @see awt.BaseWindow
* @see awt.Button
* Eversion 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 [http://www.iam.unibe.ch/~scg/Resources/PSE/2001/WWW/projektHandbuch/codeInspections/JavaStyl eGuide.html], odkud byly ukázky převzaty.
Spouštění javadoc
javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]
4
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
možné volby:
• -help,-verbose
• -public, -protected, -package, -private - specifikuje, které prvky mají být v dokumentaci zahrnuty (implicitně: -protected)
• -d destinationdirectory - kam se má dok. uložit -doctitle title - titul celé dokumentace
Příklady
Zdroj ák s dokumentačními komentáři - Komentáře
[http://www.fi.muni.cz/~tomp/java/ucebnice/javasrc/svet/Clovek.java]
Ukázkové spuštění
j avadoc
javadoc -classpath . -d apidocs svet
vytvoří dokumentaci tříd z balíku s vet do adresáře apidocs
Distribuce aplikací
Distribucí nemyslíme použití nástroje typu "InstallShield"..., ale spíše něčeho podobného tar/ZIPu
• Java na sbalení množiny souborů zdrojových i přeložených (. clas s) nabízí nástroj jar.
Sbalením vznikne soubor (archív) .jar formátově podobný ZIPu (obvykle je to ZIP formát), ale nemusí být komprimován.
Kromě souborů obsahuje i metainformace (tzv. MANIFEST)
Součástí archívu nejsou jen .class soubory, ale i další zdroje, např. obrázky, soubory s národními variantami řetězců, zdrojové texty programu, dokumentace...
Spuštění jar
• jar {ctxu} [vfmOM] [jar-file] [manifest-file] [-C dir] files
c - vytvoří archív
t - vypíše obsah archívu
5
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
• x - extrahuje archív
• u - aktualizuje obsah archívu volby:
• v - verbose
0 - soubory nekomprimuje
f - pracuje se se souborem, ne se "stdio"
• m - pribalí metainformace z manifest-file
parametr files uvádí, které soubory se sbalí - i nejavove (např. typicky dokumentace API HTML, datové soubory)
Volby jar
Volby JAR lze vypsat i spuštěním j ar bez parametrů:
Obrázek 1.1. Volby nástroje JAR
H Command Shell
C:\tomp\pbl62\jaua>jar
Usage: jar íctxu)[ufmBMi] [jar-file] [nanifest-file] [-C dir] files ...
Options:
-c create neu archive
—t list tahle of contents for archiue
-x extract named (or all) files from archiue
—u update existing archiue
-u generate uerbose output on standard output
-f specify archiue file name
-m include manifest information from specified manifest file
-0 store only; use no ZIP compression
—H do not create a manifest file for the entries
-i generate index information for the specified jar files
—C change to the specified directory and include the following file If any file is a directory then it is processed recursiuely. Ihe manifest file name and the archiue file name needs to be specified in the same order the 'mJ and '£' flags are specified.
Example 1: to archiue tuo class files into an archiue called classes.jar:
jar cuf classes.jar Foo.class Bar.class Example 2: use an existing manifest file 'mymanifesť and archiue all the files in the foo/ directory into 'classes.jar':
jar cufm c lasses.jar myman ifest —G foo/ .
C:Stomu\Dbl62 Vi aua>
^iü\24
jar - příklad
Vezměme následující zdrojový text třídy JarDemo v balíku tomp.ucebnicejar, tj. v adresáři
c:\tomp\pbl62\j ava\tomp\ucebnice\j ar:
6
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
Obrázek 1.2. Třída JarDemo
SortedMapComparatorDemo.java | Listi teratorDemo | SortedSetDennoOK.java JarD
package tomp.učebnice.jar;
public class JarDemo {
public static uoid main(String[] args) {
System.out.printlnC'Spustena trida JarDemo*");
>l
Vytvoříme archív se všemi soubory z podadresáře tomp/ucebnice/j ar (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
H Command Shell
C:\tomp\pbl62\jaua>jar cfu jardemo.jar tomp/ucebnice/jar/*.*
added manifest
adding: tomp/ucebnice/jar/JarDemo.c lass(deflated 31x5
adding: tomp/ucebnice/jar/JarDemo.jaua
C:Stomp\pbi62\jaua>_
-ln|x|
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
7
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
El PowerArchiver 2000 - jaľdemo.jar
Soubor Editace Zobrazit Akce Nástroje Nastavení Nápověda
^inLxj
Q
Nový Otevřít Oblíbené
Přidat Rozbalit Smazat Zobrazit
^ M. -Q &
Prozkoušet
Název
Změněno
Velikost Poměr
@ MANIFEST.MF |aa| JarDemo.class |at| JarDemo.java |ail J arP emo. iava. bak
4.11.200310:33 4.11.200310:35 3.11.200314:57 3.11.200314:56
^
J
Nevybrán žádný soubory).
73
443
164
0
00% 32% 21% 00%
l]
Celkem 4 soubory, 1 kB [0 kB]
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
J Command Shell
C:\temp>jar xfu /tonp/pbl62/java/jardeno . jar *.*
C:Stenp>.
- n x
Rozšíření . jar archívů
Formáty vycházející z JAR:
• pro webové aplikace - . war
• pro enterprise (EJB) aplikace - . ear
liší se podrobnějším předepsáním adresářové struktury a dalšími povinnými metainformacemi
Tvorba spustitelných archívů
Vytvoříme jars manifestem obsahujícím tento řádek:
Main-Class: NázevSpouštěnéTřidy
poté zadáme:
Java -jar NázevBaliku.jar
a spustí se metoda main třídy NázevSpouštěnéTřidy.
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
Vytvoření spustitelného archívu - příklad
Nejprve vytvoříme soubor manifestu. Příklad jeho obsahu:
Obrázek 1.6. Soubor manifestu
jardemo-manifest.txt
Main-Class: tomp.učebnice.jar.JarDemo
Následně zabalíme archív s manifestem:
Obrázek 1.7. Zabalení archívu s manifestem
Command Shell
-iDlxl
C:StompSpbl62Sjaua>jar cfum jardeno.jar jardeno-nanifest.txt tomp/ucebnice/jar/^ . *
added manifest
adding: tomp/ucebnice/jar/JarDemo.class í in = 449) (out= 306)(deflated 31n) adding: tomp/ucebnice/jar/JarDemo.jaua(in = 164) í)
C:St o mpSpbl6 2 Sj au a >_
Spuštění archívu - příklad
Spuštění aplikace zabalené ve spustitelném archívuje snadné: Java -jar jardemo.jar
a spustí se metoda main třídy tomp . učebnice .jar. JarDemo:
Obrázek 1.8. Spuštění aplikace z arhcivu
EÜ Command Shell
added manifest
adding: tomp/ucebnice/jar/JarDemo.class(in = 449) (out= 306)(deflated 3ix) adding: tomp/ucebnice/jar/JarDemo.jaua(in = 164) jaua —jar jardemo.jar Spustená trida JarDemoí
C:Stomu\Dbl62 Vi aua>
^jnj_xj
Další příklad spuštění jar
9
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
• jar tfv svet.jar | more
• vypíše po obrazovkách obsah (listing) archívu s vet. j ar
Vstupy a výstupy v Jávě
• Koncepce I/O proudů v Jávě, skládání (obalování vlastnostmi)
• Práce se soubory a adresáři, třída File
• Binární proudy, třídy InputStream, OutputStream
• Znakové proudy, třídy Reader, Writer Serializace objektů
Koncepce vstupně/výstupních operací v Jávě
založeny na v/v proudech plně platformově nezávislé
V/V proudy jsou
• znakové (Reader/Writer) nebo binární (Stream)
koncipovány jako "stavebnice" - lze vkládat do sebe a tím přidávat vlastnosti, např.
is = new InputStream(...);
bis = new BufferedlnputStream(is) ;
Téměř vše ze vstupních/výstupních tříd a rozhraní jev balíku j ava. io.
počínaje J2SDK1.4 se rozvíjí alternativní balík - j ava. ni o (New I/O)
Blíže viz dokumentace API balíků java.io
[http ://j ava. sun.com/j2se/l .4.2/docs/api/j ava/io/package-summary. html], j ava.nio
[http ://j ava. sun.eom/j2se/l .4.2/docs/api/j ava/nio/package-summary. html].
Práce se soubory
vše je opět v balíku j ava. i o
10
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
základem je třída j ava. 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 (WpočítačAadresář...)
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):
• File.separatorChar \ -jako char
• File . separator \ -jako String
• File.pathSeparatorChar ; -jako char
• File.pathSeparator ; -jako String
System. getProperty ( "user .dir") - adresář uživatele, pod jehož UID je proces JVM spuštěn
Třída File
Vytvoření konstruktorem - máme několik možností:
new File(Stňng fi léna- vytvoří v aktuálním adresáři soubor s názvem filename
me)
new File(File baseDir, vytvoří v adresáři baseDir soubor s názvem filename
string filename)
new File(String base- vytvoří v adresáři se jménem baseDirName soubor s názvem filename
DirName, Stúngfilena-
new File(URL url) vytvoří soubor se (souborovým - file:) URL url
Testy existence a povahy souboru:
boolean test na existenci souboru (nebo adresáře)
existsO
boolean is- test, zda jde o soubor (tj. ne adresář)
File()
11
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
() test, zda jde o adresář
Test práv ke čtení/zápisu:
boolean ca- test, zda lze soubor číst
nReadO
boolean ca- test, zda lze do souboru zapisovat
nWriteO
Třída File (2)
Vytvoření souboru nebo adresáře:
boolean (pro soubor) vrací true, když se podaří soubor vytvořit
create-
^fg^qij^Q (pro adresář) vrací true, když se podaří adresář vytvořit
mkdir()
boolean navíc si dotvoří i příp. neexistující adresáře na cestě
mkdirsO
Vytvoření dočasného (temporary) souboru:
static File create- vytvoří dočasný soubor ve standardním pro to určeném adresáři (např. c: \temp) s
TempFile(String uvedeným prefixem a sufixem názvu
prefix, String sufi-
atatic File create- dtto, ale vytvoří dočasný soubor v adr. directory
TempFile(String
prefix, String suf-
Zruseni:
fix, File
directory)
boolean de- zrušení souboru nebo adresáře
lete()
Přejmenování (ne přesun mezi adresáři!):
boolean re- přejmenuje soubor nebo adresář
(Fi
nameTole
Třída Eále (3)
Další vlastnosti:
long len- délka (velikost) souboru v bajtech gth()
12
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
() čas poslední modifikace v ms od začátku éry - podobně jako systémový čas vracený Sys-
tem.currentTimeMillis().
String jen jméno souboru (tj. poslední část cesty)
(
SjWSme) celá cesta k souboru i se jménem
getPathO
String ge- absolutní cesta k souboru i se jménem
tAbsolu-tePathO
13
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
() adresář, v němž je soubor nebo adresář obsažen
Blíže viz dokumentace API třídy File [http://java.sun.eom/j2se/l.4.2/docs/api/java/io/File.html].
Práce s adresáři
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 f f) nebo podobné
File[] lisťFiles(FilenameFilterfnf):
FileFilter je rozhraní s jedinou metodou boolean accept(File pathname), obdobně FilenameFilter, viz Popis API j avaio.FilenameFilter [http://java.sun.eom/j2se/l.4/docs/api/java/io/FilenameFilter.html]
Práce s binárními proudy
Vstupní jsou odvozeny od abstraktní třídy InputStream Výstupní jsou odvozeny od abstraktní třídy OutputStream
Vstupní binární proudy
Uvedené metody, kromě abstract byte read(), nemusejí být nutně v neabstraktní podtřídě překryty.
void closeO uzavře proud a uvolní příslušné zdroje (systémové "file handles" apod.)
void mark(int poznačí si aktuální pozici (později se lze vrátit zpět pomocí reset())...
readlimiť)
boolean markSup- ...ale jen když platí tohle
portedO
abstract int read() přečte bajt (0-255 pokud OK; jinak -1, když už není možné přečíst)
int read(byte[] b) přečte pole bajtů
int read(byte[] b, přečte pole bajtů se specifikací délky a pozice plnění pole b
int off, int len)
void reset() vrátí se ke značce nastavené metodou mark(int)
long skip(long n) přeskočí zadaný počte bajtů
Důležité neabstraktní třídy odvozené od input stream
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 j ava. i o!):
14
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
BufferedlnputStream
j ava.util. zip. CheckedlnputStream j avax. crypto. CipherlnputStream DatalnputStream
java.security.DigestInputStream
j ava.util. zip. InflaterlnputStream
LineNumberlnputStream
ProgressMonitorlnputStream PushbacklnputStream
proud s vyrovnávací pamětí (je možno specifikovat její optimální velikost)
proud s kontrolním součtem (např. CRC32)
proud deäfrující data ze vstupu
má metody pro čtení hodnot primitivních typů, např. float readFloat()
počítá současně i haš (digest) čtených dat, použitý algoritmus lze nastavit
dekomprimuje (např. GZIPem) zabalený vstupní proud (má ještě specializované podťřídy)
doplňuje informaci o tom, ze kterého řádku vstupu čteme (zavrhovaná - deprecated - třída)
přidává schopnost informovat o průběhu čtení z proudu
do proudu lze data vracet zpět
Další vstupní proudy
Příklad rekonstrukce objektů ze souborů
FilelnputStream istream = new FilelnputStream("t.tmp");
ObjectlnputStream p = new ObjectlnputStream(istream);
int i = p.readlntO;
String today = (String)p.readObject();
Date date = (Date)p.readObject();
istream.close();
ja- vstupní proud zvukových dat
vax. sound, sampled. AudioInputStre
gftteArraylnputStream proud dat čtených z pole bajtů
PipedlnputStream SequencelnputStream
ObjectlnputStream
roura napojená na "protilehlý" PipedOutputStream
proud vzniklý spojením více podřízených proudů do jednoho virtuálního
proud na čtení serializovaných objektů
Práce se znakovými proudy
15
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
základem je abstraktní třída Reader, konkrétními implementacemi jsou:
• BufferedReader, CharArrayReader, InputStreamReader, PipedReader, Strin-gReader
• LineNumberReader, FileReader, PushbackReader
Výstupní proudy
nebudeme důkladně probírat všechny typy principy:
• jedná se o protějšky k vstupním proudům, názvy jsou konstruovány analogicky (např. FileReader -> FileWriter)
místo generických metod read mají write (...)
Příklady:
PrintStream poskytuje metody pro pohodlný zápis hodnot primitivních typů a řetězců - příkladem
jsou System, out a System, err
Print Writer poskytuje metody pro pohodlný zápis hodnot primitivních typů a řetězců
Konverze: znakové <-> binární proudy
Ze vstupního binárního proudu InputStream (čili každého) je možné vytvořit znakový Reader pomocí
// nejprve binárni vstupni proud - toho kódováni znaků nezajimá InputStream is = ...
// znakový proud isr
// použije pro dekódováni 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áni jinou znakovou sadu
Reader isr2 = new InputStreamReader(is, chrs);
Podporované názvy znakových sad naleznete na webu IANA Charsets
16
Přednáška 11 - Použití javadoc ajar. Vstupy a výstupy
[http ://www. iana. org/assignments/character-sets].
Obdobně pro výstupní proudy - lze vytvořit Writer z OutputStream.
Serializace objektů
• nebudeme podrobně studovat, zatím stačí vědět, že:
• serializace objektů je postup, jak z objektu vytvořit sekvenci bajtů persistentně uložitelnou na paměťové médium (disk) a později restaurovatelnou do podoby výchozího javového objektu.
• deserializace je právě zpětná rekonstrukce objektu
• aby objekt bylo možno serializovat, musí implementovat (prázdné) rozhraní Java.io.Se rializ able
• proměnné objektu, které nemají být serializovány, musí být označeny modifikátorem - klíčovým slovem - transient
• pokud požaduje "speciální chování" při de/serializaci, musí objekt definovat metody
• private void readObject(java.io.ObjectlnputStream stream) throws IOException, ClassNotFoundException
• private void writeObject(java.io.ObjectOutputStream stream) throws IOException
• metody:
• DataOutputStream.writeObject(Object o)
Odkazy
Tutoriály k Java I/O: kapitola z Sun Java Tutorial [http://java.sun.com/docs/books/tutorial/essential/io/]
Demo programy na serializaci (z učebnice): Serializace objektů
[http://www.fi.muni.cz/~tomp/java/ucebnice/javasrc/tomp/ucebnice/serializace/]
17