ukelonn

Ukelonn: en webapplikasjon for ukelønn

Tanken er at ungene skal kunne registrere jobber de gjør i hjemmet og at foreldrene kan registrere utbetalinger av ukelønn og andre måter lønna blir betalt på (f.eks. utlegg/lån og ekstra datapakker til mobil).

Webapplikasjonen er skrevet for å bli kjørt i en OSGi runtime, og er ment å være responsive slik at den er lett å kjøre på mobiltelefoner og nettbrett.

Hva ligger på de forskjellige branchene

I øyeblikket er det tre hoved-brancher:
1. using-vaadin
Denne branchen bruker [[https://vaadin.com/home][vaadin]] og er iferd med å nærme seg primefaces-branchen i funksjonalitet. Her brukes Vaadins [[https://vaadin.com/docs/-/part/touchkit/mobile-components.html][Mobile User Interface Components]] for å få noe som ser "app-aktig" ut, iallefall på registrering av jobber, gjort av ungene. Admin-grensesnittet er også blitt mer mobilt men vil trives bedre på en tablet enn på en mobil (det er mer som skal vises fram). Denne branchen er i skrivende stund "i produksjon" i heimen.
2. using-primefaces
Denne branchen bruker [[https://en.wikipedia.org/wiki/JavaServer_Faces][JSF]] med [[http://www.primefaces.org/][primefaces]] og var den første som var ferdig. Jeg støtte på [[https://github.com/primefaces/primefaces/issues/1864][en bug]] i primefaces mobile som gjorde at versjonen som kjører nå ikke er så pen (siden jeg ikke kunne bruke primefaces mobile så måtte jeg gjøre et triks med å blåse opp fontene for at ting ikke skulle være uleselig på mobil, så sluttresultatet ser litt rart ut)
3. using-rendersnake
Denne branchen er ment å være "back to basic" og bruke [[http://rendersnake.org/][rendersnake]] sammen med en REST-ful backend, men den er i skrivende stund ikke forbi "hello world"-stadiet

Jeg har også plan om å lage en branch med en versjon som bruker spark med angular.js istedenfor primefaces, men denne er foreløpig på plan-stadiet. Spark er allerede en OSGi-bundle, så det bør la seg gjøre å få den til å spille i Karaf på en sånn måte at jeg kan beholde database-laget (der all business-intelligensen er), mens jeg fjerner alt som har med servlets å gjøre. Forhåpentligvis kan jeg også beholde Shiro for å håndtere autentisering og autorisasjon.

Utsjekk og bygg

Dette trengs for å laste og teste ut denne programvaren
1. Installer det som trengs:
2. git: https://git-scm.com/download/win
3. Java SDK 1.8: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
4. Apache maven:
5. Download: https://maven.apache.org/download.cgi
6. Install: https://maven.apache.org/install.html
7. Run: https://maven.apache.org/run.html
8. Gjør en klon av git-repositoriet
#+BEGIN_EXAMPLE mkdir %HOME%\git cd %HOME%\git git clone https://github.com/steinarb/ukelonn.git #+END_EXAMPLE
9. Åpne et kommandolinje-vindu og skriv følgende kommandoer:
#+BEGIN_EXAMPLE cd %HOME%\git\ukelonn git checkout using-vaadin mvn clean install #+END_EXAMPLE
10. [http://karaf.apache.org/download.html][Last ned Karaf 4.1.1]], pakk ut den nedlastede distribusjonen og start karaf fra kommandlinja
11. Gjør ukelonn-webapplikasjonen tilgjengelig for karaf, som "karaf features", hentet fra maven:
#+BEGIN_EXAMPLE feature:repo-add mvn:no.priv.bang.ukelonn/ukelonn.karaf/LATEST/xml/features #+END_EXAMPLE
12. Installer webapplikasjonen:
#+BEGIN_EXAMPLE feature:install ukelonn-db-derby-test feature:install ukelonn #+END_EXAMPLE
13. Koble en nettleser mot http://localhost:8181/ukelonn/
14. For en vanlig bruker, brukernavn/passord: jad/1ad
15. Vanlig bruker kan registrere nye jobber og sjekke saldo
16. For en administrator-bruker, brukernavn/passord: on/ola12
17. Administrator-bruker kan registrere utbetalinger, legge inn nye jobbtyper og endre eksisterende, legge inn nye utbetalinger og justere på eksisterende, og legge inn brukere og endre på eksisterende brukere

Beskrivelse av koden

(Beskriver versjonen fra using-vaadin)

Prosjektet er et maven-prosjekt med følgende struktur:
• pom.xml
Dette er topp-prosjektet som definerer alle versjoner av programvare som brukes og alle versjoner av avhengigheter og felles-oppsett for plugins.
• ukelonn.api/pom.xml
Dette er en OSGi-bundle som definerer to OSGi-servicer: UkelonnService og UkelonnDatabase
• ukelonn.bundle/pom.xml
Dette er selve webapplikasjonen. Siden dette er en Vaadin-applikasjon som bruker servlet API, så er dette en WAR og ikke en JAR, men det er også en OSGi-bundle som krever en UkelonnDatabase service og som eksponerer en UkelonnService service
• ukelonn.bundle.test.db/pom.xml
Dette er en ikke-persistent SQL-database i minnet som setter opp forventet skjema og fyller opp databasen med test-data. Dette er en fullt funksjonell database, men ingenting blir persistert mellom kjøringer. Den brukes til test både av webappen i gogoshell og brukes som en vanlig jar-fil i enhetstestene i ukelonn.bundle
• ukelonn.bundle.postgresql.db/pom.xml
Dette er en OSGi-bundle som forventer å finne en PostgreSQL-base som brukeren som kjører webappen har rettigheter til og som har en database "ukelonn" med forventet skjema
• ukelonn.tests/pom.xml
Dette er en Pax Exam integrasjonstest som sjekker at OSGi-bundlene starter og at de tilbyr riktig service.
• ukelonn.gogoshell/pom.xml
Dette er en POM for å starte webappen kjørende i gogoshell. Dvs. en fullt funksjonell OSGi-kontainer som blir startet på nytt hver gang maven starter den
• ukelonn.karaf/pom.xml
Dette er en POM som lager en "feature"-fil for [[http://karaf.apache.org/][Apache karaf]]
• ukelonn.rebundled/pom.xml
Hver gang man trenger en avhengighet som ikke er en OSGi-bundle kan man "rebundle" avhengigheten ved å lage et nytt underprosjekt av dette prosjektet. Apache Karaf har muligheter til å auto-bundle jar-filer ved lasting, men integrasjonstestene i ukelonn.tests og gogoshell-kjøring av prosjektet trenger begge avhengigheter som OSGi-bundler. Vaadin TouchKit og noen av avhengighetene til TouchKit var /ikke/ bundler og måtte rebundles. Men selve Vaadin og avhengighetene var allerede bundlet.

Kjøring på apache karaf med PostgreSQL

Dette krever at man har en lokal PostgreSQL-installasjon med følgende innstillinger:
1. En database med navn "ukelonn" der brukeren karaf kjører med har alle rettigheter
2. Følgende tabeller må være i databasen ukelonn: https://github.com/steinarb/ukelonn/tree/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/tables
3. Følgende views må være i databasen ukelonn: https://github.com/steinarb/ukelonn/tree/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/views
4. I tillegg så må eksempeldataene være på plass for å kunne logge inn med brukerene nevnt i eksemplene: https://github.com/steinarb/ukelonn/tree/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/data
Rekkefølgen dataene skal tas inn i, er:
5. example_transaction_types.sql: https://github.com/steinarb/ukelonn/blob/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/data/example_transaction_types.sql

/NB!/ denne fila /må/ inn i databasen som den er for at det skal fungere å legge inn nye brukere
1. example_users.sql: https://github.com/steinarb/ukelonn/blob/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/data/example_users.sql
2. example_administrators.sql: https://github.com/steinarb/ukelonn/blob/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/data/example_administrators.sql
3. example_accounts.sql: https://github.com/steinarb/ukelonn/blob/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/data/example_accounts.sql
4. example_transactions.sql: https://github.com/steinarb/ukelonn/blob/using-primefaces/ukelonn.bundle.test.db/src/main/resources/sql/data/example_transactions.sql
/OBS/: Her er det en mulighet til å legge inn egne data:
5. Iallefall legg inn en bruker i example_users.sql
6. Gjør samme bruker administrator i example_administrators.sql
7. Behold example_transaction_types.sql (den kan justeres på i ettertid fra AdminUIet)
8. Logg inn som admin-brukeren og du kan:
9. legge inn nye jobbtyper,
10. justere eksisterende jobbtyper (f.eks. beløp)
11. legge inn nye brukere for ungene (for at disse skal dukke opp så må du ha lagt inn example_transaction_types.sql) som den er

Lisens

Framgangsmåte:
1. Klon og bygg webapplikasjonen (regner med at linux-brukere klarer å oversette til noe passende):
#+BEGIN_EXAMPLE mkdir %HOME%\git cd %HOME%\git git clone https://github.com/steinarb/ukelonn.git cd %HOME%\git\ukelonn git checkout using-vaadin mvn clean install #+END_EXAMPLE
2. [http://karaf.apache.org/download.html][Last ned Karaf 4.1.1]], pakk ut den nedlastede distribusjonen og start karaf fra kommandlinja
3. Gjør ukelonn-webapplikasjonen tilgjengelig for karaf, som "karaf features", hentet fra maven:
#+BEGIN_EXAMPLE feature:repo-add mvn:no.priv.bang.ukelonn/ukelonn.karaf/LATEST/xml/features #+END_EXAMPLE
4. Installer webapplikasjonen:
#+BEGIN_EXAMPLE feature:install ukelonn-db-postgresql feature:install ukelonn #+END_EXAMPLE
5. Koble en nettleser mot http://localhost:8181/ukelonn/
6. For en vanlig bruker, brukernavn/passord: jad/1ad
7. Vanlig bruker kan registrere nye jobber og sjekke saldo
8. For en administrator-bruker, brukernavn/passord: on/ola12
9. Administrator-bruker kan registrere utbetalinger, legge inn nye jobbtyper og endre eksisterende, legge inn nye utbetalinger og justere på eksisterende, og legge inn brukere og endre på eksisterende brukere

Lisensen er Apache Public License v 2.0 fordi denne er kompatibel med Affero GPL v 3.0.