%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE    : Development.tex
% SUBJECT : Document describing development issues in Patch Repository.
% AUTHOR  : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Development}
\label{development}

This chapter describes how to develop, and build the \portal system. The audience for this chapter is \portal developers.

\section{Setup}
\label{dev-setup}
This section describes how to setup the \portal environment to be able to build the web application

\subsection{Development}
\begin{enumerate}
  \item Clone the repository from BigMac
    \begin{enumerate}
      \item Add developers public key to BigMac account
      \item Clone the repository \newline
      \command{git clone ``ssh://git@bigmac.northgrum.com:8010/saipt/portal-webapp.git''}
    \end{enumerate}
    
  \item Create/Edit \command{settings.xml} in the \command{.m2} located in the home directory. See Subsection~\ref{settings.xml}
  \item \portal requires \command{ngas-commons} library to be built prior to building the web application. See Subsection~\ref{ngas-commons}
  \item Change directories into the project and run \command{mvn clean install antrun:run@warcopy}. This could take some time to download the required libraries.
  \item Start the tomcat server and navigate to \command{http://localhost:8080/portal/} to make sure the server comes up
\end{enumerate}

\subsection{NGAS Commons}
\label{ngas-commons}
NGAS Commons is a common library of functions that other java applications can take advantage of.

To checkout the library:\newline
\command{git clone ``ssh://git@bigmac.northgrum.com:8010/saipt/ngas-commons.git''}

To build:\newline
\command{mvn clean install}

Note: \command{ngas-commons} needs to be built prior to building the main application

\section{Yarn}
\label{yarn}
Yarn is the new package manager used with \command{node.js} in replacement of \command{npm} it uses the same \command{pacakge.json} file that \command{npm} did.

To download a new client side library use the command \command{yarn add <package-name> --save}. This will add the file to the \command{node\_modules} library.

Next include the appropriate file into the \command{assets.js} file inside \command{portal\_client} to make sure it will be injected into the \command{index.html} file during compile time.

The \command{assets.js} file specifies all the vendor libraries that have to be included in the client html during build.

\section{Grunt}
\label{grunt}
Grunt\cite{grunt} allows for live reloading of client code to reflect any changes done on the client javascript/html pages during development. This requires the application to be running 
locally on port 8080. Grunt also has to be installed locally and on the users path to be able to execute properly.

To execute Grunt change directories to the client project \filename{portal\_client} and issue the command \command{grunt onlyServe}. This will start the proxy server and open a web browser 
that points to the proxy process on \command{127.0.0.1 port 9000}. Navigating to this url will load content from the local client content and not from the deployed client content. Making 
changes and saving the client code will automatically cause the site to refresh and will reflect the changes.

The deployed code is all minified and any javascript errors would not be easily debugged. Running grunt makes it reference the source material and allows the developer to debug the 
javascript that was causing the errors and also show up properly in the development console within the browser. 

\section{Settings.xml}
\label{settings.xml}
Settings.xml allows for user specific keys to build the application. Each developer needs this file to build the application property

Sample \command{settings.xml} file can be found in Appendex~\ref{sample-settings.xml}

\section{IDE}

Most modern IDE's such as Eclipse, NetBeans, IntelliJ, can import existing maven projects. Once the project has been checked out, import into the IDE an existin maven project. Eclipse
allows SCM checkout directly from the IDE. 

\portal was developed using Eclipse \EclipseVersion\ and is the recommended IDE of choice. 

\subsection{NetBeans}
\label{netbeans}
While the application was developed using Eclipse, the JPO\footnotemark\ classes were generated using NetBeans as they are well defined. 
\footnotetext{Java Persistence Objects}

To generate the JPO objects load at least the portal\_database project into netbeans. Right click on \filename{net.locusworks.portal.database.entities} package and choose 
\command{New -> Entities Classes From Database}

Set up the connect to connect to the portal database and choose Add All (but then remove \_flyway\_migration table) as shown in Figure~\ref{fig:netbeans-db} then click next


\begin{figure}[htbp]
	\centering
	\scalebox{0.5}{\includegraphics*{figures/netbeans-database.png}}
	\caption{NetBeans Database Connection}
	\label{fig:netbeans-db}
\end{figure}

In the ``Entity Classes'' section, make sure generation type is set to either ``New'' or ``Recreate'' (this can be changed by choosing the \command{\ldots} below the class name).

Make sure ``Generate Named Query Annotations for Persistent Fields'' and ``Generate JAXB Annotations'' are not selected as shown in Figure~\ref{fig:netbeans-ec} then click next

\begin{figure}[htbp]
	\centering
	\scalebox{0.5}{\includegraphics*{figures/netbeans-entityclass.png}}
	\caption{NetBeans Entity Classes}
	\label{fig:netbeans-ec}
\end{figure}

\newpage

In the final window make sure the ``Collection Type'' is set to \command{java.util.list} and only ``Fully Qualified Database Table Names'' and ``Use Column Names in Relationships'' 
are selected as shown
in Figure~\ref{fig:netbeans-mo}. 

This will generate all the JPO classes which map the database tables into java objects.

\begin{figure}[htbp]
	\centering
	\scalebox{0.5}{\includegraphics*{figures/netbeans-mapping.png}}
	\caption{NetBeans Mapping Options}
	\label{fig:netbeans-mo}
\end{figure}