Evropský sociální fond Praha & EU: Investujeme do vaší budoucnosti Programování v jazyku Java Dokumentace, logování, regex BI-PJV Programování v jazyku Java Katedra teoretické informatiky Miroslav Balík Fakulta informačních technologií České vysoké učení technické
dokumentace BI-PJV13 2
BI-PJV13 3 Dokumentace Tvorba dokumentace byla vždy útrpnou záležitostí neboť: 1.programátoři ji krajně neradi dělají - a pokud - tak až nakonec, 2.nebyla vůbec žádná vodítka jak ji dělat, 3.a tedy pokud byla tak velmi rozmanitá, 4.vytvářená různými technikami, 5.odděleně od popisovaných programů, 6.a na různých nosičích, 7.často neaktuální, obtížně modifikovatelná, 8.těžko dosažitelná nebo dokonce ztracená. Velmi významným přínosem Javy k metodice programování je také originální způsob podpory dokumentace softwarového díla programem javadoc. Tím se dokumentační utrpení velmi zmírňuje, neboť vnitřní (technická) dokumentace je součástí zdrojových souborů, je celosvětově stylově jednotná ve tvaru důmyslně provázaných HTML stránek.
javadoc BI-PJV13 4 Součástí j2sdk je také dokumentační program javadoc a jeho popis: j2sdk1.*.*/bin/javadoc j2sdk1.*.*/docs/tooldocs/solaris/javadoc.html j2sdk1.*.*/docs/tooldocs/windows/javadoc.html Pro úplné informace o projektu javadoc: http://www.java.sun.com/j2se/javadoc/
javadoc BI-PJV13 5 Vstupem do programu javadoc jsou zdrojové soubory, výstupem je adresář obsahující tzv. doclety ve tvaru.html. Programátor píše do zdrojových souborů tzv. dokumentační komentáře ( začínají lomítkem a dvěma hvězdičkami ) a to před popisované části, tj. třídu, interfejs, atribut, metodu a konstruktor. Zavináč vyznačuje tzv. tag pro strukturaci význačných složek. Příklad popisu metody: /** Tato metoda počítá cosi * a nějak. * bla bla bla... * @param i int * @throws NullPointerException * @return int */ Pokročilá IDE (např. JBuilder ) usnadňují psaní těchto komentářů.
javadoc Javadoc je velmi složitý program ( ve verzi j2sdk1.4 má 56 opcí ). Následuje několik jednoduchých možností k vytvoření dokumentace celých balíčků v rámci projektu vytvářeného v JBuilderu. BI-PJV13 6 Pro spouštění z řádky: javadoc.exe -breakiterator // doporučeno -d projekt\doc // výstupní adresář [ -overview povidani.html ] // do přehledu [ -public -protected -private ] // hloubka výběru -sourcepath projekt\src // cesta ke zdrojům [ balik1 balik2... ] // jednotlivé balíčky [ -subpackages // probírat strom balik3 balik4... ] // kořenové balíčky Soubor povidani.htm umožňuje dodat vlastní komentáře, obrázky či dokonce i interaktivní aplety.
Podpora v Netbeans BI-PJV13 7 Vytvoření dokumentace balíčku je velmi jednoduché: Build->Generate Javadoc Dokumentace se vytvoří v distribučním adresáři dist
Java ARchive BI-PJV13 8
BI-PJV13 9 JAR - Java ARchive J2SE/bin obsahuje program jar, který je mírným rozšířením PKZIPu. Z důvodů bezpečnosti, kapacity a rychlosti je preferovaný. Se soubory *.jar lze nakládat i WinZipem (od ver. 7.0) či WinRARem. Do archivu lze přiložit i adresář meta-inf a soubor meta-inf/manifest.mf, v němž se ukládají dodatečné informace ve formě dvojic klíč:hodnota. Tak lze např. určit spouštěcí třídu, certifikáty jednotlivých složek apod. Klíč má být unikátní, oddělený od hodnoty dvojtečkou a jednou mezerou. Soubor musí musí končit novou řádkou.
Příklad použití Vytvoření: jar cf MyJar.jar myapp BI-PJV13 10 Výpis: jar -xvf MyJar.jar Spuštění: java jar MyJar.jar Aplikaci se spustit, pokud jar obsahuje manifest, v němž je vyznačena spustitelná třída ( např. Main-Class: p1.a ), tj. obsahující main
BI-PJV13 11 Vytvoření JAR a dokumentace v NetBeans je snadné po té když jsou třídy projektu zkompilovány. Projects -> identifikace projektu X -> Build v adresáři projektu dist se vytvoří X.jar Projects -> identifikace projektu X -> Generate Javadoc v adresáři projektu dist se vytvoří adresář javadoc s dokumentací
Vytvoření JAR ručně Příklad vytvoření archivu s manifestem: jar -cvfm Muj.jar xxx.mft file1 [-C dir2 file2] [-C dir3 file3]... kde: Muj.jar je výstupní soubor xxx.mft je soubor manifestu (může se jmenovat jakkoli - včetně extenze) -C znamená změnu adresáře. Následuje jeden soubor anebo tečka znamenající vše z adresáře. Vstupní file mohou obsahovat hvězdičkovou notaci. Bude-li xxx.mft obsahovat: Main-Class: p1.a Ahoj-Nazdar: Cau Pak soubor meta-inf/manifest.mf bude obsahovat: Manifest-Version: 1.0 Main-Class: p1.a Ahoj-Nazdar: Cau Created-By: 1.2 (Sun Microsystems Inc.) BI-PJV13 12
Manifest Soubor meta-inf/manifest.mf např. obsahuje: BI-PJV13 13 Manifest-Version: 1.0 Created-By: 1.4.2_04 (Sun Microsystems Inc.) Main-Class: p1.mainclass Class-Path: Signature-Version: Extension-List: Extension-Name: javax.help Specification-Vendor: Sun Microsystems, Inc Specification-Version: 1.0 Implementation-Vendor-Id: com.sun Implementation-Vendor: Sun Microsystems, Inc Implementation-Version: 1.0
java.util.jar BI-PJV13 14 java.util.zip ZipFile JarFile java.io GZIP InputStream ZipEntry JarEntry Input Filter Inflater Zip Jar Stream InputStream InputStream InputStream InputStream Output Stream Filter OutputStream Deflater OutputStream Zip OutputStream Jar OutputStream GZIP OutputStream Map Manifest Attributes Pack200 Attributes. Name
Logging BI-PJV13 15
BI-PJV13 16 Logging Balíček java.util.logging podporuje tvorbu strukturovaných výpisů pro různé zájemce v různých formátech (text, XML) a jejich zasílání do paměti, proudů, konzole, souborů či socketů. Zpráva je objekt typu LogRecord, který přijímají objekty typu Logger. Ty bývají pojmenované v hierarchickém jmenném prostoru, ale mohou být i anonymní. U loggerů se registrují handlery různých podtypů. Defaultně všechny loggery posílají své výstupy k rodičovskému loggeru, ale mohou být konfigurovány tak, aby ignorovaly handlery výše ve stromu. Některé handlery mohou zasílat svůj výstup jiným handlerům. Zprávy vyznačují svůj význam a prioritu pomocí Level ( FINEST.. SEVERE ). http://java.sun.com/javase/6/docs/technotes/guides
Tok zpráv BI-PJV13 17 Aplikace Log Logger Memory File Record Handler Handler Filter Filter Formatter Filter Formatter Memory Handler Console Handler MyOwn Handler Filter Formatter Filter Formatter Filter Formatter Socket Handler Filter Formatter
LogManager BI-PJV13 18 LogManager je singleton registrující pojmenované loggery. LogManager RootLogger global deprecated -> GLOBAL_LOGGER_NAME... má defaultní ConsoleHandler a a.b a.b.c x
Balíček java.util.logging BI-PJV13 19 Logger LogRecord Formatter Handler Log Manager Level Simple Formatter Memory Handler Error Manager XML Formatter Stream Handler Console Handler Logging Permission Filter LoggingMXBean File Handler Socket Handler
Konkrétní třída LogRecord BI-PJV13 20 Slouží k vytváření zpráv. Konstruktor: public LogRecord( Level level, String msg ) getry a setry: Level LoggerName Message Millis Parameters ResourceBundle ResourceBundleName SequenceNumber SourceClassName SourceMethodName ThreadID Thrown
Konkrétní třída Level vyjadřuje závažnost zprávy. Konstruktory: public Level( String name, int value ) public Level( String name, int value, String resourcebundlename ) static Level parse( String name ) Getry: LocalizedName Name ResourceBundleName BI-PJV13 21 Predefinované finální hodnoty: OFF ~ MAX_VALUE, SEVERE ~ 1000, WARNING ~ 900, INFO ~ 800 pro speciální výpisy: CONFIG ~ 700, FINE ~ 500, FINER ~ 400, FINEST ~ 300, ALL ~ MIN_VALUE
BI-PJV13 22 Konstruktor: Logger protected Logger(String name, String resourcebundlename) void addhandler ( Handler h ) void removehandler ( Handler h ) void entering( String class, String method, Object params ) void exiting ( String class, String method, Object result ) boolean isloggable( ) void log(... ) void logp(... ) void logrb(... ) void throwing(... ) void config, fine, finer, finest, info, severe, warning getry: AnonymousLogger, Filter, Handlers, Level, Logger, Name, Parrent, ResourceBundle, ResourceBundleName, UseParrentHandlers setry: Filter, Level, Parrent, UseParrentHandle
BI-PJV13 23 Abstraktní třída Handler Konstruktor: protected Handler( ) abstract void close ( ) abstract void flush ( ) abstract void publish ( LogRecord r ) boolean isloggable( ) protected void reporterror( String msg, Exception ex, int code ) getry a setry: Encoding ErrorManager Filter Formatter Level
Vytváří kruhovou frontu zpráv. MemoryHandler Konstruktory (využívají též informace z konfiguračního souboru): : public MemoryHandler( ) public MemoryHandler( Handler target, int size, Level pushlevel ) přidává metody: public void push( ) vypudí celý obsah fronty do dalšího handleru a vyčistí frontu. public void publish( LogRecord r ) vloží referenci zprávy do fronty. Pokud její level je stejný nebo vyšší než pushlevel zavolá metodu push. public void flush( ) volá flush dalšího handleru. Vlastní frontu nemění. getry a setry: PushLevel definuje úroveň pro vypuzení fronty do dalšího handleru. BI-PJV13 24
BI-PJV13 25 StreamHandler Konstruktory: public StreamHandler( ) public StreamHandler( OutputStream os, Formatter f ) Setr: OutputStream Podtřídy ConsoleHandler, FileHandler a SocketHandler mají konstruktory: public ConsoleHandler( ) public SocketHandler( ) public SocketHandler( String host, int port ) public FileHandler( String pattern, int limit, int count, boolean append ) FileHandler umožňuje cyklický zápis generických souborů 0, 1,... count-1 nepřesahující limit daný v bajtech.
Příklad BI-PJV13 26 Logger logger; Handler h1 = null, h2 = null; try { logger =Logger.getLogger( "A" ); h1 = new ConsoleHandler( ); h2 = new FileHandler( "logged.txt" ); logger.addhandler( h1 ); logger.addhandler( h2 ); for ( int i = 0; i < 10; i++ ) { String s = " MESSAGE # " +i ); LogRecord r = new LogRecord( Level.SEVERE, s ); logger.log( r ); } } catch ( Exception ex ) { System.out.println( ex ); } finally { h1.close( ); h2.close( ); }
regex BI-PJV13 27
java.util.regex BI-PJV13 28 Regulární výrazy jsou standardním prostředkem pro definici regulárních jazyků, konečných automatů a některých textových vyhledávacích strojů. Podrobnosti viz: http://java.sun.com/docs/books/tutorial/essential/regex/
BI-PJV13 29 Třída Matcher Objekt typu Matcher je vyhledávací stroj. Jeho konstruktory jsou mimo balíček java.util.regex nepoužitelné. Matcher se získá metodu z třídy Pattern. Metody: boolean find( ) boolean lookingat( ) boolean matches( )
BI-PJV13 30 Pattern abc příklad přímého řetězu - vyhledání bez překrývání [0-4a-mA-M] číslice či písmeno z první poloviny [^1-3] kterýkoli znak kromě 1, 2 a 3. - kterýkoli znak \. - skutečná tečka \d - číslice [0-9], \D non- tj. [^0-9] \s - whitespace, tj. mezera, tabulátor a konec řádky, \S non- tj. [^\s] \w - znak slova, tj. [0-9a-zA-Z], \W non- [^\w] + >= 1, * >= 0,? <= 1, ^ - negace, && - průnik Příklady: ( [ ^,/ ] )+ - jakýkoli znak krom, a /. Vrátí skupinu bez těchto separátorů ( [ ^,/ ] )* - totéž avšak navíc vrací prázdný řetěz místo oněch separátorů.+ či.* -
BI-PJV13 31 Kvalifikátory greedy hladový, reluctant zdráhavý, possessive - panovačný pro greedy reluctant possessive <=1????+ >=0 * *? *+ >=1 + +? ++ =n {n} {n}? {n}+ >=n {n,} {n,}? {n,}+ n<= i <=m {n,m} {n,m}? {n,m}+. *?ab - skupiny se sufixem ab
Příklad pro vstup: ababaaaab BI-PJV13 32 regex a? a* a+ pozice 0-1 0-1 0-1 1-1 1-1 2-3 2-3 2-3 4-8 3-3 3-3 4-5 4-8 5-6 8-8 6-7 9-9 7-8 8-8 9-9
BI-PJV13 33 java.lang.regex Runtime Exception MatchResult IllegalArgument Exception Matcher Pattern PatternSyntax Exception
BI-PJV13 34 Příklad lexikální analýzy String patt = " ( [ 0-9 ] + ) " +" "+ // NUMBER " ( [ \" ] [. [ ^\" ] ]*[ \" ] ) " +" "+ // QUOTE " ( [ ( ] ) " +" "+ // BRAC " ( [ ) ] ) " +" "+ // KET " ( \\p{punct} ) " +" "+ // OTHER " ( [ a-za-z ][ a-za-z0-9 ]* ) " +" "+ // ID " ( [ ]* ) " ; // BLANK Pattern p = Pattern.compile( patt ); Matcher m = p.matcher( " searched text " ); while( m.find( ) ) { } String g = m.group( );