HØGSKOLEN I OSLO OG AKERSHUS. FôrIt CDS. Produktdokumentasjon

Transkript

1 HØGSKOLEN I OSLO OG AKERSHUS FôrIt CDS Stian Strøm Anderssen, Mikkel Sannes Nylend og Shahariar Kabir Bhuiyan Gruppe

2 Forord en er en beskrivelse av webapplikasjonen FôrIt CDS. Den første delen av beskrivelsen gir leseren et innblikk i hva applikasjonen er og hvordan den fungerer for en bruker. Denne delen er ikke alt for teknisk, men er til for å få et innblikk i hvordan brukergrensesnittet fungerer med funksjonene. Videre går produktrapporten mer og mer i teknisk detalj om hvordan applikasjonen er bygget opp og kodet. Derfor er produktdokumentasjonen skrevet for lesere med erfaring innen systemutvikling og bør helst kunne grunnleggende Java. Det er også en stor fordel å ha kjennskap til andre kjente programmeringsspråk som CSS, XML og HTML. Beskrivelsen er laget for at leser skal få en oversikt over FôrIt CDS. Leser skal ved hjelp av dette dokumentet ha mulighet til å videreutvikle og vedlikeholde applikasjonen. Siden dokumentet inneholder svært tekniske begreper finnes det fotnoter på hver side og ordforklaringer som ligger helt til slutt av hele sluttrapporten. 1

3 Innholdsfortegnelse Forord...0 Innholdsfortegnelse Brukerdokumentasjon Bruk av applikasjonen Innloggingsskjerm Hjem Detaljer Se på kart Meny Profil Informasjon Logg ut Feilmeldinger Kodestandard og verktøy Applikasjonens funksjoner Innlogging Hurtigvisning av alle ordrene Detaljer for hver ordre Sporing av hver ordre på kart Bytte språk Informasjon om EWOS, Goodtech og applikasjonen Logge ut Programmets oppbygning Moduler Parent Server Common

4 4.5 Client Standalone Hovedoppbygning Database Webservice Klient Servere Klasseforklaringer Hovedklasser Modellklasser Views og components Kobling til webservice Andre Teknisk beskrivelse av applikasjon Innloggingsfunksjon Sessions Views og komponenter Accordion Lyttere Visning av bilder og ikoner CSS Kommunikasjon med webservice Link fra ressursfil Konvertering til Java objekter Kart Språk Feilhåndtering og logging Feilhåndtering

5 8.2 Tilbakemeldinger til bruker Logging Resterende arbeid

6 1 Brukerdokumentasjon Dette kapittelet beskriver hvordan en kan bruke og teste applikasjonen. Det viser de forskjellige vinduene med en kort beskrivelse til hvert av de. Dette vil gi leser et kort innblikk i hva applikasjonen gjør og hvordan den fungerer. 1.1 Bruk av applikasjonen Anbefalte nettlesere for bruk av applikasjonen er Google Chrome (alle OS) og Safari for iphone. Windows Phone sin Internet Explorer fungerer også. Vi har opplevd at Firefox er noe mindre responsiv, men fortsatt fullt brukelig Innloggingsskjerm Det første skjermbildet en bruker møter er en innloggingsskjerm som vist på figur 1.1. Denne er veldig enkel, og tilbyr brukeren å taste inn et brukernavn og et passord. En bruker har muligheten til å endre språk til engelsk ved innloggingsskjermen. Ved førstegangsbruk vil applikasjonen lastes inn på norsk. I dette tilfelle kan man trykke på det britiske flagget øverst i høyre hjørne for å endre språk til engelsk. Omvendt kan man trykke på det norske flagget for å endre språket til norsk. Figur 1.2 viser innloggingsskjermen på engelsk og hvor man må trykke for å endre språk til norsk. 5

7 Figur Innloggingsskjermen Figur 1.2 Innloggingsskjerm engelsk Hjem Bruker blir sendt videre til hjemskjermen hvis korrekt brukernavn og passord er tastet inn. Her vil bruker kunne se en liste over innkommende ordre. Hver ordre er beskrevet med et ordrenummer, status på ordre og en leveringsadresse. Ved å trykke på Detaljer knappen kan bruker se en mer detaljert beskrivelse av sin ordre. Man kan også trykke på boksen som vist på figur 1.3. Hvis bruker ønsker å spore sin ordre gjøres det ved å trykke på Se på kart knappen. 6

8 Figur 1.3 Hjemskjermen. Hver ordre ligger i en boks. Boksen er klikkbar og sender deg videre til Detaljer Detaljer Bildet under viser skjermbildet for Detaljer. Her vises en mer detaljert oversikt over en ordre med blant annet ordrelinjer. Ønsker bruker å gå tilbake til hjem-skjermen, kan man trykke på tilbakeknappen øverst til venstre som vist på figur 1.4, tilbakeknappen til en browser eller en fysisk tilbakeknapp på din mobiltelefon. 7

9 Figur 1.4 Detaljer. Rød pil viser tilbakeknappen Se på kart Bildet under viser skjermbildet for Se på kart. Kartet har to markører. Den rød, runde sirkelen med en oransje dott i sentrum illustrerer befrakteren, mens det røde flagget illustrerer leveringsposisjonen til ordren. Ved å klikke på disse markørene kan man få en liten detaljert oversikt over enten bortfrakter eller leveringsadresse, som vist på figur 1.6. Har en bruker gått seg vill i kartet kan man trykke på knappen øverst i høyre hjørne for å zoome tilbake til der man startet. Figur 1.5 illustrerer dette. For å gå tilbake til hjemskjermen trykker man på tilbakeknappen øverst til venstre, tilbakeknappen til en browser eller en fysisk tilbakeknapp på din mobiltelefon. 8

10 Figur 1.5 Kart. Rød pil viser knappen som tar deg med tilbake til start om du har gått deg vill. Figur 1.6 Popupvinduet som dukker opp hvis en markør trykkes på Meny Øverst i venstre hjørne i hjemskjermen er det en menyknapp. Klikker man på denne dukker det opp en meny med fire knapper. Hver av knappene vil navigere deg til det emnet som trykkes på. Legg merke til at man ikke kan klikke på det emnet man allerede er i. 9

11 Figur Den rød pil viser hvor menyknappen ligger. Figur 1.8 Et skjermbilde av menyen Profil Ved å trykke på Profil i menyen blir man sendt videre til profilskjermen, som vist på figur 1.9. Her kan bruker se flåtenummeret og kundenummeret til innlogget bruker. I profilen kan bruker endre språk om det er ønskelig. Legg merke til at knappen for det språket som brukes ikke kan klikkes på. 10

12 Figur 1.9 Profil. Det norske flagget ved språk illustrerer at språket norsk er valgt og kan ikke klikkes på Informasjon Ved å trykke på Om i menyen navigeres man til om-skjermen. Her kan bruker lese litt om applikasjonen, om EWOS, eller om Goodtech. Som standard åpnes Om EWOS fanen. 11

13 Figur 1.10 Om EWOS Figur 1.11 Om applikasjonen. En kan trykke på en av de to røde pilene for å lese om ønsket emne Logg ut Hvis bruker ønsker å logge ut kan bruker trykke på Logg ut i menyen. 1.2 Feilmeldinger Fire mulige feil kan oppstå ved bruk av applikasjonen. Den første er når bruker ikke får tilgang til applikasjonen. Dette kan skyldes at serveren hvor applikasjonen ligger nede. Ved en slik tilfelle må bruker vente til serveren er oppe og går igjen. Dersom bruker har glemt å fylle inn et felt, eller om en bruker har skrevet inn feil informasjon, vil det dukke opp en rød tekst hvor det står Feil brukernavn eller passord!, som vist på figur Sørg for å fylle inn nødvendige felter med korrekt informasjon. 12

14 Ved noen tilfeller kan informasjon du skriver inn være riktig, men likevel ikke få logget inn. Det skyldes at serveren applikasjonen kommuniserer med er ute av drift. Utviklerne får beskjed om dette fortløpende. Figur 1.12 Feilmelding ved ugyldig informasjon Figur 1.13 Feilmelding hvis server er nede Den fjerde feilmeldingen bruker kan få er illustrert i figur En slik feil skyldes logikk-feil i programkoden. Når feilen oppstår, rapporteres det til utviklerne øyeblikkelig, og bruker må vente tålmodig til feilen blir rettet på. 13

15 Figur 1.14 Errorview som vises når en uventet feil oppstår 2 Kodestandard og verktøy For at applikasjonen skal være enklest mulig å videreutvikle og drifte for Goodtech sine ansatte, ønsket de at vi fulgte deres standarder for Java-koding. Standarden Goodtech følger er hovedsakelig Geosoft sine standarder. Goodtech sin standard har implementert kun noen få avvik fra Geosoft sin standard. Dette gjelder blant annet for kommentarer som skal skrives på norsk. Det vil også si at all javadoc skal skrives på norsk. Hovedspråket som ble brukt under utvikling av FôrIt CDS er Java 7. Som et rammeverk rundt Java har gruppen brukt Vaadin Touchkit som er et webrammeverk som gjør koding av 14

16 webapplikasjoner for mobile enheter lettere. Når prosjektet skal kompileres blir det brukt byggeverktøyet Maven for å kompilere prosjektet. Maven er et rammeverk som kompilerer og bygger applikasjoner. Editeringsverktøy brukt for å skrive kode er Eclipse. Gruppen valgt Eclipse fordi det støtter de fleste filformater og det var det verktøyet gruppen var kjent med fra før. 3 Applikasjonens funksjoner Kapittelet utdyper nærmere om hva applikasjonen kan gjøre. Funksjonene blir beskrevet med få tekniske begreper slik at de fleste lesere uten IT-kunnskap kan henge med. Etter å ha lest dette kapittelet vil leseren ha fått en oversikt over hovedfunksjonene til FôrIt CDS. 3.1 Innlogging Når en bruker går inn på webapplikasjonen for første gang kommer kunden til innloggingsskjermen (figur 1.1). Her vil brukeren får se to tekstfelter, en for brukernavn og en for passord. Det vil også være en knapp for å kunne logge seg inn. Når en skriver inn brukernavn og passord kan en trykke enter eller trykke på knappen for å logge seg inn. Er brukernavnet og passordet godkjent vil en bli sendt videre til hjemskjermen, hvis ikke vil brukeren få en enkel tilbakemelding om at det var feil brukernavn eller passord (2.12). Ved ugyldig innsending av brukernavn og passord, vil passordfeltet bli blanket ut og brukernavnfeltet bli satt i fokus. Siden de fleste browsere støtter lagring av forms for vanlige HTML-sider vil også brukeren få valget om å kunne lagre brukernavnet og passordet i browseren. Dette gjør at en slipper å skrive inn brukernavn og passord hver gang en skal sjekke applikasjonen. Brukernavnet og passordet vil kunden få tilsendt av EWOS. Derfor er det heller ikke nødvendig å ha noen registreringsfunksjon innebygget i applikasjonen. 3.2 Hurtigvisning av alle ordrene Etter at brukeren har fått logget inn vil brukeren som sagt bli videresendt til hjemskjermen. Her vil en kunne se alle de bestilte ordrene i et enkelt oppsett hvor hver ordre har en slags bolk med den viktigste informasjonen (figur 1.3). Dette vil typisk være en status for om den 15

17 er registrert, om den laster eller om ordren er på vei. En vil også få vite estimert ankomsttid til leveringsadressen. Hver bolk har også to knapper. Den ene knappen sender det til en side med kart hvor en kan spore ordren på et kart. Den andre fører videre til en side med flere detaljer for den spesifike ordren. 3.3 Detaljer for hver ordre Denne siden viser hovedsakelig all nyttig informasjon om en ordre. Det vil si at når en trykker seg videre ved hjelp av detaljknappen på en av bolkene på hjemskjermen vil en komme hit (figur 1.4). Brukeren får vite hvilken befrakter som skal frakte ordren, hvor den skal leveres og hvilken status ordren har. Avhengig av om ordren har status registrert, lastet eller på vei, får en også et relevant tidspunkt. Dette kan enten være forventet avgang eller forventet ankomst. Under hovedinformasjonen for ordren kan en finne ordrelinjene. Dette er informasjon om hvilke varer som gjelder for den ordren, hvor mye som er bestilt av den varen. Hvis ordren ikke har blitt lastet enda vises det også hva som er planlagt å bli lastet for den varen. Hvis ordren har blitt lastet ombord på befrakteren vises hvor mye som ble faktisk ble lastet av den varen. Siden befrakterne ikke alltid har plass eller har for mye plass får ikke kunden alltid den mengden av fôr som er bestilt. Under alle ordrelinjene vil en også få en sum som gjelder for hele ordren. 3.4 Sporing av hver ordre på kart Når en har trykket på kartknappen for en av ordrene på hjemskjermen vil en videresendes til en side med kart (figur 1.5). På kartet vil en kunne se hvor befrakteren med ordren befinner seg akkurat nå. Det vises også et annet punkt for leveringsadressen til brukeren. I det en laster siden vil kartet vil automatisk fokusere inn slik at de to punktene blir godt synlig på skjermen. Brukeren har også ha en knapp øverst i høyre hjørne for å kunne manuelt fokusere inn til de to punktene hvis en har scrollet eller zoomet seg ut av fokus. Ved et klikk på en av punktene vil en informasjonsboks poppe opp med informasjon om enten leveringsadressen eller om befrakteren. 16

18 3.5 Bytte språk Brukeren har også mulighet for å endre språket mellom norsk og engelsk i applikasjonen. Dette kan gjøres på innloggings- og profilvinduet. I innloggingsskjermen kan en trykke på flagget øverst i høyre hjørne. Språket vil endres til det flagget en trykket på. Det vil si at hvis det er et engelsk flagg som vises, bytter en fra norsk til engelsk ved å trykke på det. Under profilvinduet kan en se under innstillinger en mulighet for å velge det språket som ikke er valgt fra før (figur 1.9). Språkvalget vil bli husket til neste gang brukeren kommer til applikasjonen med den samme browseren. 3.6 Informasjon om EWOS, Goodtech og applikasjonen Webapplikasjonen har også et eget vindu for å vise statisk informasjon om bedriftene EWOS og Goodtech, samt litt generelt om applikasjonen. 3.7 Logge ut Brukeren har også mulighet til å logge ut ved å trykke logg ut i menyen. 4 Programmets oppbygning I denne seksjonen skal vi se nærmere på hvordan applikasjonen er bygd opp. 4.1 Moduler Siden FôrIt CDS er delt opp i flere moduler med forskjellige funksjoner. Hver modul inneholder en del av funksjonen til applikasjonen. For eksempel gir det oss muligheten å legge webservicen på et annet sted enn på klientlaget. Dette gir større sikkerhet og et mer fleksibelt sluttprodukt. 17

19 Figur 4.1 Viser modulene i programmet 4.2 Parent Modulen som er en samlet modul av alle de andre modulene for FôrIt CDS. 4.3 Server Modulen som inneholder programkode for webservicen. Bruker modellen fra modulen Common til å lage nyttige Java-objekter. 4.4 Common En modul som har tre klasser som definerer en modell på det som hentes fra databasen. 4.5 Client Modulen inneholder brukergrensesnittet, logikken for å hente data fra webservice og objektdefinisjoner for en bruker, ordre, ordrelinje og en befrakter. Alle ressurser som blir brukt av brukeren (alt fra bilder, ikoner og stilark) lagres også under denne modulen. Den inneholder også alle enhetstestene for klientdelen. 18

20 4.6 Standalone Det finnes to standalonemoduler. Den ene modulen som kalles kun Standalone lager en jarfil for klientdelen ved kompilering av parent-modulen. Jar-filen kan legges rett på serveren og applikasjonen kan kjøres. Den andre standalonemodulen kalles Standalone-server og gjør det samme for webservicedelen av applikasjonen. 5 Hovedoppbygning Figur 5.1 Hovedoppbygning på hvordan applikasjonen er satt opp. 19

21 5.1 Database Databasen som FôrIt CDS baserer seg på er den samme som den ikke-mobile løsningen bruker. Siden denne databasen er svært stor og innviklet i forhold til hva som er nyttig informasjon for mobilapplikasjonen blir bare små deler av denne databasen brukt. Databasen bruker standard SQL-spørringer for å hente data. Per dags dato er det ikke mulighet for mobilapplikasjonen å skrive til database, altså er kun lesing tillatt. 5.2 Webservice Webservicen er laget mellom klienten og databasen. Webservicen som blir brukt er av typen REST. REST står for Representational State Transfer og er en type standard for å kode webservicer. Webservicen henter data fra databasen med tre ferdiglagde sprørringer. De tre spørringene henter følgende: De siste ordrene for en kunde Alle salgsdetaljer for en bestemt ordre Alle befraktere Webservicen krever en innlogging før en kan hente data fra databasen. Dette gjøres når brukeren logger seg inn i applikasjonen. Dataen som returneres fra webservicen blir sendt som JSON-arrays og JSON-objekter. 5.3 Klient Klientdelen er den delen av applikasjonen som kjører lokalt i brukeren sin browser. Den viser views, tar imot brukerinput og bestemmer hva som skal skje med den inputen. Trykker brukeren på en knapp, registreres dette og koden til lytteren for knappen utføres. Når brukeren logger seg inn, kobler klientdelen seg på webservicen og henter JSON-objektene, konverterer JSON-objektene til definerte Java-objekter og sender nyttig informasjon ut til brukeren. Klientdelen av applikasjonen kontrollerer også session- og cookie-bruken ved pålogging, utlogging og valg av språk. Hovedoppgavene til klientdelen: Vise views 20

22 Ta imot brukerinput Hente JSON-objekter fra webservice Konvertere JSON-objektene fra webservice til Java-objekter Vise relevant informasjon basert på Java-objektene 5.4 Servere Prosjektet vil til slutt ligge på EWOS sine servere sammen med den eksisterende skrivebordsløsningen for FôrIt. Applikasjonen vil ta opp to porter, en for klientdelen og en for webservicen. Databasen eksisterer allerede på fungerende servere. Per dags dato har applikasjonen blitt testet i et testmiljø hos Goodtech sine interne servere som inneholder en liten kopi av EWOS sine databaser satt opp med webservicen og klientdelen. Mer om testing kommer under Testrapporten. 6 Klasseforklaringer Vi skal nå ta for oss klasseoppsettet for hovedmodulen, Client, som vi har jobbet med. Klasseoppsettet i modulen er bygget opp på MVC-prinsippet, Model View Controller. Dette prinsippet baserer seg på Views (skjermer) som er separert fra Model (modellen) med en Controller (kontroller). Pakkene er delt inn i følgende struktur: no.goodtech.foritcds.client no.goodtech.foritcds.client.model no.goodtech.foritcds.client.ui no.goodtech.foritcds.client.ui.language no.goodtech.foritcds.client.components no.goodtech.foritcds.client.util Navngivningen av pakkene følger standard navngivning for Java-program for bedrifter. Dette vil si: <domenenavn>.<bedrift>.<modul>.<pakkenavn> 21

23 Figur 6.1 Oversikt over hvordan pakkene er satt opp. 6.1 Hovedklasser Vi har en hovedklasse i Client-modulen. Den kalles ForitCDSUI og er en slags overklasse for applikasjonen. Den generer og bytter Views, holder kontroll på hvilken URL som blir vist i adressebaren og den setter hvilken CSS-style som gjelder. ForitCDSUI inneholder derfor et objekt av NavigationManager som bestemmer hvilket vindu som vises til enhver tid. Den holder også alle standarder for modulen. Som for eksempel bestemmer den standarder for datoformat, hvilket tekstformat som gjelder, applikasjonsnavn og sessionnavn. Vi følger det Språkrådets standard for visning av datoer: DD.MM.YYY. Klassen inneholder også et objekt av typen DefaultErrorHandler som finnes i Vaadin sine pakker. Dette objekter bestemmer hva som skal skje når en uventet RuntimeException oppstår. Mer om feilhåndtering kommer under kapittel 8 Feilhåndtering og logging. 22

24 6.2 Modellklasser Figur 6.2 Sammensetningen av modellene og relasjonene mellom de. Modellklassene ligger under pakken model, og er et oppsett på hvordan applikasjonen deler opp dataen fra webservice og legger det ryddig i objekter. Klassene inneholder stort sett datasett som definerer objektet og get- og set-metoder. Modellklasser er følgende klasser: Fleet Freighter Order SalesDetails public class Freighter { private List<Order> orders; private int freighterid; private int factoryid; private String freightername; private String freighterno; private double longitude; private double latitude; public void setfreighterid(int freighterid) { 23

25 this.freighterid = freighterid; public int getfreighterid() { return freighterid;... Figur 6.3 Eksempel på hvordan en modellklasse ser ut. Fleet er modellen på hva en flåte skal være. En flåte er det som definerer en bruker. Det viktigste for denne klassen er selvfølgelig en id og et passord, som blir brukt for å logge inn. Den inneholder også en liste med ordre, kundenummer og et leveringsnavn. Freighter er en modell for hva objektet befrakter inneholder. Objektet inneholder listen med ordre som befinner seg på skipet. Det har også to variable med datatyper som double som definerer latitude og longitude for hvor befrakteren befinner seg i verden. For å identifisere hver befrakter kalles det på hvilken fabrikkid den tilhører, samt hvilken id den selve befrakteren har. Klassen har også mindre viktige variabler som et nummer og navn. Order er datatypen for hver ordre. Den inneholder en liste av ordrelinjer (salesdetails). Hver ordre er koblet opp mot en flåte og en befrakter. Order har derfor en flåteid og befrakterid. Order bruker også latitud og longitude på samme måte som Freighter-klassen. For å identifisere hver ordre har den også en egen id. Andre data som definerer klassen er: Ordrenummer Flåtenummer En status som forteller hvilken tilstand ordren er i (registrert, laster eller på vei). Tre heltallsvariable for bestilt mengde, det som er planlagt å bli lastet ombord på befrakteren og hvor mye som faktisk ble lastet ombord. En dato for estimert ankomst Leveringsadresse 24

26 En dato for planlagt avgang for ordren En dato for når ordren ble ferdig lastet ombord på befrakteren Et leveranseadressenummer og et leveranseadressenavn SalesDetails er definisjonen på en ordrelinje. Hver ordre kan ha mange ordrelinjer. Hver ordrelinje består av en id, en varebeskrivelse, mengden som er bestilt, planlagt og faktisk lastet av varen. 6.3 Views og components Alle views som lages extender det som Vaadin kaller NavigationView. Det lager et vindu med en banner på toppen av skjermen og et område hvor du kan legge komponenter med forskjellige utforminger. En annen ting som er felles for alle views er en variabel som er av typen WSBusinessLogic. Dette gir muligheten for hvert view å koble seg til webservice og hente data fra databasen, for deretter å skrive dataen ut på skjermen. Hvis det oppstår en uventet feil er det kritisk at feilen logges slik at driftere vil kunne rette på feilen. Hver vindusklasse har derfor også en logge-variabel som skriver den uventede feilen til en loggfil. Mer om logging kommer under kapittel 8 Feilhåndtering og logging. Hvis feilen er så kritisk at applikasjonen ikke kan kjøre videre, blir brukeren omdirigert til et ErrorView (se figur 1.14) som er en statisk side som logger feilen og viser kunden at et problem har oppstått. Ressurser som bilder og ikoner hentes ved hjelp av ThemeResource. Flere av komponentene som legges til i vinduene er endret på i forhold til hva som er standardkomponenter fra Vaadin. Derfor har vi pakken som heter components. Den inneholder ForitMap som henter tiles til kartet fra MapBox. ForitMap bytter også kart mellom dagmodus og nattmodus for å gjøre kartet mer synlig for brukere som bruker applikasjonen utendørs. Pakken inneholder også to klasser som redefinerer menyknappen som viser og gjemmer menyen, og selve menypanelet som kommer opp ved trykk på menyknappen. Menyknappen inneholder en Animator som gir menypanelet en fin innrulling ved åpning av panelet. Siden Vaadin sin Touchkit-pakke ikke fullt ut støtter Windows Phone 8 sin standardbrowser, har knappen også en test som gjør at menyen også fungerer for de som bruker Windows Phone. 25

27 6.4 Kobling til webservice Mellom alle views og webservicen har vi to klasser. Vi har en klasse som heter WSBusinessLogic som er en slags Controller hvis en ser på MVC-modellen. Den henter data fra den andre klassen, WebServiceConverter, som er koblepunktet til webservicen. Alle views kobles til WSBusinessLogic som videre kobles til WebSreviceConverter som kobler seg på webservice ved gyldig påloggingsinformasjon. WSBusinessLogic blir derfor et slags mellomledd mellom views og logikk, og kan tolkes som en controller i designmønsteret MVC. Tilkoblingsklassen WebserviceConverter tar ved innlogging imot brukernavnet og passordet og logger på webservice hvis informasjonen er gyldig. Etter en gyldig pålogging kan det hentes informasjon til views fra webservice sine tre URL-tilkoblinger. JSONobjektene som blir hentet fra webservice blir konvertert til objekter fra modellklassene, og videre blir dataen brukt til å bli skrevet ut til views. 6.5 Andre Av andre klasser har vi de tre språkklassene som ligger i pakken ui.language. Her er det en hovedklasse som inneholder navn på alle språklabels. Pakken har også to klasser som inneholder språkforskjellene i en lik array. Når et view har en komponent som krever en språkendring kalles den spesifike varibelen fra denne hovedklassen, og henter riktig tekst fra en av de to språkklassene. Disse tre klassene kalles ForitBundle (hovedklassen), ForitBundle_no (norsk språkklasse) og ForitBundle_en (engelsk språkklasse). Det ligger også en språklogikklasse under pakken util som kalles LanguageLogic. Denne holder kontroll på hvilket språk som er valgt til enhver tid. Dette gjøres ved sletting, lagring og oppdatering av cookies for en string som enten er NO eller US. Ved eventuelle nye språk vil det bare være å legge til en ny språkklasse med riktig tekst på variablene, og så legge til riktig språkidentitetsstring under LanguageLogic. 26

28 7 Teknisk beskrivelse av applikasjon Kapittelet går inn i applikasjonens funksjoner og beskriver hvordan disse er bygget opp ved hjelp av kodeeksempler og figurer. Leser burde ha kompetanse innen IT og systemutvikling, og ha god kjennskap til Java. 7.1 Innloggingsfunksjon Innloggingsfunksjonen på LoginView starter med et objekt av typen LoginForm. Denne klassen genererer en HTML-formtagg for å kunne logg inn på en sikker måte. Den lager to tekstfelter for brukernavn og passord og en submit-knapp for å klikke Logg inn. En kan enten logge inn ved å trykke enter på tastaturet eller ved å klikke på logg inn knappen. Klikkfunksjonaliteten er implementert ved å legge til en lytter til LoginForm-objektet. loginform.addlistener(new LoginListener() { public void onlogin(loginevent event) { String username = event.getloginparameter("username"); String password = event.getloginparameter("password"); boolean isvalid = false, error = false; if (!username.equals("") &&!password.equals("")) { try { isvalid = bll.login(username, password); catch (Exception ex) { error = true; errorlabel.setcaption("får ikke koblet til server. Prøv på nytt senere."); LOGGER.error("Får ikke kontakt med webservice: ", ex); if (isvalid) { // Går til HomeView eller error bll.setview(new HomeView()); else if (error == false) { errorlabel.setcaption(bll.getbundle().getstring(foritbundle.loginerrorlabel)); 27

29 ); Figur 7.1 Et eksempel på lytteren som er lagt til for å logge inn. I lytteren blir brukernavnet og passordet sendt videre til kontrolleren som sender dataen videre til WebserviceConverteren som spør webservice om dette er gyldig påloggingsinformasjon. Ved gyldig informasjon setter kontrolleren en session og videresender brukeren til HomeView Sessions En session Vaadin bruker VaadinService sin innebyggede metode for å kontrollere sessions. Dette brukes når brukeren logges inn eller ut. Her er et eksempel på hvordan session settes når brukeren henholdsvis logger inn og ut: VaadinService.getCurrentRequest().getWrappedSession().setAttribute(ForItCDSUI._SESSIONNAME, user); VaadinService.getCurrentRequest().getWrappedSession().setAttribute(ForItCDSUI._SESSIONNAME, null); 7.2 Views og komponenter Alle views i FôrIt CDS blir satt opp på samme måte. De bygger på Vaadins objekt kalt NavigationView. Denne klassen oppretter en banner og et tomt område under for alt innhold. Hvert NavigationView har mulighet for å legge til en overskrift i banneren ved å sette en caption. Alle komponenter som vi legger til i skjermene, som for eksempel Labels og Buttons, blir lagt til i forskjellige typer Layouts. Hver skjerm har en hovedlayout av typen VerticalComponentGroup for alt innhold. Det er denne layouten som skaper den fine margen for innholdet i hvert view. Andre typer layouts som blir brukt er: VerticalLayout legger komponenter nedover i rekkefølgen en legger de til HorizontalLayout legger komponenter bortover i rekkefølgen en legger de til 28

30 GridLayout en slags tabell hvor en bestemmer komponentenes posisjon med koordinater Her er et eksempel på hvordan komponenter blir lagt til i layoutene: VerticalLayout eachorderlayout = new VerticalLayout(); Label ordernolabel = new Label(bll.getBundle().getString(ForitBundle.homeOrderId) + printorder.getorderno()); eachorderlayout.addcomponent(ordernolabel); Figur 7.2 Eksempel på VerticalLayout. HorizontalLayout og VerticalComponentGroup fungerer på helt lik måte. int size = 0; if (orderlines!= null) size = orderlines.size(); // Lager GridLayout med størrelse 3, size+2 final GridLayout grid = new GridLayout(3, size + 2); //Legger til en Label i posisjon 0,0 i GridLayouten Label articleheader = new Label(bll.getBundle().getString(ForitBundle.orderdetailsTableArticle)); articleheader.setstylename(gridheader_style); grid.addcomponent(articleheader, 0, 0); grid.setcomponentalignment(articleheader, Alignment.MIDDLE_CENTER); Figur 7.3 Eksempel på GridLayout Accordion Applikasjonen har også et informasjonsview (AboutView) som inneholder en komponent som kalles Accordion. En Accordion viser sammenleggbare faner med informasjon, og de er svært effektive for å vise en større mengde data på en skjerm med små dimensjoner. En Accordion blir satt opp med flere Tabs som inneholder den informasjonen som skal vises for den fanen. Accordions fungerer som et trekkspill hvor en bare kan se informasjonen i en fane om gangen. Her er et eksempel på hvordan en tab blir lagt til: // Accordion er området som inneholder de ulike Verticallayoutene. Accordion accordion = new Accordion(); final VerticalLayout aboutewoslayout = new VerticalLayout(); aboutewoslayout.setid("aboutewoslayout"); 29

31 Image EWOSimage = new Image(null, EWOS_logo); aboutewoslayout.addcomponent(ewosimage); aboutewoslabel = new Label(bll.getBundle().getString(ForitBundle.aboutEWOSInformation)); aboutewoslayout.addcomponent(aboutewoslabel); // Legger til VerticalLayout til en Tab som legges til i Accordion. // arrow_up er et ikon på om den tabben er valgt eller ikke. Tab aboutewostab = accordion.addtab(aboutewoslayout,bll.getbundle().getstring(foritbundle.aboutewos), arrow_up); Lyttere Alle mulige aksjoner brukeren kan utføre krever lyttere. Noen av komponentene har allerede innebygget lyttere. Dette gjelder blant annet tekstfelter og større views med scrolling. For alle andre komponenter som skal være klikkbare kreves det lyttere. Her er et eksempel på hvordan en knapp fra HomeView får lagt til en Listener som lytter etter når brukeren klikker på den: mapbutton.addclicklistener(new ClickListener() public void buttonclick(clickevent event) { bll.setview(new MapView(printOrder)); ); Visning av bilder og ikoner For å gjøre applikasjonen mer intuitiv, penere og få vist all informasjon vi ønsker kreves det en form for visning av bilder og ikoner. Alle bilder og ikoner blir hentet fra av en Resourcemappe som ligger under Client-modulen. De blir hentet ved hjelp av ThemeResource. Dette er en Vaadin-komponent som henter riktig resurs fra Resource-mappen ved hjelp av filplasseringen til bildet. Her er et eksempel på hvordan filer hentes fra mappen images under ressursmappen: EWOS_logo = new ThemeResource("images/EWOS_logo.jpg"); goodtech_logo = new ThemeResource("images/goodtech_logo.png"); 30

32 Bilder blir lagt til ved hjelp av Vaadins Image-objekt. Image-objektet tar imot ThemeResource-objektet og så er det bare å legge til bildet som hvilken som helst annen komponent. Ikoner blir bare lagt til med Vaadin-komponentenes innebyggede funksjon som støtter ikoner inne i hver komponent. // Legger til bilde final VerticalLayout aboutewoslayout = new VerticalLayout(); aboutewoslayout.setid("aboutewoslayout"); Image EWOSimage = new Image(null, EWOS_logo); aboutewoslayout.addcomponent(ewosimage); // Legger til ikon til en knapp private final ThemeResource homeresource = new ThemeResource("images/menu_home.png"); homenavbutton.seticon(homeresource); Figur 7.4 Viser hvordan et bilde blir lagt til i en VerticalLayout og hvordan et ikon blir lagt til i en knapp på menyen CSS Siden alle views blir generert til HTML-kode er de designet med et stilark av typen Cascading Style Sheet. Dette blir lagt til for applikasjonen i klassen ForitCDSUI public class ForItCDSUI extends UI {... Hver komponent som bli lagt til i vinduene kan få en egen styling-id. Dette gjør det enklere å definere et eget design for alle komponenter som bli lagt til. Vaadin genererer også klassenavn på alt som befinner seg i vinduene. Dette gjør at det er bare å kalle på den riktige delen av vinduet du vil endre på og style den slik det etter egen vilje. Her er et utdrag fra HTML-koden som blir generert fra HomeView. <div class="v-touchkit-componentgroup-row v-touchkit-componentgroup-row-nocap"> <div class="v-caption"></div><div class="v-touchkit-componentgroup-cell"> 31

33 <div class="v-label v-widget v-has-width" id="homeinformationlabel" style="width: 100%;">Du har 2 innkommende ordre.</div> </div> </div> Figur 7.5 Koden viser øverste del av innholdet i HomeView som beskriver hvor mange innkommende ordre brukeren har. #homeinformationlabel { text-align: center; Figur 7.6 Dette er den veldig simple CSS-koden som tilhører den tekstbiten. De kobles sammen med iden homeinformationlabel. 7.3 Kommunikasjon med webservice Klassen WebserviceConverter har som hovedoppgave å snakke med webservice og hente data når det er behov for det. Webservicen er av typen REST og er laget på den måten at en må logge inn med gyldig påloggingsinformasjon for så å kunne hente den dataen en ønsker fra tre forskjellige URL. Når en åpner en av URLene i nettleseren etter en godkjent innloggning får en resultatet av den spørringen som URLen representerer. Dataen som kommer fra webservicen er av typen JSON-arrays. Dette er JSON-objekter satt sammen i en array. Dataen som blir hentet gjelder for den flåten som er logget inn. Selve koblingen til webservice skjer hjelp av en hjelpe-metode kalt readjsonarrayfromurl. Denne oppretter en BufferedReader, åpner URLen til webservice og henter JSON-teksten. Teksten blir så konvertert til en JSON-array og deretter returnert som objektet JSONArray. public JSONArray readjsonfromurl(string url) throws Exception { InputStream is = new URL(url).openStream(); try { BufferedReader rd = new BufferedReader(new InputStreamReader(is, Charset.forName(ForItCDSUI._CHARSET))); String jsontext = authenticate(url); JSONArray jsonarray = new JSONArray(jsonText); return jsonarray; catch (Exception e) { throw new Exception(); 32

34 finally { is.close(); Figur 7.7 Eksempel på hvordan en JSONArray blir opprettet ved lesing fra webservcice. Den tar i mot URLen og leser teksten for den URLen. Teksten blir så konvertert til JSONArray og returnerert. Klassen har også metoder for å kunne logge seg på webservice og applikasjonen. Denne metoden kalles login og tar imot et brukernavn og et passord som senere blir kryptert i metoden. Metoden returnerer et Fleet-objekt fra modellen vår. Er flåteobjektet lik null er ikke passordet eller brukernavnet godkjent. Godkjennelsen vurderes ut ifra responsen metoden får fra webservice. Ved hjelp av denne if-testen testes det på om responsen er 200, altså godkjent: HttpURLConnection urlconnection; urlconnection = (HttpURLConnection) url.openconnection(); urlconnection.setrequestproperty("authorization", "Basic " + encodeduserpassword); if (urlconnection.getresponsecode()!= 200) return null; Link fra ressursfil For å gjøre applikasjonen enkel å installere på EWOS sine systemer brukes det en ressursfil med filformatet xml. Xml-filen inneholder kun en statisk URL som er adressen til webservicen. Ved installering på nye servere må denne URLen endres for å få koblet på webservicen. <?xml version="1.0"?> <URL> Figur 7.8 Eksempel på hvordan XML-filen kan se ut. Metoden readwebserviceurl tar seg av lesingen av denne URLen. Dette gjøres slik: public void readwebserviceurl() throws Exception { if (ForItCDSUI._BASEPATH!= null && ForItCDSUI._BASEPATH.length() > 0) { // Lokaliserer filen 33

35 String path = ForItCDSUI._BASEPATH + "/resources/webserviceconnection.xml"; File file = new File(path); DocumentBuilder dbuilder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); Document doc = dbuilder.parse(file); webserviceurl = doc.getdocumentelement().gettextcontent(); Konvertering til Java objekter I WebserviceConverter finnes det tre hovedmetoder som henter arrays fra hjelpe-metoden readjsonfromurl. Metodene konverterer alle JSON-objektene over til relevante objekter fra modell-pakken og returnerer de som en liste eller et objekt. Disse metodene er: public List<Order> getorderslist(int locationid) Henter en liste med ordre basert på den flåten som er logget inn. Metoden får flåtens lokasjonsid inn som parameter og returnerer en liste med objektet Order fra modellen vår. public List<SalesDetails> getsalesdetailslist(order order) Henter en liste med ordrelinjer for den ordren som blir sendt som parameter. Den returnerer en liste med objektet SalesDetails fra modellen vår. public Freighter getfreighter(int freighterid, int factoryid) Siden denne metoden kun trenger et objekt leses det bare et JSON-objekt fra webservice her. Hver freighter er identifisert på en befrakterid og en fabrikkid. Disse variablene sendes inn som parametere. Metoden returnerer et Freighter-objekt fra modellen vår. public Freighter getfreighter(int freighterid, int factoryid) throws Exception { Freighter freighter; JSONObject jsonfreighterobject; try { jsonfreighterobject = readjsonobjectfromurl(webserviceurl + "freighter/" + freighterid + "/v1?factoryid=" + factoryid); freighter = new Freighter(); 34

36 freighter.setfactoryid(jsonfreighterobject.getint("factoryid")); freighter.setfreighterid(jsonfreighterobject.getint("id")); freighter.setfreighterno(jsonfreighterobject.getstring("freighterno")); freighter.setlatitude(jsonfreighterobject.getdouble("latitude")); freighter.setlongitude(jsonfreighterobject.getdouble("longitude")); freighter.setname(jsonfreighterobject.getstring("name")); return freighter; catch (Exception e) { throw new Exception(); Figur 7.9 Metoden getfreighter() som henter et JSONObject og returnerer et Freighter-objekt fra modellpakken. 7.4 Kart Kartet som blir brukt i applikasjonen er av typen LMap. LMap er et objekt fra en dependency som finnes under Goodtech sin samling av Vaadin-framework. Objektet er hentet fra Vaadin sin leaflet-pakke som befinner seg under addon-mappen til Vaadin. Leaflet er et opensourceprosjekt som fokuserer på mobile kartløsninger. Objektet kommer med innebygde funksjoner for å behandle kart på mobile løsninger. // Fjerner alle kontroller til kartet som vi ikke ønsker å vise i kartet getlayerscontrol().remove(); // Oppdaterer punkter på kartet if (freighterpos!= null) map.removecomponent(freighterpos); if (deliverypos!= null) map.removecomponent(deliverypos); addlocations(); Figur 7.10 Eksempel på funksjoner som følger med LMap-objektet FôrIt CDS har klassen ForItMap under components-pakken for å opprette kartet og de ønskede funksjonene. Denne klassen extender objektet LMap og får automatisk alle 35

37 funksjoner som Leaflet tilbyr. LMap krever tiles for å få vist noe som helst. Dette er en sammensetning av utrolig mange bilder satt opp i en mappestruktur med koordinater og zomm-nivå. Siden lokale tile-sett kan bli utrolig store hentes de foreløpig fra MapBox. FôrIt CDS har også en funksjon som sjekker hva klokken er, og hvis den er mer enn klokken 20:00 vil kartet bytte tile-sett til et annet sett med mørkere farger. Klokken 06:00 igjen vil kartet bytte til normale lyse farger. Dette vil gjøre applikasjonen mer brukervennlig i og med at mange kommer til å bruke den ute i dårlig lys. if (mode.equals(_nightmode)) { tilelayer = new LTileLayer( " else { tilelayer = new LTileLayer( " addbaselayer(tilelayer, null); Figur 7.11 Eksempel på hvordan tiles bli hentet fra mapbox og lagt til i LMap-objektet. 7.5 Språk Applikasjonen har også en løsning for å kunne bytte språk fra norsk til engelsk. Dette ble implementert på grunn av mulige nye kunder i utlandet for EWOS og Goodtech. Språklogikken i applikasjonen bestemmes av en cookie. Hvis cookien ikke er satt blir det satt en nye en til standardspråket norsk. Cookien er av Vaadin sin egendefinerte måte for å behandle cookies på som er ved hjelp av VaadinService sine metoder. Dette behandles i LanguageLogic-klassen i util-pakken. private Cookie getcookie(string name) { Cookie[] cookies = VaadinService.getCurrentRequest().getCookies(); for (Cookie cookie : cookies) { if (name.equals(cookie.getname())) { return cookie; return null; 36

38 public void destroycookie() { if (languagecookie!= null && country!= null) { languagecookie = new Cookie(cookieLanguageName, country); languagecookie.setmaxage(0); savecookie(); Figur 7.12 Eksempler på hvordan Cookies bli behandlet i applikasjonen. Etter at det bestemte språket har blitt satt henter den riktig data fra en klasse kalt ForitBundle. Denne ligger under ui.language og er en klasse som extender ListResourceBundle. Dette objektet er inneholder funksjoner for å behandle ressurser. Klassen inneholder flere statiske variabler som tilegnes en id. // HomeView public static final String homecaptiontext = generateid(); public static final String homeinformationstringnoorder = generateid(); Figur 7.13 Eksempel på hvordan hver tekstvariabel blir opprettet i ForitBundle Videre kobles det to andre klasser til denne hovedklassen som representerer hvert sitt språkvalg. Dette gjøres med at de extender ForitBundle. Hver av de to klassene inneholder samme type dobbel-array som inneholder hvilken variabel i bundle-klassen den tilhører og setningen i riktig språk som skal hentes. static final Object[][] contents_no = { // HomeView { homecaptiontext, "Velkommen ", { homedeliveryaddress, "Leveringsadresse: ",... Figur 7.14 Eksempel på hvordan teksten lagres under ForitBundle_no. Fungerer helt likt for ForitBundle_en. 37

39 8 Feilhåndtering og logging Applikasjonen har hatt et stort fokus for å gjøre det så lett som mulig for andre aktører knyttet til prosjektet. Det betyr at med god feilhåndtering, logging og tilbakemeldinger vil det være mye enklere å installere, bruke, videreutvikle og drifte webapplikasjonen. 8.1 Feilhåndtering FôrIt CDS bruker Vaadins egendefinerte DefaultErrorHandler for å håndtere uventede RuntimeExceptions. Her har vi et eget objekt av denne klassen i vår hovedklasse, ForitCDSUI. Måten vi bestemmer hva som skal skje hvis det den uventede feilen oppstår er slik: public void error(com.vaadin.server.errorevent event) { LOGGER.error("En feil oppstod: ", event.getthrowable()); setview(new ErrorView("")); ; Denne egendefineringen skriver først feilen med en kort beskrivelse til en loggfil og så videresender den bruker til et ErrorView (se figur 1.14). Dette statiske skjermbildet er bare en side hvor bruker får informasjon om at det har oppstått en uventet feil. Hvis appen kan si noe om feilen får brukeren en kort ikke-teknisk setning om hva som kan være problemet. Applikasjonen har også flere steder hvor vi vet det kan oppstå en feil. Dette håndteres med try/catch-setninger i øverste lag. Det vil si at hvis det oppstår en feil når en prøver å koble seg til webservice (webservicelaget i figur 5.1) vil applikasjonen kaste denne feilen med en Throw helt til feilen kommer til et View hvor bruker kan få en informativ tilbakemelding og feilen kan bli logget. // Kode fra HomView try { userorders = bll.getuserorders(username.getlocationid()); catch (Exception e) { 38

40 userorders = null; LOGGER.error("Får ikke hentet liste med ordre fra webservice.", e); bll.setview(new ErrorView(bll.getBundle().getString(ForitBundle.errorWebServiceOrder))); // Kode fra WSBusinessLogic public List<Order> getuserorders(int username) throws Exception { if (username!= -1){ // Metoden getorderslist kaster en exception ved feil return wsc.getorderslist(username); // wsc --> WebserviceConverter return null; Figur 8.1 Eksempel på hvordan try-catch blir behandle på øverste lag for å kunne gi brukeren tilbakemeldinger og for å få logget feilen. Første utdrag er fra HomeView og det andre er metoden som kalles på som er hentet fra WSBusinessLogic. 8.2 Tilbakemeldinger til bruker Siden alle mulige feil som blir håndtert med try/catch blir utført på det øverste laget, altså views, er det lett å gi brukeren tilbakemeldinger. For eksempel vil bruker få tilbakemelding på Login-skjermen om det er feil påloggingsinformasjon eller om applikasjonen ikke får koblet seg til databasen (se figur 1.13). En annen type tilbakemelding til brukeren er hvis det er mangelfull data i databasen. Dette blir håndtert med testing på alle verdier som blir skrevet ut. Hvis det ikke finnes noen verdi for det feltet som skal bli skrevet ut, vil det bli skrevet ut en standard feilmelding avhengig av hvilket språk brukeren har valgt. Den norske standardmeldingen er: finner ikke data. Kartsiden vår krever også to koordinater. Ved mangelfull data fra databasen her vil punktet aldri vises og brukeren vil få en tilbakemelding på at enten koordinatene til bortfrakteren eller leveringsadressen ikke finnes. 39

41 8.3 Logging For driftere og for utviklere som ønsker å legge til flere funksjoner til applikasjonen er det kritisk at feil som oppstår blir logget. Derfor bruker vi noe som kalles Log4j. Dette er et Javaverktøy laget for å logge hendelser for applikasjoner. I FôrIt CDS gjøres dette fra øverste nivå, altså fra views. Hver gang en bruker blir videresendt til ErrorView på grunn av en feil, blir hele StackTrace til Exception og en kort beskrivelse av feilen sendt via et Logger-objekt fra Log4j og videre til en loggfil. try { orderlines = bll.getsalesdetails(userorder); catch (Exception e) { orderlines = null; LOGGER.error("Får ikke hentet ordrelinjer fra webservice.", e); bll.setview(new ErrorView(bll.getBundle().getString(ForitBundle.errorWebServiceSalesDetails))); Figur 8.2 Eksempel på hvordan en loggen blir oppdatert ved en feil. Dette gjøres under LOGGER.error(..., e). Loggfilen legges i en mappe kalt logs rett over src-mappen i Client-modulen. Her er et utdrag fra loggfilen: :56:20 LoginView [ERROR] Får ikke hentet liste med ordre fra webservice. java.lang.exception at no.goodtech.foritcds.client.util.webserviceconverter.getorderslist(webserviceconverter.java:217) at no.goodtech.foritcds.client.util.wsbusinesslogic.getuserorders(wsbusinesslogic.java:125) at no.goodtech.foritcds.client.ui.homeview.initgui(homeview.java:62) at no.goodtech.foritcds.client.ui.homeview.<init>(homeview.java:41)... 40

42 9 Resterende arbeid FôrIt CDS er per dags dato et ganske ferdig produkt, men det har noen mangler for å få satt det helt ut i produksjon. Den første tingen som må gjøres er selve installasjonen på EWOS sine servere som vil bli gjort av Goodtech når alt annet er klart. Dette burde gå ganske lett, da det bare er å endre URLen til webservice i propertyfilen kalt WebserviceConnection.xml og starte opp servicene for klienten og webservicen. Utenom det finnes det to hovedproblemer som ikke kan bli løst i selve FôrIt CDS. Det første er at teknologien som skal sende koordinater for lokasjonene til befrakterne ikke er installert enda. Det andre problemet er beregningen av den estimerte ankomsttiden som heller ikke blir publisert til FôrIt-databasen. Når disse problemene vil bli implementert er ikke kjent enda. Applikasjonen er ikke avhengig av disse dataene, dog systemet vil være mer komplett når de er fikset. Ved en eventuell installasjon vil være lurt å laste ned en lokal filstruktur av kart-tiles. Dette vil gjøre applikasjonen mindre avhengig av andre servere som en ikke har kontroll over. 41