From 275df7d45063ae9e8f9d1377099e942dcb824348 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Rade?= Date: Fri, 27 Sep 2019 16:37:33 +0200 Subject: [PATCH] #5 developer doc straightened out --- docs/DevelopmentGuide.md | 282 +++++++++++++++-------------- {images => docs}/arc-overview.adoc | 0 {images => docs}/arc-overview.png | Bin docs/build-overview.adoc | 36 ++++ {images => docs}/dev-mindmap.adoc | 0 {images => docs}/dev-mindmap.png | Bin {images => docs}/uml-handler.png | Bin {images => docs}/uml-hanlder.adoc | 0 {images => docs}/uml-layout.adoc | 0 {images => docs}/uml-layout.png | Bin {images => docs}/uml-overview.adoc | 0 {images => docs}/uml-overview.png | Bin {images => docs}/uml-to.adoc | 0 {images => docs}/uml-to.png | Bin 14 files changed, 182 insertions(+), 136 deletions(-) rename {images => docs}/arc-overview.adoc (100%) rename {images => docs}/arc-overview.png (100%) create mode 100644 docs/build-overview.adoc rename {images => docs}/dev-mindmap.adoc (100%) rename {images => docs}/dev-mindmap.png (100%) rename {images => docs}/uml-handler.png (100%) rename {images => docs}/uml-hanlder.adoc (100%) rename {images => docs}/uml-layout.adoc (100%) rename {images => docs}/uml-layout.png (100%) rename {images => docs}/uml-overview.adoc (100%) rename {images => docs}/uml-overview.png (100%) rename {images => docs}/uml-to.adoc (100%) rename {images => docs}/uml-to.png (100%) diff --git a/docs/DevelopmentGuide.md b/docs/DevelopmentGuide.md index 9e1fdb5..e8200ae 100644 --- a/docs/DevelopmentGuide.md +++ b/docs/DevelopmentGuide.md @@ -1,12 +1,77 @@ ![Preview](../images/WheatFieldWithCrows.png) +#Quickstart +## Frontend +### Requirements +Kotlin/JS uses `Gradle` for the build, for the JS runtime `NodeJS`, and for the JS dependency management part `npm`. +You should have installed: +* node js (https://nodejs.org/en/download/current/) +* Apache Gradle +* Google Chrome (72.0.3626.81 or higher) +* Moesif CORS Plugin (for Chrome) + +### Build +gradle is run under Windows with gitbash: + +* ./gradlew.bat tasks # list all gradle tasks +* ./gradlew.bat webpack-bundle # create main.bundle.js +* ./gradlew.bat test --exclude-task npm-install + +Internally gradle uses npm for the JS part. +``` + npm --verbose +``` + If task npm-install hangs, try +``` + ./gradlew.bat npm-install --info --debug --stacktrace +``` +Helps in identifying thing that may go wrong (eg. due to proxy settings). + +### Run +``` +gradlew.bat -t run +``` + +## Backend +### Requirements +* (Oracle) JDK 1.8_181 (or higher) +* Apache Maven 3.6.0 + +### Create +Create from the Apache Isis SimpleApp archetype: +```bash +mvn archetype:generate \ + -D archetypeGroupId=org.apache.isis.archetype \ + -D archetypeArtifactId=simpleapp-archetype \ + -D archetypeVersion=2.0.0-M2 \ + -D groupId=org.my \ + -D artifactId=myapp-2.0.0-M2 \ + -D version=1.0.0 -B +``` +### Build +```bash +mvn clean install -DskipTests +``` +### Run +```bash +cd webapp +mvn -Djetty.port=8080 jetty:run -DPROTOTYPING +``` + # Design +In the following section you'll find information that likely helps understanding the implementation. ## Overview -![Preview](../images/uml-overview.png) +![Preview](./uml-overview.png) ## Handler Chain -![Preview](../images/uml-handler.png) +![Preview](./uml-handler.png) ## Patterns +### Redux +The implementation is an (independent) reinvention of Redux. +I prefer the name Aggregator over Reducer though - IIRC it's even older. +### Half Object Protocol +The HOP pattern dates back to the early 2000, namely CanooULC. +IMO Naked Objects together with the RO API and kroViz resembles something similar. ### Transfer Object (JEE / EAA) TO's are created from JSON responses ### Event Sourcing (EAA) @@ -31,50 +96,21 @@ UI elements are hierarchically grouped, cf. *layout.xml Used for building tables dynamically. ### Remote Facade The Restful Objects API. -### Redux -The implementaion here is an (independent) reinvention of Redux. -I prefer the name Aggregator over Reducer though - IIRC it's even older. -### Half Object Protocol -The HOP pattern dates back to the early 2000, namely CanooULC. -IMO Naked Objects together with the RO API and kroViz resembles something similar. - - -# Toolchain -When you are accustomed to the well settled Java ecosystem with integrated development environments, prepare yourself for learning new tools and addressing new problems. - -Kotlin is straightforward and once you now it, you may not want to go back. - -![Preview](../images/dev-mindmap.png) - -# Setup the Back-end -## Requirements -* (Oracle) JDK 1.8_181 (or higher) -* Apache Maven 3.6.0 +# Troubleshooting -## Create a Sample Backend -Create from the Apache Isis SimpleApp archetype: -```bash -mvn archetype:generate \ - -D archetypeGroupId=org.apache.isis.archetype \ - -D archetypeArtifactId=simpleapp-archetype \ - -D archetypeVersion=2.0.0-M2 \ - -D groupId=org.my \ - -D artifactId=myapp-2.0.0-M2 \ - -D version=1.0.0 -B -``` -Build via -```bash -mvn clean install -DskipTests -``` +## CORS +CORS stands for 'Cross Origin Resource Sharing' aka: 'Same Origin Policy' was designed to improve security and is implemented in browsers. +In short it means: your browser will allow loading of resources only if host and port are identical to the url you are on. +Ie. webpage loaded from http://localhost:8088/ resources from http://localhost:8080/restful will not be accessible. -## Dealing with CORS +### Solution 1 (Q&D): +Disable CORS in your browser, eg. for Chrome with the MOESIF plugin. Nicely done introduction: * https://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-definedhttps://www.moesif.com/blog/technical/cors/Authoritative-Guide-to-CORS-Cross-Origin-Resource-Sharing-for-REST-APIs/#how-is-origin-defined -### Amend web.xml - +### Solution 2: Add to webapp\src\main\webapp\WEB-INF\web.xml ```xml @@ -109,124 +145,98 @@ Add to webapp\src\main\webapp\WEB-INF\web.xml ``` -### Put into webapp/src/main/webapp/WEB-INF/lib +Put into webapp/src/main/webapp/WEB-INF/lib: * https://search.maven.org/artifact/org.eclipse.jetty/jetty-util/9.4.12.v20180830/jar * https://search.maven.org/artifact/org.eclipse.jetty/jetty-servlets/9.4.12.v20180830/jar -## Start the Backend -```bash -cd webapp -mvn -Djetty.port=8080 jetty:run -DPROTOTYPING -``` - -# Build the Front-end -## Build -Build is done via gradle - under Windows with gitbash: - -* ./gradlew.bat tasks # list all gradle tasks -* ./gradlew.bat webpack-bundle # create main.bundle.js -* ./gradlew.bat test --exclude-task npm-install - -Internally gradle uses npm for the JS part. - - npm --verbose - - If task npm-install hangs, try - - ./gradlew.bat npm-install --info --debug --stacktrace - - -Helps in identifying thing that may go wrong (eg. due to proxy settings). - - - -## Setup -proxy settings: -https://jjasonclark.com/how-to-setup-node-behind-web-proxy/ -https://gist.github.com/EudesSilva/0329645b9c258e0495544b8a5ccd1454 - - - -# Toolchain -* node js (https://nodejs.org/en/download/current/) -* Apache Gradle -* Google Chrome (72.0.3626.81) -* Moesif CORS Plugin (for Chrome) - -Kotlin/JS uses `Gradle` for the build, for the JS runtime `NodeJS`, and for the JS dependency management part `npm`. +### Solution 3: +Incorporate kroviz.js eg. in the WAR containing your Apache Isis backend. +## Network Proxy Depending on the network you are in, you may need to configure the proxy settings. Among the relevant files are: -```bash -~/.npmrc -~/.gitconfig -~/.ssh/config -~/.ssh/id_rsa -``` -### Access to git from npm -#### Problem -```bash -npm ERR! Error while executing: -npm ERR! C:\Program Files\Git\bin\git.EXE ls-remote -h -t ssh://git@github.com/jarecsni/font-awesome-webpack.git -npm ERR! -npm ERR! git@ssh.github.com: Permission denied (publickey). -npm ERR! fatal: Could not read from remote repository. -npm ERR! -npm ERR! Please make sure you have the correct access rights -npm ERR! and the repository exists. -npm ERR! -npm ERR! exited with error code: 128 -``` -#### Solution -`~/.ssh/config` -```bash -ProxyCommand /bin/connect.exe -H proxy.server.name:3128 %h %p - -Host github.com - User git - Port 22 - Hostname github.com - IdentityFile "C:\users\username\.ssh\id_rsa" - TCPKeepAlive yes - IdentitiesOnly yes - -Host ssh.github.com - User git - Port 443 - Hostname ssh.github.com - IdentityFile "C:\users\username\.ssh\id_rsa" - TCPKeepAlive yes - IdentitiesOnly yes -``` - -### Corporate Firewall with SSL 'inspection' + ```bash + ~/.npmrc + ~/.gitconfig + ~/.ssh/config + ~/.ssh/id_rsa + ``` +### References + * https://jjasonclark.com/how-to-setup-node-behind-web-proxy/ + * https://gist.github.com/EudesSilva/0329645b9c258e0495544b8a5ccd1454 + +## Corporate Firewall with SSL 'inspection' There are some questionable setups in coporate settings that are based on SSL replacement. In order to cope with it, you may try to import the Certificate into cacerts, see https://intellij-support.jetbrains.com/hc/en-us/community/posts/115000094584-IDEA-Ultimate-2016-3-4-throwing-unable-to-find-valid-certification-path-to-requested-target-when-trying-to-refresh-gradle -### Karma-Tests do not respond to code changes +## Access to git from npm +### Problem + ```bash + npm ERR! Error while executing: + npm ERR! C:\Program Files\Git\bin\git.EXE ls-remote -h -t ssh://git@github.com/jarecsni/font-awesome-webpack.git + npm ERR! + npm ERR! git@ssh.github.com: Permission denied (publickey). + npm ERR! fatal: Could not read from remote repository. + npm ERR! + npm ERR! Please make sure you have the correct access rights + npm ERR! and the repository exists. + npm ERR! + npm ERR! exited with error code: 128 + ``` + ### Solution + `~/.ssh/config` + ```bash + ProxyCommand /bin/connect.exe -H proxy.server.name:3128 %h %p + + Host github.com + User git + Port 22 + Hostname github.com + IdentityFile "C:\users\username\.ssh\id_rsa" + TCPKeepAlive yes + IdentitiesOnly yes + + Host ssh.github.com + User git + Port 443 + Hostname ssh.github.com + IdentityFile "C:\users\username\.ssh\id_rsa" + TCPKeepAlive yes + IdentitiesOnly yes + ``` + + ### Karma-Tests do not respond to code changes + Windows: + ``` + taskkill /f /im node.exe + ``` + Linux: + ``` + killall node + ``` + +# Misc +## HowTo +When you are accustomed to the well settled Java ecosystem with integrated development environments, prepare yourself for learning new tools and addressing new problems. -Windows: -``` -taskkill /f /im node.exe -``` +Kotlin is straightforward and once you now it, you may not want to go back. -Linux: -``` -killall node -``` +![Preview](./dev-mindmap.png) -### Visualize JS dependencies +## Visualize JS dependencies ``` npm -g install dependo dependo -f amd ./build/js/kroviz.js > dependo.html ``` -### Measure Test Coverage - +## Measure Test Coverage ``` nyc npm test ``` #### References https://github.com/istanbuljs/nyc + +## Gradle Build Overview +![Preview](./build-overview.png) diff --git a/images/arc-overview.adoc b/docs/arc-overview.adoc similarity index 100% rename from images/arc-overview.adoc rename to docs/arc-overview.adoc diff --git a/images/arc-overview.png b/docs/arc-overview.png similarity index 100% rename from images/arc-overview.png rename to docs/arc-overview.png diff --git a/docs/build-overview.adoc b/docs/build-overview.adoc new file mode 100644 index 0000000..ec4490c --- /dev/null +++ b/docs/build-overview.adoc @@ -0,0 +1,36 @@ +.Build Overview Diagram +[plantuml,file="build-overview.png"] +-- +@startuml +component gradle <> + +component kotlin2js <> as K2JS +component kotlinFrontend <> as KF +component npm + +package build { + rectangle karma.conf.js <> as KC +} + +rectangle package.json <> + +package projectDir { + rectangle gradle.properties <> + rectangle settings.gradle <> + rectangle build.gradle <> as BG +} + +component DCE +component webpack + +gradle -> BG +gradle -> gradle.properties +gradle -> settings.gradle + +gradle -> K2JS +BG->KF : uses +KF->KC : in order to generate + +@enduml +-- + \ No newline at end of file diff --git a/images/dev-mindmap.adoc b/docs/dev-mindmap.adoc similarity index 100% rename from images/dev-mindmap.adoc rename to docs/dev-mindmap.adoc diff --git a/images/dev-mindmap.png b/docs/dev-mindmap.png similarity index 100% rename from images/dev-mindmap.png rename to docs/dev-mindmap.png diff --git a/images/uml-handler.png b/docs/uml-handler.png similarity index 100% rename from images/uml-handler.png rename to docs/uml-handler.png diff --git a/images/uml-hanlder.adoc b/docs/uml-hanlder.adoc similarity index 100% rename from images/uml-hanlder.adoc rename to docs/uml-hanlder.adoc diff --git a/images/uml-layout.adoc b/docs/uml-layout.adoc similarity index 100% rename from images/uml-layout.adoc rename to docs/uml-layout.adoc diff --git a/images/uml-layout.png b/docs/uml-layout.png similarity index 100% rename from images/uml-layout.png rename to docs/uml-layout.png diff --git a/images/uml-overview.adoc b/docs/uml-overview.adoc similarity index 100% rename from images/uml-overview.adoc rename to docs/uml-overview.adoc diff --git a/images/uml-overview.png b/docs/uml-overview.png similarity index 100% rename from images/uml-overview.png rename to docs/uml-overview.png diff --git a/images/uml-to.adoc b/docs/uml-to.adoc similarity index 100% rename from images/uml-to.adoc rename to docs/uml-to.adoc diff --git a/images/uml-to.png b/docs/uml-to.png similarity index 100% rename from images/uml-to.png rename to docs/uml-to.png