Java 11

.gitignore

@@ -26,6 +26,8 @@ tmp/
 local.properties
 .settings/
 .loadpath
+.classpath
+.project
 
 # Locally stored "Eclipse launch configurations"
 *.launch

README.md

@@ -4,29 +4,67 @@ CRCE is an experimental repository, designed to support research into component-
 
 ## Prerequisities
 
-- **JDK 7** set in `JAVA_HOME` environment variable before starting CRCE (there is a problem with running web UI on JDK 8, need to update dependencies), tested on 1.7.0_80
+- **JDK 11** set in `JAVA_HOME` environment variable before starting CRCE, tested on OpenJDK 11.0.4
 - **MongoDB**, tested on v2.6.10, v3.4.10
 - **Maven 3**, tested on 3.5.2
 
-On linux, switching to JDK 7 for development/build can be done via `sudo update-alternatives --config java`.
+On linux, switching to JDK 11 for development/build can be done via `sudo update-alternatives --config java`.
 
 ## Build
 
+Build process consists of two parts. Compiling and building the code itself and building the docker image.
+
+### Build CRCE
+
+This process can be done automatically by running the `build-code.bash` script placed in the project root directory.
+
 1. `crce-parent` in `/pom` directory
 2. `shared-build-settings` in `/build`
 3. everything in `/third-party` (bash: `.../third-party$ for d in * ; do cd $d; mvn clean install; cd .. ; done`)
 4. `crce-core-reactor` in `/core`
 5. `crce-modules-reactor` in `/modules`
+6. `provision-reactor` in `/deploy`
 
 On linux, step 3. can be perfomed via `.../third-party$ for d in * ; do cd $d ; mvn clean install ; cd .. ; done`.  In case of maven error "Received fatal alert: protocol_version", use `mvn -Dhttps.protocols=TLSv1.2 ...` after https://stackoverflow.com/a/50924208/261891.
 
+
+### Build docker image
+
+Docker image is placed in directory `/deploy` but before it can be used, bundles must be collected. 
+Bundles can be collected by running the following commands in `/deploy` directory:
+
+```bash
+mvn clean pax:directory
+./prepare-bundles.sh
+
+```
+
+The `prepare-bundles.sh` script is needed due to the issues further described in the Issues section.
+
+To finally build the image itself, execute the following commnad in `/deploy` directory:
+
+```bash
+docker build . -t ${image-tag}
+```
+
 ## Start up
 
-Run CRCE using Maven plugin for pax in `crce-modules-reactor` module (i.e. `/modules` directory):
+Assuimg the dokcer image is already build, run it by following command:
 
-`mvn pax:provision`
+```bash
+docker run -it \
+        -p 8080:8080 \
+        --add-host mongoserver:172.17.0.1 \
+        -v /felix/deploy:/felix/deploy \
+        ${image-tag}
+```
 
-The output log should write up some info about dependencies terminated by lines similar to the following:
+The `-p` parameter maps the port of docker virual machine to the real port on the computer. 
+The `--add-host` allows docker to connect to the Mongo database running locally (Docker *usually* uses 172.17.0.1 ip to access localhost from the container). The app expects the database to be listening on port 27017 by default.
+The `-v` parameter maps directory in container to the real directory in the host machine so that it can be used to install new bundles via CLI. 
+
+
+If everything works, the output log should write up some info about dependencies terminated by lines similar to the following:
 
 ```
 Listening for transport dt_socket at address: 65505
@@ -47,17 +85,58 @@ The cause of the latter is a badly loaded binary of mathematical solver which do
 
 Started up, the application is accessible at:
 
-- web UI: http://localhost:8080/crce
+- web UI: http://localhost:8080/crce-webui
 - REST web services: http://localhost:8080/rest/v2/
 
 Updated (more or less) REST WS documentation is available at [Apiary](https://crceapi.docs.apiary.io/).
 
+### MongoDB
+
+Mongo DB can either be run locally or in docker using following command:
+
+```bash
+sudo docker run -d -p 27017:27017 -v ~/data:/data/db mongo
+```
+
+Where `~/data` is directory on host machine to be used as a storage by Mongo.
+
 ### lpsolve installation
 
 To solve the issue with mathematical solver, you need to install [lpsolve library](https://sourceforge.net/projects/lpsolve/) to your computer. To do that, follow [their guide](http://lpsolve.sourceforge.net/5.5/Java/README.html#install) step by step.
 
 > Note that on Windows, you do not have to place the libs to `\WINDOWS` or `\WINDOWS\SYSTEM32` as the guide states. Put it wherever you wish and add the directory to your `Path`.
 
+## Debugging
+
+Remote debugging is possible when running CRCE in Docker. To enable remote debug, application needs to be started with following flags:
+
+```bash
+-Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
+```
+
+And expose the port 5005 by adding `-p 5005:5005` to the `docker run` command.
+
+Check the `deploy/Dockerfile` to see the difference between running the app in normal and debug mode.
+
 ## Code updates
 
 After modifying a part of code, only the parental module needs to be rebuilt (no need to rebuild all). After that, the pax process must be restarted.
+
+## Configuration
+
+Configuration is done via OSGI service called [Configuration Admin](https://osgi.org/specification/osgi.cmpn/7.0.0/service.cm.html). 
+Details on how it's implemented in Felix can be found in  [Apache Felix Configuration Admin Service](https://felix.apache.org/documentation/subprojects/apache-felix-config-admin.html).
+
+By default, Felix will look into the `config` directory for possible configuration (example of such directory can be found in `deploy/conf.default`)
+
+
+## Issues
+
+### Required runtime environment capability in some bundles
+
+Some bundles (mostly those from the third parties) either require a particular version of OSGi runtime environment or require the capability `osgi.ee` to be set to a specific value. This may or may not work with newer version of Java and to avoid runtime problems, these requirements need to be removed.
+
+To remove them, it is necessary to edit manifest (`META-INF/MANIFEST.MF`) of such bundle and remove lines containing:
+`Require-Capability: osgi.ee;` or `Bundle-RequiredExecutionEnvironment: J2SE-`. This is done in the `deploy/prepare-bundles.sh` script.
+
+An ideal solution would be to either found newer version of such bundles or replace them with different bundles with same functionality. This however may introduce compatibility issues (as some other bundles may depend on the current versions) or may not even be possible (replacement bundle does not exist). 

arch/.gitignore

@@ -0,0 +1,8 @@
+#ignore vim
+*.swp
+
+#ignore tex build
+*.aux
+*.gz
+*.log
+

arch/sar-2018.tex

@@ -0,0 +1,172 @@
+\documentclass[12pt, a4paper]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[IL2]{fontenc}
+\usepackage[czech]{babel}
+\usepackage{graphicx}
+
+\begin{document}
+\begin{figure}[h!]
+\centering
+\includegraphics[bb= 0 0 820 445 , width=75mm]{favlogo.jpg}
+\end{figure}
+
+\vspace{5cm}
+
+{\centering
+{\huge Architektura CRCE}\\[1em]
+{\large KIV/SAR - semestrální práce}\\[7,5cm]
+}
+
+\begin{tabular}{l r}
+student: & Radek VAIS, Zdeněk VALEŠ\\
+mail: & vaisr@students.zcu.cz, valesz@students.zcu.cz\\
+datum: & 1.1.2019\\
+\end{tabular}
+
+\thispagestyle{empty}
+\newpage
+
+%========================================
+%========================================
+%========================================
+%========================================
+%========================================
+\section{Zadání} %=====================================================================================================
+
+CRCE\footnote{Component Repository supporting Compatibility Evaluation} je komponentové úložiště vyvíjené v rámci výzkumu na Katedře informatiky a výpočetní techniky na Západočeské univerzitě v Plzni. Jeho hlavní vlastností je podpora kontroly kompatibility verzí různých OSGi komponent nebo webových api.
+
+\subsection{Motivace}
+
+Vývoj projektu probíhá již několik let a vystřídalo se na něm mnoho vývojářů, což způsobilo zanesení větších či menších architektonických dluhů. Projekt již můžeme klasifikovat jako velký. Existuje potřeba, aby střídající se vývojáři (např. v rámci bakalářských prací) snadno a rychle zprovoznili základní instalaci a získali tak prostředí, pro rychlý vývoj nových částí. 
+
+\subsection{Cíle projektu}
+
+\begin{itemize}
+	\item Unifikovat proces sestavení aplikace a spuštění.
+	\item Zdokumentovat současnou architekturu aplikace.
+	\item Analyzovat závislosti modulů v projektu a ověřit, zda některé moduly mají být součástí jádra.
+	\item Připravit Docker image pro vývojáře.
+\end{itemize}
+
+\newpage
+%========================================
+%========================================
+%========================================
+%========================================
+%========================================
+\section{Analýza~architektury} %============================================================================================
+
+Celý projekt je rozdělen do čtyř hlavních modulů: sdílené nastavení sestavení, jádro, moduly a knihovny třetích stran. Ne zcela jasné je začlenění mechanismu pro nasazení a spuštění v modulu \texttt{CRCE modules} (jedná se o komponentu \texttt{provision}). Závislostí modulů na jádře pozorujeme dva typy. Prvním typem je závislost na agregačním modulu jádra, druhým je jmenovitá závislost na komponentách jádra. Tyto skutečnosti jsou patrné na celkovém diagramu na Obrázku \ref{fig:wholeCRCE}.
+
+\begin{figure}[h!]
+\centering
+\includegraphics[width=135mm]{wholeCRCE.png}
+\caption{Diagram závislostí všech maven komponent projektu CRCE před provedenými úpravami.}
+\label{fig:wholeCRCE}
+\end{figure}
+
+Během analýzy modulu pro moduly CRCE jsme identifikovali několik kandidátů na přesun do jádra. Za kandidáty jsme volili takové komponenty, které využívá velká část ostatních modulů a zároveň tyto moduly mají závislosti do jádra. Komponenta webového rozhraní (\texttt{crce-webui}) tomuto pravidlu sice odporuje, představuje ale základní komponentu, bez které by úložiště nešlo použít. Přesouvané komponenty jsou: \texttt{crce-compatibility-api}, \texttt{crce-webui}, \texttt{crce-concurrency} (graficky znázorněno na Obrázku \ref{fig:modulesCRCE}). 
+
+Po identifikace kandidátů jsme z přesunu vyřadili komponentu metadata-osgi-bundle, kvůli nedostatečné obecnosti. Komponenta je schopna indexovat pouze OSGI komponenty -- přesun do jádra by byl možný, pokud by uměla indexovat obecné JAR. Komponenta \texttt{crce-webui} bohužel obsahuje silnou závislost na této komponentě, která brání přesunu \texttt{crce-webui} do jádra. Závislost spočívá v použití několika konstant, které jsou v definované v metadata-osgi-bundle. Navrhli jsme tedy přidání metody do rozhraní indexeru pro zjištění jaké elementy indexer zpracovává a silnou závislost jsme nahradili slabou závislostí.
+
+\begin{figure}[h!]
+\centering
+\includegraphics[width=135mm]{modules.png}
+\label{fig:modulesCRCE}
+\caption{Diagram původních závislostí uvnitř modulu moduly CRCE. Zeleně jsou označeny přesouvané komponenty. Červeně je označena nevhodná závislost.}
+\end{figure}
+
+%========================================
+%========================================
+%========================================
+%========================================
+%========================================
+\section{Provedené~změny} %=======================================================================================
+
+V projektu jsme provedli několik změn, které by měly vést k zjednodušení práce budoucích vývojářů. Pro přehlednost dodávám, že v této sekci pojem \textit{modul} značí maven modul v kořenovém adresáři CRCE a pojem \textit{komponenta} značí jeden z maven modulů obsahující konkrétní implementaci (\textit{crce-webui}, \textit{crce-metadata-api}, ...).
+
+\subsection{Nový modul pro sestavení}
+Do kořene CRCE byl přidán nový modul \textit{deploy}, do kterého byla přesunuta komponenta \textit{provision}, používaná ke spouštění CRCE. Jsou zde agregovány všechny komponenty z jádra a komponenty z modulu \textit{modules}, které jsou zachycené v \textit{crce-default-modules}. 
+
+Nově přidaná komponenta \textit{crce-default-modules} tedy slouží jako agregátor komponent z modulu \textit{modules}, které mají být použité ve výsledné distribuci.
+
+V rámci přípravy modulu pro sestavení a spuštění byla povýšena verze Felix na 5.0.0. Starší verze způsobovala problémy se spuštěním interaktivního shellu při spuštění pomocí Dockeru.
+
+\subsection{Přesun vybraných modulů do jádra}
+Do jádra byly z modulu \textit{modules} přesunuty komponenty: \textit{crce-compatibility-api}, \textit{crce-webui} a \textit{crce-concurrency}. V případě \textit{crce-webui} bylo nutné odstranit závislost na \textit{crce-core} (jinak by se jednalo o kruhovou závislost) a nahradit ji jednotlivými závislostmi na vybraných komponentách z jádra.
+
+V komponentě \textit{crce-compatibility-api} bylo nutné přidat výchozí (prázdnou) implementaci rozhraní \textit{Compatibility} a \textit{Diff}. Pro tyto implementace byl přidán unit test.
+
+Součástí přesunu komponent do jádra bylo přidání unit testu do \textit{crce-metadata-osgi-bundle}, který dokazuje schopnost této komponenty indexovat pouze OSGI bundly a ne obecné JAR.
+
+\subsubsection{Nahrazení silné závislosti v komponentě crce-webui}
+Komponenta \textit{crce-webui} obsahovala silnou závislost na komponentě \textit{crce-metadata-osgi-bundle}. Tato závislost spočívala v použití několika konstant, označujících indexované elementy, definovaných v rozhraní \textit{NsOsgiIdentity}. Konstanty byly použity ve třídě \textit{ResourceServlet} k filtrování zobrazovaných OSGI bundlů. 
+
+Po dohodě s vyučujícím jsme tuto závislost nahradili slabou závislostí -- konstanty stejného typu jsme dodefinovali i v komponentě \textit{crce-webui}. Silná závislost byla odstraněna, nicméně pokud se v budoucnu změní komponenta \textit{crce-metadata-osgi-bundle}, bude nutné kontrolovat, zda změna neovlivnila \textit{crce-webui} a případné nesrovnalosti opravit.
+
+Aby bylo podobným závislostem v budoucnosti zamezeno, rozhraní indexeru bylo rozšířeno o metodu, která vrací elementy, jež je indexer schopen detekovat. V rámci této práce byla vytvořena defaultní implementace této vlastnosti v AbstractIndexer, která vrací pouze prázdný seznam. Projekt lze bezpečně přeložit, ale momentálně novou funkci rozhraní plně využívá jen OSGiIndexer.
+
+\begin{figure}[h!]
+\centering
+\includegraphics[width=135mm]{indexerApi.png}
+\label{fig:indexerApi}
+\caption{Diagram ukazuje upravené rozhraní indexeru, které nově obsahuje metodu getIndexedAttributes, která slouží k získání seznamu vlastností, které daný indexer zpracovává. Dále naznačuje možnost umístit implementaci indexeru do modulu crce-core nebo crce-modules (fiktivní indexery JarIndexer a AnotherIndexer).}
+\end{figure}
+
+\subsubsection{Načítání connection stringu}
+
+Součástí příprav pro dockerizaci bylo přidání konfigurace připojení k databázi MongoDB. Ke konfiguraci připojení lze nyní využít proměnnou prostředí \textit{mongo\_connection}, kde aplikace očekává MongoDB connection string\footnote{viz dokumentace: https://docs.mongodb.com/manual/reference/connection-string/}. V případě, že tato proměnná není nastavena, použije se výchozí hodnota (\textit{mongodb://localhost:27017}, která nese připojení k databázi běžící na localhostu a standardním portu. Výhodou tohoto přístupu je možnost konfigurovat connection string v Dockerfile a při změně pouze znovu sestavit image.
+
+
+\section{Dockerizace projektu}
+Do modulu \textit{deploy} byl přidán Dockerfile, kterým je možné sestavit docker image obsahující spustitelnou verzi CRCE. Do takto spuštěného CRCE lze doinstalovávat nové OSGI komponenty a není nutné celý projekt znovu sestavovat. 
+
+
+
+%========================================
+%========================================
+%========================================
+%========================================
+%========================================
+\section{Uživatelská~příručka} %======================================================================================
+
+Provedené změny ovlivnily základní používání projektu při vývoji. 
+
+Pro sestavení na platformě Linux lze použít bash script \textit{build.bash}\footnote{Teoreticky není nutná platforma Linux. Pro uživatele Windows by měl být dostačující bash interpret nebo Linux subsystem. Tato možnost nebyla testována.}, který automaticky spustí jednotlivé kroky sestavení pomocí nástroje Maven. Script vždy vykonává všechny kroky od začátku, v případě selhání je vhodné po opravě pokračovat v buildu manuálně.
+
+V případě, že databáze neběží na localhostu, nebo standardním portu, je možné nastavit připojení skrze proměnnou prostředí \textit{mongo\_connection}. Tato proměnná by v případě použití měla obsahovat celý connection string. Pokud není nastavená, pro připojení k databázi bude použita výchozí hodnota: \textit{mongodb://localhost:27017}.
+
+\subsection{Docker}
+K sestavení Docker image je možné použít Dockerfile, který se nachází v modulu \textit{deploy}. Sestavení image je provedeno příkazem:
+
+\begin{verbatim}
+docker build . -t crce-docker
+\end{verbatim} 
+
+Výsledný image obsahuje distribuci Apache Felix 5.0.0, JDK 1.7 a všechny OSGI bundly z CRCE. Spuštění lze provést příkazem:
+
+\begin{verbatim}
+docker run -it \ 
+	   -p 8080:8080 \
+	   --add-host mongoserver:172.17.0.1 \
+	   -v /felix/deploy:/felix/deploy \
+	   crce-docker 
+\end{verbatim}
+
+Parametr \textit{add-host} slouží k přidání záznamu do /etc/hosts v kontejneru a image se pak může k databázi běžící na hostovacím stroji dostat pomocí hostname \textit{mongoserver}. IP adresa 172.17.0.1 je adresa, kterou docker přiřazuje hostovacímu stroji. Do adresáře \textit{/felix/deploy} na hostovacím stroji je možné vložit OSGI bundly a ty následně nainstalovat a spustit skrze Gogo shell. K běžící instanci je možné přistoupit na adrese \textit{http://localhost:8080/crce}.
+
+Před spuštěním docker image je třeba spustit instanci MongoDB. Není podstatné, zda bude spuštěna prostřednictvím Dockeru (např. image 3.4-jessie), lokálním stroji nebo na serveru. Jen je třeba před sestavením ověřit nastavení connection string. Není připravena konfigurace docker-compose, protože se nám v rámci konfigurace a testů nepodařilo zprovoznit GoGo shell při použití compose mechanismu, uživatel by byl ochuzen o diagnostické možnosti OSGi runtime.
+
+%========================================
+%========================================
+%========================================
+%========================================
+%========================================
+\newpage
+\section{Závěr}  %======================================================================================================
+
+V rámci projektu jsme naplnili cíl usnadnit novým vývojářům spuštění výchozí aplikace, především přípravou docker image. Nepodařilo se nám zjednodušit proces sestavení celé aplikace na jeden Maven příkaz nicméně pro prostředí Linux jsme vytvořili script, který úkony nutné pro sestavení provede automaticky.
+Dále jsme přesunuli několik modulů do jádra CRCE z důvodu jejich provázanosti s ostatními nebo nutnosti pro používání. 
+
+
+\end{document}