725G61 - Laboration 7 Implementation av ett API. Johan Falkenjack

Transkript

1 725G61 - Laboration 7 Implementation av ett API Johan Falkenjack December 13, 2013

2 1 Inledning Hittills i kursen har vi tittat på grundläggande programmering och grundläggande objektorientering. I den här labben kommer ni använda det ni lärt er hittills samtidigt som ni lär er tolka ett API och att dokumentera er kod. 2 Vad är ett API API står för Application Programming Interface och beskriver hur en viss resurs kan användas. Man kan prata om många olika typer av API:er, som t.ex. generella API:er för att kommunicera med skrivare, eller specifika API:er för att kommunicera med en specifik klass. Ett API beskriver hur man utifrån kan kommunicera med en viss resurs. För skrivarexemplet kan det handla om en lista med kommandon som skrivaren kan ta emot, ungefär som metoder. T.ex. kan det finnas en metod för att skriva ut ett dokument representerat som t.ex. PostScript (ett dokumentbeskrivningsspråk som många skrivare förstår). En annan metod kanske returnerar hur mycket bläck som finns kvar, eller kontrollerar huruvida det finns papper att skriva ut på. Ni kan även tänka på Javas standardbibliotek som en samling API:er. Där har ni beskrivningar av hur en mängd klasser kan användas, och ni kan använda dessa baserat på beskrivningen utan att behöva bry er om exakt hur alla klasser och metoder är implementerade under ytan. I den här labben kommer ni få en beskrivning av ett API, som beskriver ett paket med en klass. Er uppgift är att implementera klassen. När det är gjort ska ni också skriva JavaDoc-kommentarer för att kunna generera samma dokumentation, utifrån er kod, som den ni fått given i uppgiften. 3 Att koda utifrån ett API I den här labben ska ni implementera en liten Counter-klass, dvs en klass som kan räknas upp och räknas ner och till exempel användas när man ska räkna hur många gånger en klass instansierats. Mer konkreta tillämpningar kan vara för att mäta antalet liv eller poäng i ett spel eller för att räkna antalet personer i en lokal genom att räkna in- och utpasseringar. Klassen ska också hålla reda på högsta och lägsta värdena som den antagit, t.ex. för att man ska veta maximala antalet personer som varit i en lokal samtidigt under en given dag. För att skapa klassen skall ni utgå från API-dokumentationen som finns på hemsidan. I en API-dokumentation kan man inte se något om hur en klass är implementerad internt. Därför kommer här en liten ledning som förhoppningsvis ska hjälpa er med implementationen: Klassen kommer behöva sex privata variabler. Tre heltalsvariabler, en för att hålla det faktiska värdet, en för att hålla max-värdet, en för min-värdet, och tre sanningsvariabler för att hålla reda på vad man får göra med klassen. Titta 1

3 speciellt på konstruktorerna för en ledning till hur dessa ska fungera och använd metodnamnen som en ledning till vad variablerna bör heta. Det är viktigt att veta för den här labben att begreppet "räkna upp" i programmeringstermer kallas att inkrementera (kom ihåg postinkrementationsoperatorn, ++) och att räkna ner kallas att dekrementera. 3.1 Hur läser man ett API? Ni har tidigare under kursen fått referenser till Javas dokumentation som i all väsentlig mening beskriver API:erna för alla inbyggda klasser. Det API ni får i den här labben är av samma typ som de som ligger på Oracles officiella JavaDoc-sidor, med den skillnaden att klassen inte är inbyggd i Java utan måste konstrueras av er. Här kommer en liten repetition av hur man läser dokumentationen Förstasidan När ni först går in och tittar på API:t så kommer ni se en sammanfattning av paketet edu.liu.ida.svp725g61.lab7 och en lista över vilka paket, klasser, interface osv. som paketet innehåller. I det här fallet innehåller paketet bara en enda klass Counter. Det finns också en meny i toppen och botten av sidan med alternativen Package, Class, Use, Tree, Deprecated, Index och Help. Klicka gärna på dessa för att se vad som visas. Sidan Use visar var paketet, eller klassen, man tittar på används. Detta är inte aktuellt i vårt API då vi bara har en enda klass som inte används i någon annanstans i API:t. Ofta har man dock i ett API med flera klasser där vissa klasser används av andra, t.ex. som Course användes av Student i Labb 6. Deprecated visar delar av paketet som är deprecated, dvs som är på väg att fasas ut och inte bör användas. När man ändrar någonting i implementationen av ett API, t.ex. byter namn på en metod, så behåller man normalt sett även den gamla metoden under en övergångsperiod men markerar den som deprecated. Detta varnar användare av API:t att ändra sin kod så att API:t används på det nya sättet innan den gamla metoden tas bort helt. Detta är inte heller aktuellt i vårt API eftersom det är helt nytt. Sidan Help visar en informationstext över hur dokumentationen är uppbyggd, denna kan ni läsa om ni har tid över och vill veta mer om hur JavaDocsidorna är uppbyggda. 3.2 Klassbeskrivningen När ni klickar på klassen Counter i listan Class Summary på förstasidan så kommer ni till en sida som beskriver klassen. Längst upp står klassens namn och en arvshierarki som visar vilka klasser vår klass ärver av. Ofta står det också ett datum när klassen senast uppdaterades och namnet på den eller de som skrivit implementationen. 2

4 Efter det kommer ett avsnitt som heter Field Summary. Namnet kommer av att publika variabler ofta kallas för fields, eller fält. För varje publik variabel står namnet och dess typ samt i vissa fall en beskrivning av vad variabeln används till. Efter Field Summary följer Constructor Summary och Method Summary. Här listas alla publika konstruktorer respektive alla publika metoder. Konstruktorer listas inte med returvärde, eftersom konstruktorer per definition returnerar ett objekt av klassen i fråga. För varje metod står dock returvärdet i vänsterkolumnen. I högerkolumnen står konstruktorns/metodens signatur samt en kort beskrivning. Efter Summary-avsnitten följer motsvarande Details-avsnitt. Här kan man läsa mer detaljer om fält, konstruktorer och metoder. T.ex. kan man läsa vilka argument en metod tar, om några. Man kan också läsa om vilka undantag som eventuellt kastas, vad returvärdet representerar osv. Här finns också ofta en mer utförlig beskrivning av metoden. Tittar man noga ser man att beskrivningen som fanns i Summary-avsnittet består av första meningen i den beskrivning som finns i Details-avsnittet. UPPGIFT 7.1 Implementera klassen enligt dokumentationen i API:t på kurshemsidan. Skapa sedan även en test-klass i ett separat paket, som endast innehåller en mainmetod och som använder er Counter-klass. Test-klassen använder ni för att kunna testa att er klass beter sig så som API-dokumentationen säger, d v s försök att se till att er main-metod använder och testar alla publika variabler, konstruktorer, och metoder som Counter erbjuder, med lämpliga värden som ni själva hittar på. (Jämför med hur ni använde klassen Test i Labb 5, där ni fick en färdig test-klass för att testa att er MySet-klass fungerade korrekt - här ska ni alltså skapa en motsvarande test-klass på egen hand, för att testa er Counter-klass.) 4 Att skapa en API-dokumentation Nu när ni skapat klassen Counter ska ni skapa en API-dokumentation med hjälp av JavaDoc. Den dokumentation ni använde i förra uppgiften är genererad med hjälp av en speciell typ av kommentarer som heter JavaDoc-kommentarer. Dessa kommentarer skrivs på ett speciellt sätt i koden och tillsammans med koden kan man med dessa generera JavaDoc-filer genom att använda JavaDoc-programmet. JavaDoc-kommentarer skrivs alltid precis innan det som dokumenteras. T.ex. skriver man en kommentar innan klassdefinitionen, en annan innan varje publik variabel, en innan varje konstruktor/metod. I Eclipse kan man automatiskt generera kommentarer genom att ställa markören i t.ex. den metod man vill dokumentera och trycka Alt-Shift-J. 3

5 Här kommer nu ett exempel på en dokumentation för en klass: 1 /** 2 * A small class designed to work as a back-end for a simple stopwatch. 3 * Created with IntelliJ IDEA. 4 Johan Falkenjack */ 8 public class Timer { 9 10 //Class body } Först i dokumentationen står en beskrivning av klassen. Den första meningen här används i olika Summary-listor i de genererade JavaDoc-sidorna. Samtliga meningar syns i Details-listor. (I det här fallet står det "Created with IntelliJ IDEA." Den meningen är en del av beskrivningen men är faktiskt också automatgenererad och kommer av att klassen Timer skrevs i en annan utvecklingsmiljö än Eclipse. IntelliJ IDEA är ett alternativ till Eclipse som dock kostar pengar om man inte kan nöja sig med en nedbantad version. När man genererar JavaDoc-kommentarer i IntelliJ läggs det automatiskt till lite reklam.) Notera att klassnamnet inte står någonstans i kommentaren. En av fördelarna med JavaDoc är att kommentarerna samarbetar med koden och JavaDocgeneratorn analyserar den faktiska Java-koden för att hämta viss information därifrån, t.ex. klassnamn, metodnamn osv. Efter beskrivningen kommer ett med olika specialuppgifter. Dessa är standardiserade och används för olika saker. Oftast, som i fallet ovan, är de ganska självförklarande. Ni fick en genomgång av hur Javadoc-kommentarer skrivs på föreläsning 9, gå gärna tillbaka och titta på föreläsningsbilderna igen. En ganska bra sammanfattning av hur JavaDoc fungerar finns även på wikipedia ( Där finns också illustrativa exempel för hur man dokumenterar exempelvis metoder. 4.1 Att generera JavaDoc För att generera dokumentation från er fil med hjälp av JavaDoc i Eclipse gör man på följande sätt: Under menyn Project finns alternativet Generate Javadoc. Det är okej att använda standardinställningarna och klicka Finish direkt. Ibland är dock fältet Javadoc command tomt. Det innebär att Eclipse inte konfigurerats för JavaDoc. Då får man manuellt lägga till filen för JavaDoc. Den ligger sannolikt på sökvägen C:\Program Files\Java\jdk1.6.0_35\bin\javadoc.exe eller motsvarande på IDAs maskiner. Fråga er labbassistent om ni får problem med detta. 4

6 När man genererar JavaDoc skapas en ny katalog i projektet. Tidigare har vi haft src och bin, nu kommer vi också få doc. Katalogen doc innehåller de html-filer som utgör projektets dokumentation. UPPGIFT 7.2 Skriv JavaDoc-kommentarer för klassen Counter som exakt motsvarar de i det givna API:t med undantag av att ni kan ändra eventuella datum och författare. Generera sedan JavaDoc utifrån er fil. Jag rekommenderar att göra detta genom stegvis förfining. Skriv först korta kommentarer och se att ni får genereringen att fungera. Fixa sedan till kommentarerna så att rätt saker står i de genererade filerna, dvs att era HTML-filer ser likadana ut som de som ni fått givna inför den här labben (med undantag av att ni lagt in era egna namn och nya datum). När ni redovisar ska ni skicka in både den genererade doc-katalogen (packa ner den i en zip-fil) samt kodfilen Counter.java och er test-klass som ni skapade i första uppgiften. 5