Produktdokumentasjon. 29/5 Hovedprosjekt ingeniørutdanningen. Tittel på hovedprosjektet Tarantell Dashboard

Transkript

1 29/5 Hovedprosjekt ingeniørutdanningen 09 Produktdokumentasjon Tittel på hovedprosjektet Tarantell Dashboard Gruppe 28 Bjørn Ove Pedersen Stian Dalviken Antall sider 38 Intern veileder Steinar Johannesen Oppdragsgiver Tarantell AS - Kontaktperson Jarle Haakenstad

2 1 Forord Dette er produktdokumentasjonen til systemet Tarantell Dashboard, som er laget som et hovedprosjekt hos HiO, for Tarantell AS. Systemet er laget av Bjørn Ove Pedersen og Stian Dalviken. Dette dokumentet gir et overblikk om hvordan systemet har blitt laget og hvordan det fungerer, og er laget for at en dataansvarlig hos Tarantell AS lettere kan gjøre seg kjent med systemet, slik at det blir enklere å videreutvikle Tarantell Dashboard. Kompetansen den dataansvarlige må ha for å kunne forstå dette systemet og denne produktdokumentasjonen er i all hovedsak god kjennskap til programmeringsspråket Java. Kunnskap om Jetty, Apache Wicket og Spring Framework er også noe man burde ha, selv om dette blir i korte trekk blir beskrevet under punkt 7.1, 7.2 og 7.3 i dette dokumentet. Det blir også referert til disse verktøyenes hjemmesider under kilder (punkt 12). Hele systemet (Javaklasser og øvrige filer) ligger tilgjengelig på prosjektets hjemmeside. 2

3 2 Innholdsfortegnelse 1 Forord Innholdsfortegnelse Hensikten med systemet Kravspesifikasjon og endelig produkt Systemets oppbygning Klasserelasjoner Client Fetcher Parser Backend Kort historisk oppsummering Fetcherne Feed objektet Websider med autentisering Websider uten autentisering E-post Verdiobjektene Tweet BlogPost Parserne Twitter feed Twitter json feed Twitter rss feed Twitter xml feed Blog feed E-post Klientene Generisk klient Twitterklient, bloggklient og e-postklient Frontend Jetty Apache Wicket Spring IoC (Inversion of Control) Javaklassene Index WicketApplication URLImage Øvrige filer HTML CSS web.xml applicationcontext.xml Systemets krav til maskinvare Installasjon av systemet

4 10 Oversikt over filer Backend Backend-tester Frontend Oversikt over Javabibliotek Backend Frontend Kilder Vedlegg Vedlegg

5 3 Hensikten med systemet Tarantell har tidligere brukt tradisjonelle metoder for å nå ut med fellesinformasjon til sine ansatte, for eksempel gjennom e-post og innlegg på deres offisielle blogg. Som et supplement til dette ønsket bedriften seg nå å få utviklet et system som kunne hente inn data fra alle de eksterne kildene, samle de på en plass og presentere dem via skjermer rundt i lokalet. Dette ville gjøre informasjonen lettere tilgjengelig og mer synlig for både ansatte, kunder og andre besøkende. Hensikten med Tarantell Dashboard er å kunne tilby Tarantell en alternativ informasjonskanal for sine ansatte, kunder og andre besøkende. Statusskjermen inneholder statusbeskjeder fra Twitter, blogginnlegg fra Tarantell bloggen og felles e-poster. Systemet er designet på en slik måte at det enkelt kan konfigureres, driftes og videreutvikles. 5

6 4 Kravspesifikasjon og endelig produkt Selve kravspesifikasjonen følger med sluttdokumentasjonen som et eget dokument og er ikke gjengitt i dette avsnittet. 4.1 Rolle og innhold Kravspesifikasjonen har hatt en sentral rolle under hele utviklingen. Vi kjente fra før av til viktigheten av en god kravspesifikasjon og hadde mange møter med oppdragsgiver i oppstartsfasen for å fastsette de nødvendige kravene til funksjon, design og bruk av forskjellige teknologier og verktøy. Vi bestemte oss i samråd med oppdragsgiver om å legge oss på en linje som var konkret, men ikke spesielt detaljorientert og som dermed ga rom for mindre ikke-funksjonelle endringer av løsningen uten at kravspesifikasjonen måtte endres. 4.2 Endringer Når vi satt opp kravspesifikasjonen ønsket vi å ta hensyn til flere tilfeller, også en eventuell situasjon der vi lå foran den planlagte fremdriften. Vi følte at det var en realistisk mulighet for at dette kunne skje. Tanken var at vi ved tid til overs skulle implementere en funksjon der statistikk om de ansatte og deres oppdrag kunne vises på statusskjermen. Gjerne grafisk fremstilt. Disse opplysningene ble sendt per e-post og siden det skulle implementeres en e-post leser ville halve jobben alt være gjort. Det viste seg imidlertid at når vi kom til begynnelsen av mai lå vi i underkant av en uke bak fremdriftsplanen og denne funksjonen måtte kuttes fra kravspesifikasjonen. 4.3 Endelig produkt Vi vurderte hele tiden produktet opp mot den gjeldende kravspesifikasjonen. Siden det tross alt dukket opp ganske få problemer som påvirket kravspesifikasjonen trengte vi bare å gjøre denne ene endringen som er beskrevet i forrige punkt. Vi mener at vi har oppnådd alle de funksjonelle kravene, og forhåpentligvis også de strukturelle, som er beskrevet i kravspesifikasjonen. 6

7 5 Systemets oppbygning Systemet er delt opp i to deler, en backend-del og en frontend-del. Disse delene blir beskrevet i punkt 6 og 7. Kort oppsummert innhenter backend-delen all informasjon fra de allerede eksisterende kildene, og frontend-delen henter denne informasjonen fra backend, og viser dette på websiden. Allerede eksisterende kilder Backend Frontend Felles informasjonskanal (webside) Fig. 1: Visuell beskrivelse av hvordan Tarantell Dashboard fungerer 7

8 5.1 Klasserelasjoner For å gi en bedre og en mer oversiktlig forståelse av oppbygningen av backend, har vi lagt ved noen bilder av klasserelasjonene. De fullstendige klassene med oversikt over variabler, objekter og metoder er lagt i punkt 13.1 Vedlegg 1. Backend-delen blir beskrevet nærmere i punkt Client Fig. 2: Visuell beskrivelse av klasserelasjonene til klientene Fetcher Fig. 3: Visuell beskrivelse av klasserelasjonene til fetcherene 8

9 5.1.3 Parser Fig. 4: Visuell beskrivelse av klasserelasjonene til parserene 9

10 6 Backend Dette avsnittet dekker den delen av systemet som håndterer det som ikke kommer direkte til syne for brukeren. Det innebærer blant annet å hente data fra kildene, parse disse til konkrete verdiobjekter, lagre objektene og tilby måter for å hente ut disse på en sikker og god måte. Backend er utformet som et selvstendig API slik at det kan benyttes uavhengig av hva slags type frontend man ønsker å bruke det mot. Vi har valgt å bruke Wicket, men et ganske annerledes alternativ som Swing ville fungert like godt. Vi viser for øvrig til javadoc som en alternativ dokumentasjon til backend. Webside Frontend Backend Fig. 5: Illustrerer rollen til backend i den totale sammenhengen 6.1 Kort historisk oppsummering Dette punktet oppsummerer i veldig korte trekk hvordan systemets design oppsto: Vi valgte å starte med å hente såkalte tweets fra Twitter websiden og få disse skrevet ut i Eclipse konsollen. Det eneste kravet vi stilte var at dette skulle gjøres på den enklest tenkelige måten uavhengig av alle andre faktorer og vi endte da opp med en stor klasse som gjorde hele jobben. Dette kunne kanskje se noe planløst ut, men det var viktig for oss å få et visst overblikk før vi tok hensyn til design eller andre ting. Neste skritt var å analysere denne klassen for å finne ut hva slags oppgaver som faktisk ble utført. Det aller første vi måtte gjøre noe med var at det kun var selve statusmeldingen som ble skrevet ut. Vi ønsket også å hente og lagre annen informasjon som var knyttet til statusmeldingen slik som hvilken bruker som la den ut og når det ble gjort. Vi lagde da et verdiobjekt som representerte en tweet og som hadde de feltene vi ønsket. For å omdanne feeden fra Twitter til et slikt verdiobjekt lagde vi også en parser. 10

11 Den opprinnelige klassen vi startet med, som nå var blitt noe mindre, ble på nytt delt opp i to klasser med hvert sitt ansvarsområde. Den ene av dem hentet feeden fra Twitter, en såkalt fetcher, og den andre lagret verdiobjektene våre i en datastruktur og administrerte disse, en såkalt klient. Disse fire enkle klassene dannet nå grunnlaget for all videre påbygging som ble gjort. Frem til da hadde vi hentet ut statusmeldinger via xml feed, men Tarantell ønsket nå at vi også skulle hente json feeden og rss feeden som er de to andre typene Twitter tilbyr. Dette var selvfølgelig ikke nødvendig for systemets funksjonalitet, men mest for øvelsens skyld. På dette tidspunktet trakk vi inn interface basert design som vi mente var den beste løsningen. Dette gjorde at når vi senere skulle hente blogginnlegg og e-poster lett kunne implementere dette i designet. Med relativt like klienter som håndterte tre forskjellige verdiobjekter kunne vi nå dytte alt felles opp i en abstrakt superklasse og ta i bruk genetikk og arv. 6.2 Fetcherne I vår sammenheng betyr å fetche den handlingen å hente ned data fra en kilde. Øverst i fetcher hierarkiet står interfacet Fetcher som bør implementeres av alle klasser som ønsker å utføre en slik handling. Dersom en klasse som fungerer i henhold til det som er beskrevet over likevel velger å ikke implementere dette interfacet vil den selvfølgelig fremdeles kunne brukes som en uavhengig klasse, men vil ikke uten videre være kvalifisert som et argument til en klient. Dette vil bli klarere under avsnitt 6.5. Fetchere har en generisk typeparameter. Denne parameteren angir hva slags type den uprosesserte nedlastede dataen har. Som et eksempel vil det være helt naturlig at denne er en InputStream dersom fetcheren er av en slik art at den skal hente data fra en webside. I et tilfelle som dette vil det også være helt greit om man velger å konvertere disse dataene til en String i fetcheren før de returneres og da vil altså String være typeparameteren. Dette er opp til utvikleren selv og hva han eller hun finner naturlig eller hensiktsmessig. Det er en forutsetning at metoden public Feed<T> fetch() throws FetchException; blir implementert av fetcheren. Det er gjennom denne metoden selve hentingen foregår og dataene blir returnert. Metoden er parameterløs hovedsakelig av to årsaker: For det første er det noen ganger nødvendig å få oppdateringer fra en kilde relativt ofte. Det vil da være upraktisk å sende med de samme parameterne gang etter gang når de kan settes en gang for alle et annet sted. For det andre vil forskjellige fetchere ha behov for forskjellig informasjon. En fetcher som skal hente fra en webside trenger kanskje bare en url til siden mens en som skal hente fra en e-post konto vil trenge å vite protokoll, server, port, brukernavn, passord, etc. Som et resultat av dette er en fetcher nødt til å ha en konstruktør (eller alternativt settere) der disse feltene kan settes. Videre må metoden kaste en FetchException. Denne skal dekke alle feilsituasjoner som kan oppstå i forbindelse med henting av data. Man må dermed bruke try/catch blokker på alle unntak som kan oppstå og kaste disse som en FetchException. De nedhentede dataene returneres som et Feed objekt. Dette objektet kan du lese mer om i neste avsnitt. Avsnittene til tar for seg de konkrete implementasjonene av Fetcher interfacet som er inkludert i API et. 11

12 Fig. 6: Fetcher hierarkiet Feed objektet Fetcher interfacet er lagt opp på en slik måte at det kan returnere data som blir hentet uavhengig av deres type. Dette er løst ved bruk av objektet Feed hvis eneste hensikt er å pakke inn den opprinnelige feeden slik at fetch() metoden i en fetcher kan returnere et objekt av samme type uansett kilde. Denne klassen er laget generisk slik at man ved kall på dens getcontent() metode vil få feeden i dens opprinnelige type uten bruk av casting. Objektet vil kunne returneres fra fetcheren slik: return new Feed<T>(theFeed); der thefeed svarer til den opprinnelige feeden og den parametriske typen <T> svarer til samme type som fetcheren ble instansiert med Websider med autentisering Klassen AuthenticatingFetcher er en konkret klasse for å hente ned en fil på web som krever autentisering fordi innholdet er beskyttet av for eksempel.htaccess. I vårt program bruker vi den i forbindelse med å hente feed fra websiden Twitter. Hvordan brukes klassen? Klassen brukes ved at den opprettes med brukernavn, passord og uri som parametre, som alle er av typen String. Parameteren uri representerer en streng av tegn som identifiserer en ressurs på internett, i dette tilfellet en url. Ingen av disse parameterne får lov å være null. Konstruktøren vil da kaste en NullArgumentException. Videre vil man kunne få data fra fetcheren ved kall på dens fetch() metode som var drøftet i avsnitt

13 Hvordan fungerer klassen? Klassen fungerer ved at den oppretter et HttpURLConnection objekt som blir en kommunikasjonslink mellom applikasjonen og den beskyttede websiden. De overnevnte parametrene brukes av dette objektet gjennom metoden authenticate(). Denne metoden kalles hver gang man vil hente data fra kilden selv om det strengt tatt er tilstrekkelig å autentisere kommunikasjonslinken en gang. Alternativet ville blitt å gjøre dette en gang i konstruktøren, men da måtte vi foretatt unntakshåndteringen der og dette ønsket vi å unngå. Et poeng med systemet er å i størst mulig grad unngå å lage kode som allerede finnes hvis denne er slik at den passer inn i programmet. Før vi lagde denne klassen så vi på den allerede ferdiglagde java.net.authenticator som i bunn og grunn gjør samme jobben. Problemet med denne er at for å sette innloggingsakkreditiver kalles metoden Authenticator.setDefault(Authenticator). At denne er static skapte et potensielt problem for oss da vi ønsket å lage API et slik at man kunne bruke denne klassen til å logge inn på forskjellige kontoer eller forskjellige websider om hverandre. Dette lot seg ikke gjøre med Authenticator som setter en standard for hele applikasjonen. Denne kunne heller ikke settes til en annen verdi senere. AuthenticatingFetcher er dermed bygget på en slik måte at den kan opprettes i flere instanser for å oppnå disse målene. Denne klassens generiske type, som representerer de uprosesserte dataene, er en String (konvertert fra InputStream etter den er hentet ned) Websider uten autentisering Klassen NonAuthenticatingFetcher er en konkret klasse for å hente ned en fil på web som ikke krever autentisering. Dette gjelder det store flertallet av websider. I vårt program bruker vi den i forbindelse med å hente feed fra Tarantell bloggen. Hvordan brukes klassen? Klassen brukes ved at den opprettes med en String parameter uri som identifiserer en ressurs på internettet, i dette tilfellet en url. Parameteren får ikke lov til å være null. Konstruktøren vil da kaste en NullArgumentException. Videre vil man få data fra fetcheren ved kall på dens fetch() metode som var drøftet i avsnitt 6.2. Hvordan fungerer klassen? Klassen fungerer ved at den oppretter et HttpURLConnection objekt som blir en kommunikasjonslink mellom applikasjonen og den ubeskyttede websiden. Den overnevnte parameteren uri brukes av dette objektet i fetch() metoden for å hente dataene. HttpURLConnection objektet vil bli reinstansiert hver gang data hentes selv om det strengt tatt er tilstrekkelig å sette dette en gang. Alternativet ville blitt å gjøre dette i konstruktøren, men da måtte vi foretatt unntakshåndtering der og dette ønsket vi å unngå. Denne klassens generiske type, som representerer de uprosesserte dataene, er en String (konvertert fra InputStream etter den er hentet ned). 13

14 6.2.4 E-post Klassen Fetcher er en konkret klasse for å hente e-poster fra en mailserver. I vårt program bruker vi den i forbindelse med å hente Tarantells fellesmail. Hvordan brukes klassen? Klassen brukes ved at den opprettes med grunnleggende informasjon om serveren det skal hentes e-poster fra og innloggingsakkreditiver. De støttede protokollene er Internet Message Access Protocol (IMAP) og Post Office Protocol 3 (POP3). Noen servere vil kanskje også kreve at man bruker secure sockets layer (SSL) krypteringsprotokollen for å få tilgang. Hvis dette er tilfellet burde protokollen ende på s slik at det blir imaps og pop3s. Den boolske variabelen securessl settes samtidig til true. Til slutt må det spesifiseres en mailserver og porten på denne serveren det skal kobles til. Hvis et negativt eller på annen måte ugyldig portnummer spesifiseres vil fetcheren bruke standardportene 143 for imap og 110 for pop3. Verken protokoll, mailserver, brukernavn eller passord får lov til å være null. Konstruktøren vil da kaste en NullArgumentException. Videre vil man få data fra fetcheren ved kall på dens fetch() metode som var drøftet i avsnitt 6.2. Hvordan fungerer klassen? Klassen fungerer ved at den oppretter to objekter session og url på bakgrunn av parameterne som ble spesifisert i konstruktøren. Disse objektene representerer henholdsvis en mailsesjon og et url navn. Ved kall på fetch()metoden vil man fra kombinasjonen av disse få ut et Store objekt som modellerer et e-post lager. Det er dette lageret pakket inn i et Feed objekt som returneres fra metoden. Klassens generiske type er dermed Store. 6.3 Verdiobjektene I dette avsnittet tar vi for oss verdiobjektene i API et. Verdiobjekter er objekter som kun holder på verdier og har liten eller ingen logikk. Siden de ikke inneholder logikk i noen særlig grad og bør være enkle og oversiktlige dekker vi disse i relativt korte trekk. I vår applikasjon er verdiobjektene Tweet, BlogPost og . Dersom man ønsker å tilføre API et et nytt verdiobjekt er det kun et reelt hensyn å ta. Verdiobjektet må overskrive metoden public boolean equals(object) som alle klasser arver fra Object. Uten overskrivelse vil denne metoden returnere true hvis, og bare hvis, to objekter er fysisk like. To verdiobjekter av samme type som sammenlignes bør også regnes som ekvivalente dersom de har logisk likhet. Hvordan man definerer logisk likhet for de to verdiobjektene vil komme helt an på hvilke felter objektene har, men det mest åpenbare eksempelet er hvis objektet har et felt id som er unikt. Da bør alle objekter med en tilsvarende id regnes som like selv om de ikke er det samme fysiske objektet. Men et verdiobjekt kan aldri være ekvivalent med et objekt av en annen klasse uansett om denne tilfeldigvis også skulle ha et felt id. 14

15 Videre kan man implementere interfacet Comparable slik at verdiobjektet blir sammenlignbart med seg selv. Dette er ikke obligatorisk, men ved å gjøre dette kan man definere den naturlige ordenen for instanser av denne typen. Dette kan være en fordel senere slik at lister av denne typen senere kan sorteres for eksempel kronologisk eller bibliografisk etter en valgt egenskap Tweet Twitter er en sosial nettverks- og mikrobloggtjeneste som lar sine brukere sende og lese andre brukeres statusmeldinger. Beskjedene er tekstbaserte, opp til 140 tegn lange og blir synlige for andre brukere som har abonnert på dette. Slike statusbeskjeder er kjent som tweets. En instans av denne klassen modellerer en slik tweet som et Java objekt. Denne klassen inneholder felter for en tweet sin unike ID (hentet fra Twitter, ikke generert av applikasjonen), brukeren som publiserte tweeten, referanser til bilde av brukeren, når tweeten ble publisert og naturligvis meldingen selv. Siden det aldri burde være noe behov for å endre en tweet inneholder klassen ingen settere og alle dens felter er konstanter. En instans av denne klassen er regnet som logisk ekvivalent med et annet objekt av samme klasse med samme id. Den er også sammenlignbar med seg selv slik at dens naturlige orden er i kronologisk synkende rekkefølge BlogPost Blogg (eng:blog) er en sammentrekning av begrepet weblog og er en relativt ofte oppdatert, kronologisk publikasjon på en webside. Den kan inneholde alt av betydning for utgiveren, men den er vanligvis en samling av reflekterende innlegg, beskrivelse av hendelser eller materiale som audio, grafikk eller video. En enkel publikasjon på en blogg er kjent som en post. Denne klassen modellerer en slik post som et Java objekt. Denne klassen inneholder felter for en post sin tittel, navnet på den som har skrevet posten, når den ble postet og naturligvis posten selv. Siden det aldri burde være noe behov for å endre en post inneholder klassen ingen settere og alle dens felter er konstanter. Derimot kan det i enkelte tilfeller være hensiktsmessig å utvide den ved å lage en subklasse for å representere en mer konkret post med felter den generelle posten ikke har. En instans av denne klassen er regnet som logisk ekvivalent med et annet objekt av samme klasse med samme tittel og samme tidsstempel. Den er også sammenlignbar med seg selv slik at dens naturlige orden er i kronologisk synkende rekkefølge. 15

16 En instans av denne klassen representerer en enkel elektronisk post. Den inneholder felter for navnene og adressene til sendere og mottakere, e-postens emne, navnene på eventuelle vedlegg, når den ble sendt og naturligvis selve teksten (eng:body). Siden det aldri burde være behov for å endre en e-post inneholder klassen ingen settere og alle dens felter er konstanter. Derimot kan det i enkelte tilfeller være hensiktsmessig å utvide den ved å lage en subklasse for å representere en mer konkret e-post med flere parametre. En instans av denne klassen er regnes som logisk ekvivalent med et annet objekt av samme klasse med samme emne og samme tidsstempel. Den er også sammenlignbar med seg selv slik at dens naturlige orden er i kronologisk synkende rekkefølge. 6.4 Parserne I de forrige avsnittene har vi tatt for fetchere og verdiobjekter, hva de er og hvordan de virker. I dette avsnittet skal vi se på hvordan data som blir returnert fra en fetcher blir parset til verdiobjekter. Øverst i parser hierarkiet står interfacet Parser som bør implementeres av alle klasser som ønsker å parse en eller annen type data til verdiobjekter. Dersom en klasse som fungerer i henhold til dette likevel velger å ikke implementere Parser interfacet vil den selvfølgelig fremdeles kunne brukes som en uavhengig klasse, men vil ikke uten videre være kvalifisert som et argument til en klient. Dette vil bli klarere under avsnitt 6.5. Parsere har to generiske typeparametre. Den første typen angir hva slags verdiobjekt den mottatte feeden skal parses til, for eksempel Tweet, BlogPost eller . Den andre parameteren angir, som for fetchere, hva slags type den uprosesserte dataen som er pakket inn i det mottatte Feed objektet er. Det er en forutsetning at metoden public List<E> parse(feed<t> feed) throws ParseException; blir implementert av parseren. Det er gjennom denne metoden selve parsingen foregår og verdiobjektene blir returnert. Metoden tar imot et objekt av typen Feed som er den samme typen som returneres fra en fetcher. Legg merke til at en enkel feed ikke returnerer et enkelt verdiobjekt, men en liste med flere. For eksempel vil en enkel Twitter feed returnere det som tilsvarer 20 separate Tweet objekter. Videre må metoden kaste en ParseException. Denne skal dekke alle feilsituasjoner som kan oppstå i forbindelse med parsingen. Man må dermed bruke try/catch blokker på alle unntak som kan oppstå og kaste disse som en ParseException. Klasser som implementerer Parser interfacet trenger ingen konstruktør da de får alle data de trenger gjennom den nevnte parse metoden. 16

17 Dette avsnittets underpunkter tar for seg de konkrete implementasjonene av Parser interfacet. De fleste klassene benytter seg av eksterne biblioteker for å ta seg av selve parsingen, typisk å sende inn feeden i et objekt, iterere dette og hente ut verdiene som strenger. Vi går derfor ikke gjennom hvordan dette fungerer for hver klasse separat. Fig. 7: Parser hierarkiet Twitter feed I enkelte tilfeller kan det være ønskelig å begrense et interface ytterligere. TwitterParser er et interface som bør implementeres av alle klasser som utelukkende ønsker å parse feed fra Twitter. Dette interfacets generiske typer er Tweet fordi vi ønsker at feeden skal resultere i en liste av Tweet objekter, og String fordi parameteren feed er et Feed objekt som pakker inn nettopp en streng. Dette er den uprosesserte dataen fra Twitter feeden. I tillegg til metoden interfacet arver fra Parser må alle klasser som implementerer TwitterParser også inkludere en metode public String getformat();. Denne returnerer ganske enkelt en streng med kildefilens format. For klasser som parser rss feed returnerer denne metoden.rss, for klasser som parser xml feed returnerer metoden.xml osv. 17

18 6.4.2 Twitter json feed Klassen TwitterJSONParser er en konkret klasse for å parse feed som har sin opprinnelse i Twitter sin.json feed. Klassen implementerer interfacet TwitterParser. Hvordan brukes klassen? Klassen opprettes uten parametre. Videre kalles parse metoden som ble drøftet under avsnitt 6.4. Argumentet til metoden bør være et Feed objekt fra en AuthenticatingFetcher instansiert med uri en til Twitter sin.json feed. Metoden returnerer en liste bestående av 20 Tweet objekter Twitter rss feed Klassen TwitterRSSParser er en konkret klasse for å parse feed som har sin opprinnelse i Twitter sin.rss feed. Klassen implementerer interfacet TwitterParser. Hvordan brukes klassen? Klassen opprettes uten parametre. Videre kalles parse metoden som ble drøftet under avsnitt 6.4. Argumentet til metoden bør være et Feed objekt fra en AuthenticatingFetcher instansiert med uri en til Twitter sin.rss feed. Metoden returnerer en liste bestående av 20 Tweet objekter. NB! Rss feeden til Twitter er langt mindre omfattende enn for.json og.xml. Det anbefales derfor at en av disse brukes isteden. Pga dette ville felter som bildereferanse blir satt til null fordi denne ikke eksisterer i feeden Twitter xml feed Klassen TwitterXMLParser er en konkret klasse for å parse feed som har sin opprinnelse i Twitter sin.xml feed. Klassen implementerer interfacet TwitterParser. Hvordan brukes klassen? Klassen opprettes uten parametre. Videre kalles parse metoden som ble drøftet under avsnitt 6.4. Argumentet til metoden bør være et Feed objekt fra en AuthenticatingFetcher instansiert med uri en til Twitter sin.xml feed. Metoden returnerer en liste bestående av 20 Tweet objekter Blog feed Klassen BlogParser er en konkret klasse for å parse feed som har sin opprinnelse i en blogg sin.rss feed. Hvordan brukes klassen? Klassen opprettes uten parametre. Videre kalles parse metoden som ble drøftet under avsnitt 6.4. Argumentet til metoden bør være et Feed objekt fra en NonAuthenticatingFetcher instansiert med uri en til bloggens.rss feed. Hvor mange BlogPost objekter som ligger i den returnerte listen vil avhenge av bloggen det hentes fra. 18

19 6.4.6 E-post Klassen Parser er en konkret klasse for å parse fra et objekt som modellerer et e-post lager. Vær oppmerksom på at denne klassen har en relativt enkel tilnærming til e-post håndtering hvilket betyr at det vil dekke kun de vanligste tilfellene. Eksempler på tilfeller som havner utenfor denne klassens ansvarsområde er e-poster med ugyldig format, som har ugyldige tegnsett, som har digital signatur eller er kryptert. I noen tilfeller kan det også hende at JavaMail ikke får tak i den informasjonen den trenger fra e-post tilbyderen, noe som vil direkte påvirke parseren. Hvordan brukes klassen? Klassen opprettes uten parametre. Videre kalles parse metoden som ble drøftet under avsnitt 6.4. Argumentet til metoden bør være et Feed objekt fra en Fetcher. Parseren vil returnere en liste med objekter som representerer alle uleste e-poster fra inboksen i det respektive e-post lageret. 6.5 Klientene Etter å ha lest om tilsynelatende usammenhengende klassehierarkier skal vi nå ta for oss hvordan det hele blir sydd sammen med klientene. En klient er en klasse som er ansvarlig for administreringen av de forskjellige verdiobjektene. Hvert verdiobjekt har sin egen type klient med sine egne metoder helt spesifikke for dette verdiobjektet. Det er også klientene som er backendet s ansikt utad. Det vil si at det er disse et frontend skal henvende seg mot for å få tak i de verdiene det trenger. Øverst i klienthierarkiet finner vi GenericClient som er en abstrakt superklasse til alle andre klienter. Fig. 8: Klient hierarkiet 19

20 6.5.1 Generisk klient Hensikten med den generiske klienten er å få det som er felles for alle klienter opp i en superklasse. I tillegg har den noen få metoder som er ment for å danne grunnlaget for generelle convenience metoder som kan være nyttige å implementere i en klient. Gjennom disse vil man for eksempel kunne få en filtrert-, sortert- eller komplett liste med verdiobjektene klienten administrerer. Klienter har to generiske typeparametre. Den første typen angir hva slags verdiobjekt klienten administrerer, for eksempel Tweet, BlogPost eller . Den andre parameteren angir, som for fetchere og parsere, hva slags type den uprosesserte dataen dette objektet oppsto fra er. Den generiske klienten har følgende konstruktør: protected GenericClient(Fetcher<T> fetcher, Parser<E, T> parser, int maxitems); Fra konstruktøren leser vi at den er i stand til å bruke en hvilken som helst klasse som implementerer Fetcher interfacet og tilsvarende for parsere. Subklasser av denne klienten står så fritt til å begrense dette så mye de vil. For eksempel er det naturlig for en klient som håndterer Tweet objekter å begrense Parser til å måtte være en TwitterParser. Den siste parameteren maxitems angir hvor mange samtidige objekter klienten får håndtere. Dersom denne er negativ vil klienten kunne håndtere et uendelig antall. Det finnes også en tilsvarende konstruktør i klassen uten sistnevnte argument der maxitems automatisk settes til -1. Argumentene fetcher og parser får ikke være null. Konstruktøren vil da kaste en NullArgumentException. For å starte å populere klienten med verdiobjekter kalles metoden public boolean update(). Klienten vil da selv sørge for å håndtere samspillet mellom fetcher og parser. Metoden returnerer en boolsk variabel som indikerer om det virkelig har skjedd en oppdatering. Det forekommer ofte at kilden ikke er oppdatert siden sist eller hvis det eventuelt har oppstått en exception under prosessen. Returverdien fra metoden kan for eksempel indikere til en klasse på et høyere nivå om det er behov for å utføre endringer i frontend. update() benytter seg av følgende private metoder: private boolean addnewitems(list<e> newitems); Gjennom update() får denne metoden tilsendt listen med verdiobjekter som ble returnert av parseren. Denne metoden vil sørge for at klientens listestruktur med verdiobjekter til enhver tid forblir sortert kronologisk synkende ved å legge de nyeste objektene først. Metoden tillater heller ikke at listen inneholder duplikater (avsnitt 6.3 beskriver hvordan dette unngås ved å definere logisk likhet). private void removeexcessiveitems(); Dersom maxitems definerer et maks antall objekter klienten får håndtere vil denne metoden sørge for å opprettholde dette kravet ved å fjerne de eldste verdiobjektene fra listen. Med eldste menes de objektene som havnet i listen først og som nå ligger bakerst. Klassens resterende metoder er alle ment som et grunnlag for convenience metoder for klienter som arver fra denne. Disse er relativt enkle og vil ikke bli videre drøftet her. Et viktig poeng er likevel at alle disse har til felles at de unngår å eksponere klassens private liste med administrerte objekter for å unngå manipulering av denne. Denne listen returneres isteden som en Collections.UnmodifiableList eller en grunn kopi. 20

21 6.5.2 Twitterklient, bloggklient og e-postklient De tre spesifikke klientene TwitterClient, BlogClient og Client er alle såpass enkle at vi har valgt å ikke greie ut noe særlig om disse. Kort fortalt populeres de via update() metoden som er omtalt i avsnitt Videre inneholder de en mengde convenience metoder som returnerer filtrerte, sorterte eller komplette lister med deres respektive verdiobjekter. 7 Frontend I korte trekk består frontend-delen av web-rammeverket og websiden i systemet. I frontend blir informasjonen fra de allerede eksisterende kildene hentet gjennom backend, og deretter blir denne informasjonen prosessert ut på websiden. Web-rammeverket vi har brukt er Apache Wicket, som er et godt rammeverk. Wicket er et eget Javabibliotek. Sammen med websiden har vi også brukt CSS for å sette stil på Twitter-, blog- og epostdelene. Vi har også brukt Javascript for å legge til Flash i overskriften. Sammen med Java har vi brukt Spring IoC (Inversion of Control) for å lage Javabeans av klasser og konstanter. For å starte serveren på localhost:8080 har vi brukt Jetty. 7.1 Jetty Jetty er en gratis nedlastbar webserver som er brukt i dette systemet. I dette systemet lages det en jar-fil ved hjelp av Maven. Maven pakker da frontend inn i en eksekverbar jar-fil. Jetty bruker den pakkede jar-filen, og legger denne ut på Localhost:8080. Man går da inn på for å se websiden. 21

22 7.2 Apache Wicket Wicket er et web-rammeverk som fungerer meget bra, og er oversiktlig. Det fungerer på den måten at den bruker en konfigureringsfil (web.xml) som henviser til en Javaklasse som er grunnlaget for webapplikasjonen. Denne Javaklassen utvider (extends) klassen WebApplication som forteller Wicket at dette er webapplikasjonen. Det eneste denne klassen trenger å inneholde er en metode som returnerer Javaklassen til hovedwebsiden. Hovedwebsiden (Javaklassen) som blir referert til, må utvide klassen WebPage som forteller Wicket at dette er en webside. Grunnen til at det må være to forskjellige klasser er at en klasse ikke kan utvide to klasser. I tillegg til websideklassen må det være en korresponderende fil som er en HTML-fil. Både Javaklassen og HTML-filen må ha samme navn for at HTML-koden kan referere til Wicket-IDer i Javaklassen. Wicket-IDer fungerer på den måten at de blir opprettet i Javaklassen, og de blir dermed referert til innenfor en HTML-tag. Her er et kodeeksempel: Index.java: add(new Label( hello, Hello World )); Index.html: <span wicket:id= hello /> Utskriften på websiden i dette tilfellet blir Hello World. I eksempelet brukes Label, og den krever her: Label(String id, String innhold) Dersom man vil ha flere sider, må man opprette flere Javaklasser med korresponderende HTML-filer. Disse nye Javaklassene må enten utvide klassen WebPage eller hovedwebsideklassen som allerede utvider WebPage. Minimum èn av disse må også bli referert til i hovedwebsideklassen. 22

23 7.3 Spring IoC (Inversion of Control) Spring IoC kan brukes til å lage Javabeans av klasser. Dette fungerer, i dette systemet, på den måten at man først må referere til en XML-fil som inneholder bønnene, i samme web.xml-fil som brukes av Wicket. I XML-filen som inneholder alle bønnene må man referere til samme webapplikasjon-fil som Wicket refererer til i web.xml. I den webapplikasjons-filen må man legge til en metode som brukes til å initialisere Spring Bean Injection, slik at man kan få tilgang til å bruke Springbeans ved hjelp av å injeksere (inject) bønnene til bruk i Java-filene. Spring instansierer klassene når man oppretter bønnene. Disse bønnene kan man endre på mens man kjører. I dette systemet kan man for eksempel endre en konstant mens man kjører serveren, uten å måtte restarte serveren får å se endringene. Det er gode eksempler på hvordan man oppretter bønner og injekserer dem i Javaklassene i frontend-delen av systemet, men her er et kodeeksempel: applicationcontext.xml: <bean id= hello class= java.lang.string > <constructor-arg value= Hello World /> </bean> hello ) private String hei; I dette eksempelet lages en tekst-streng som en konstant. hei -variabelen i Javaklassen blir her satt til å inneholde Hello World. 23

24 7.4 Javaklassene Frontend består av 3 Javaklasser: Index.java, WicketApplication.java, og URLImage.java. Disse klassene inneholder logikken bak det å hente informasjon via backend, og å vise denne informasjonen på websiden Index Fig. 9: Oversikt over klassen Index.java Denne klassen er drivkraften bak websiden Index.html. Her ligger logikken bak det å hente informasjon fra de allerede eksisterende kildene via backend. Index.java utvider (extends) klassen WebPage, som forteller wicket at denne klassen er en webside. Det kreves også en HTML-fil med samme navn, og som ligger i samme mappe. I Javaklassen blir alle wicket-idene generert med innhold, og i HTML-filen blir det referert til disse IDene, og dermed blir det vist tekst og bilder. Disse IDene blir generert i insert-metodene i denne klassen. setheadercontributors() -metoden legger til en link i head -tagen i htmlfilen til plasseringen av både CSS-filen og Javascript-filen i systemet. 24

25 7.4.2 WicketApplication Fig. 10: Oversikt over klassen WicketApplication.java Denne klassen blir referert til fra både web.xml og applicationcontext.xml. Den utvider (extends) WebApplication som fortell Wicket at dette er webapplikasjonen, samt returnerer klassen til hovedwebsiden (Index.java) gjennom metoden gethomepage(). Metoden init() tilgjengeliggjør muligheten til å injeksere (inject) Springbeans i websidene. Fig. 11: Bilde av beskjeden man får uten å overskrive metoden outputdevelopmentmodewarning() outputdevelopmentmodewarning() -metoden er en tom metode som brukes til å skrive over en advarselbeskjed man får i kommando-vinduet når man kjører Jetty for å starte applikasjonen på Localhost:8080. Siden metoden er tom, fjerner den hele beskjeden. (Ref. Fig 11) URLImage Fig. 12: Oversikt over klassen URLImage.java Denne klassen brukes av Index.java for å få lagt til bilder ved siden av teksten til alle Tweetene. Wicket har en innebygget metode for å legge til bilder i et HTML-dokument, men da må bildene ligge på samme server som Wicket blir kjørt fra. For å overstyre dette og få brukt bilder fra internettkilder, kan man gjøre det som det er gjort i denne klassen, som legger til en src i img -tagen, og deretter legges linken til. 25

26 7.5 Øvrige filer I tillegg til Javafilene inneholder frontend noen andre filer som er med på å forme websiden, samt en fil for å Wicket til å fungere og en fil som inneholder instansiering av klasser ved hjelp av Spring IoC HTML Index.html er selve websiden. Den bruker Javaklassen Index for å hente ut informasjonen som skal vises på nett. Dette gjør den ved hjelp av Wicket-IDer som man refererer til i Index.java. Denne siden bruker også samme flash-video som brukes på Tarantell AS sine egne websider ( All formattering av innholdet i siden blir gjort ved hjelp av en CSS-fil. Det er også brukt egengenererte bilder som det linkes til i denne siden CSS All formattering av innholdet blir gjort i filen stylesheet.css. Selv om bruk av CSS er mest brukt til å få lik formattering og struktur på flere websider, så har vi valgt å bruke dette på Index.html siden det er mye lettere å holde oversikt. Bruk av CSS gjør det også mulig å gjøre endringer mens man kjører websiden på serveren, og man får endringene da kun ved hjelp av å ta en refresh av websiden web.xml Denne filen instansierer bruken av både Wicket og Spring IoC. Dette er en konfigurasjonsfil som for Wicket referer til webapplikasjonen i systemet (WicketApplication.java), og for Spring IoC referer den til filen der all instansiering av Javaklasser og der Javabeans blir laget (applicationcontext.xml) applicationcontext.xml Denne filen inneholder all instansiering av konstanter og Javaklasser. Det blir dannet bønner av disse, som senere blir injeksert (inject) i Javaklassene som skal bruke dem. En stor fordel ved å gjøre det på denne måten er at man kan gjøre endringer i denne filen mens man kjører systemet, og endringene skjer uten å måtte restarte systemet. Dersom man for eksempel ønsker å vise flere eller færre antall Tweets på websiden, trenger man kun å gjøre endringer i verdien til bønna med visibletweets som ID. Dette kan man da gjøre uten å måtte restarte serveren for å se endringer, men bare ved å ta en refresh av siden. <bean id="visibletweets" class="java.lang.integer"> <constructor-arg value="5" /> </bean> 8 Systemets krav til maskinvare Systemet krever ikke noen spesiell maskinvare, annet enn at maskinen må ha internettilgang for å kunne hente informasjon fra de eksterne kildene. Maskinen må ha Java og Maven 2 installert. Systemet er programmert med Java, og kan brukes på et vidt spekter av operativsystem, siden Java er platformuavhengig. Systemet er utviklet og testet på Mac OS X, Windows XP og Windows Vista. Det er også testet på Ubuntu Linux. De nettleserne systemet er testet på, er Firefox, Opera, Internet Explorer og Safari. 26

27 9 Installasjon av systemet Før programmet kan kjøres må Java 1.5 (java.sun.com) og Maven 2 (maven.apache.org) være installert på maskinen og innholdet av zip-filen med kildekoden man finner på dette prosjektets hjemmeside, må være kopiert inn på lokaldisken. Mappen ext-lib inneholder prosjektavhengigheter som ikke finnes i Mavens sentrale repository. Disse må derfor installeres manuelt (punkt 2, 3 og 4). Ved første gangs kjøring vil det ta noe tid å laste ned klassebibliotekene fra nettet. Det er ikke laget noen kjørbar fil som kan eksekvere kommandoene da de må utføres sekvensielt (f. eks batch-filer starter eksekveringen av en kommando før den forrige er ferdig). 1. cd ext-lib 2. mvn install:install-file -DgroupId=javax.jms -DartifactId=jms -Dversion=1.1 -Dpackaging=jar -Dfile=jms-1.1.jar 3. mvn install:install-file -DgroupId=com.sun.jmx -DartifactId=jmxri -Dversion= Dpackaging=jar -Dfile=jmxri jar 4. mvn install:install-file -DgroupId=com.sun.jdmk -DartifactId=jmxtools -Dversion= Dpackaging=jar -Dfile=jmxtools jar 5. cd../backend 6. mvn install 7. cd../frontend 8. mvn jetty:run 9. Normalt vil dette være tilstrekkelig for kjøring, men vi har opplevd fra tid til annen at Maven ikke kopierer over frontendets html-side. Sjekk derfor at filen "frontend/src/main/java/no/tarantell/dashboard/wicket/index.html" også finnes i "frontend/target/classes/no/tarantell/dashboard/wicket". Hvis ikke; kopier den over manuelt. Prosjektet kan kjøres på følgende adresse: Siden kan og bør optimaliseres til din skjerm og oppløsning. Innstillingene er nå satt til å passe en oppløsning på 1280 x 1024 punkter. Dersom du ønsker å endre innstillingene, kan du gå inn i applicationcontext.xml og endre konstantene som forteller om antall visbare Tweets, Blog poster og eposter, og endre antall visbare karakterer i innholdet til Blog postene og epostene. Eclipse-prosjekter kan genereres med kommandoen 'mvn eclipse:eclipse' i henholdsvis backend og frontend mappene. 27

28 10 Oversikt over filer Her er en oversikt over filer som ligger i systemet, med filendelse og under hvilken mappe de ligger i. I tillegg til disse filene, er det en pom.xml fil i hver av hovedmappene (backend og frontend). Denne filen brukes av Maven for å laste ne dog legge til alle de eksterne bibliotekene som blir brukt, samt tilgjengeliggjør Jetty-serveren Backend Backend Filnavn Filtype Mappe Feed java dashboard Launcher java dashboard BlogClient java client Client java client GenericClient java client TwitterClient java client AuthenticatingFetcher java fetcher Fetcher java fetcher Fetcher java fetcher FetchException java fetcher NonAuthenticatingFetcher java fetcher BlogParser java parser DateTimeParser java parser Parser java parser ParseException java parser Parser java parser TwitterJSONParser java parser TwitterParser java parser TwitterRSSParser java parser TwitterXMLParser java parser BlogPost java valueobject java valueobject Tweet java valueobject 28

29 10.2 Backend-tester Backend-tester Filnavn Filtype Mappe MasterTestSuite java dashboard TestData java dashboard BlogClientTest java dashboard ClientTest java client GenericClientTest java client TestSuite java client TwitterClientTest java client AuthenticatingFetcherTest java fetcher FetcherTest java fetcher NonAuthenticatingFetcherTest java fetcher TestSuite java fetcher BlogParserTest java parser DateTimeParserTest java parser ParserTest java parser TestSuite java parser TwitterJSONParserTest java parser TwitterRSSParserTest java parser TwitterXMLParserTest java parser BlogPostTest java valueobject Test java valueobject TestSuite java valueobject TweetTest java valueobject 29

30 10.3 Frontend Frontend Filnavn Filtype Mappe Index html wicket Index java wicket WicketApplication java wicket URLImage java wicket stylesheet css css header jpg images logo jpg images spacer jpg images swfobject js js applicationcontext xml WEB-INF web xml WEB-INF 30

31 11 Oversikt over Javabibliotek Her er en oversikt over Javabibliotekene som er brukt i systemet, med versjonsnummer, samt om de ved hjelp av maven blir automatisk lastet ned og installert, eller ikke. Dersom de automatisk blir lastet ned og installert, ligger disse i Maven Repository Backend Backend Gruppe Artifakt Versjon Auto/Manuell installering javax.activation activation 1.1 Automatisk commons-beanutils commons-beanutils Automatisk commons-cli commons-cli 1.0 Automatisk commons-codec commons-codec 1.3 Automatisk commons-collections commons-collections 3.2 Automatisk org.apache.commons commons-parent 2.4 Automatisk commons-logging commons-logging Automatisk net.sf.ezmorph ezmorph Automatisk jdom jdom 1.0 Automatisk javax.jms jms 1.1 Manuell com.sun.jmx jmxri Manuell com.sun.jdmk jmxtools Manuell joda-time joda-time 1.6 Automatisk net.sf.json-lib json-lib Automatisk junit junit 4.5 Automatisk junit-addons junit-addons 1.4 Automatisk log4j log4j Automatisk javax.mail mail 1.4 Automatisk org.mockito mockito-all 1.6 Automatisk rome rome 0.9 Automatisk xerces xercesimpl Automatisk 31

32 11.2 Frontend Frontend Gruppe Artifakt Versjon Auto/Manuell installering aopalliance aopalliance 1.0 Automatisk cglib cglib-nodep 2.1_3 Automatisk org.eclipse.jdt core Automatisk geronimo-spec geronimo-spec-jta 1.0.1B-rc4 Automatisk org.mortbay.jetty jetty Automatisk org.mortbay.jetty jetty-annotations Automatisk org.mortbay.jetty jetty-management Automatisk org.mortbay.jetty jetty-naming Automatisk org.mortbay.jetty jetty-plus Automatisk org.mortbay.jetty jetty-util Automatisk org.mortbay.jetty jsp Automatisk org.mortbay.jetty maven-jetty-plugin Automatisk org.slf4j slf4j-log4j Automatisk org.springframework spring Automatisk org.springframework spring-beans Automatisk org.springframework spring-context Automatisk org.springframework spring-core Automatisk org.mortbay.jetty start Automatisk org.apache.wicket wicket Automatisk org.apache.wicket wicket-ioc Automatisk org.apache.wicket wicket-spring Automatisk org.apache.wicket wicket-spring-annot Automatisk 32

33 12 Kilder I tillegg til har vi brukt for å søke etter informasjon og veiledning på hvordan man skal bruke de forskjellige nye verktøyene og bibliotekene vi ikke har vært igjennom tidligere. 33

34 13 Vedlegg 13.1 Vedlegg 1 Fig. 13: Klasserelasjoner til klientene 34

35 Fig. 14: Klasserelasjoner til fetcherene 35

36 Fig. 15: Klasserelasjoner til parserene 36

37 Fig. 16: Oversikt over klassene i mappen dashboard Fig. 17: Oversikt over verdiobjekt-klassene 37

38 Fig. 18: Oversikt over Javaklassene i frontend 38