howto:eclipse [SavaPage

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Using Eclipse for SavaPage Development ======

> This is a guide for SavaPage Development Partners on how to install and configure Eclipse IDE for SavaPage development.

**Status** : reviewed/approved

====== Installation ======

Download latest stable version of [[https://www.eclipse.org|Eclipse IDE for Java EE Developers]].

<code bash>
cd ~/applications
tar -zxvf eclipse-jee-2019-03-R-linux-gtk-x86_64.tar.gz # Ubuntu 16.04, Trisquel 8.0, ...
tar -zxvf eclipse-jee-2020-06-R-linux-gtk-x86_64.tar.gz
</code>

| **Important** | Eclipse-2020-06 (SWT requires GTK 3.20.0) is **not** compatible with Ubuntu 16.04 (GTK  3.18.9). |

<code>
# libgtk check on Ubuntu 20.04.1
rijk@sperwer:~$ dpkg -s libgtk-3-0 | grep '^Version'
Version: 3.24.20-0ubuntu1
</code>


===== Marketplace =====

Install from Eclipse Marketplace:

  * **Checkstyle** Plug-in
    * Make Checkstyle //active// for every Java project project.
    * Use built-in ''Sun Checks - (Global)'' coding convention for all Java projects.
  * **SpotBugs** Eclipse Plugin (formerly known as FindBugs)
    * //Run automatically// for every Java project.
  * **Jaspersoft Studio**
  * **Bash Editor** 

====== Configure ======

===== Show Hidden Files =====

In the package explorer, in the upper right corner of the view, there is a little icon with tool tip text "View Menu". From that menu, select "Filters and Customization". On the "Pre-set filters" tab, uncheck ''.* resources''.

===== Compiler compliance level =====

Select Window -> Preferences -> Java -> Compiler
  * JDK compliance -> Compiler compliance level: ''1.8''

===== Installed JREs =====

Select Window -> Preferences -> Java -> Installed JREs
  * Check that OpenJDK 8 or higher is selected.

^ Important | Make sure the openjdk source package is installed, so its Javadoc is available in Eclipse. |

<code bash>
# if openjdk-11 is installed, then ...
sudo apt install openjdk-11-source
</code>

===== JPA Validation =====

To prevent "Duplicate generator defined in this persistence unit" messages:

Select Window -> Preferences -> Java Persistence ->JPA -> Errors/Warnings 

Under "Queries and generators" mark "Duplicate generator defined" as ''Ignore''.

===== Java Code Style =====

==== Formatter ====

Select Window -> Preferences -> Java -> Code Style -> Formatter
  * Press the 'Import...' button.
  * Select ''savapage-make/eclipse/CodeFormatterProfileJava.xml''.

==== Code Templates ====

Select Window -> Preferences -> Java -> Code Style -> Code Templates -> Comments -> Types
  * Press the 'Edit' button.
  * Change your name in the generated comment from ''@author ${user}'' to ''@author Your Name''.

===== JavaScript Code Style =====

==== Formatter ====

Select Window -> Preferences. Select JavaScript, or Web -> HTML Files -> Client-side JavaScript. Select Code Style -> Formatter
  * Press the 'Import...' button.
  * Select ''savapage-make/eclipse/CodeFormatterProfileJavaScript.xml''.

===== Editors =====

==== Text ====

Select Window -> Preferences -> General -> Editors -> Text Editors
 
Check the following items:

  * Displayed tab width: ''4''
  * Insert spaces for tabs
  * Show print margin
    * Print margin column: ''80''
  * Show line numbers
  * Show whitespace characters
    * Configure visibility
        * show spaces as dots
        * do not show Carriage Return and Line Feed

==== XML ====

Select Window -> Preferences -> XML -> XML Files -> Editor

  * Select: indent using spaces
  * Indentation size: 4
    * Note: when Indentation size cannot be set (known Eclipse bug) open with a text editor this file in your workspace folder: ''.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.wst.xml.core.prefs'' and change/add ''indentationSize=4''
  * Unselect : Format comments

==== Java ====

Select Window -> Preferences -> Java -> Editor -> Save Actions 

//Not applicable in Eclipse 2019-03 (4.11.0) ?//
  * Select checkboxes and press "Formatter"  button.
  * On "Code Organizing" tab check "Remove trailing whitespace" and "Correct indentation" .

//Eclipse 2020-06//
  * [x] Additional actions

==== CSS ====
Select Window -> Preferences -> Web -> CSS Files -> Editor
  * Line width: 72
  * Enable "Insert line break between properties"
  * Enable "Insert whitespace between selectors"
  * Enable "Disable wrapping in sty;e attribute of HTML"
  * Select "Indent using tabs"
  * Capitalization style: all "Lowercase"

==== HTML ====
Select Window -> Preferences -> Web -> HTML Files -> Editor
  * Line width: 72
  * Disable "Split multiple attributes each on a new line"
  * Disable "Align final bracket in multi-line elements tags"
  * Disable "Clear all blank lines"
  * Select "Indent using tabs"
  * Remove Inline Elements like `a`, `li`, `td`, `th`, `br`, `input`, `label`, `select` ...
  * Tag names: Lowercase
  * Attribute names: Lowercase

===== Maven =====

Maven is integrated into Eclipse, but the central repository index needs to be rebuild, so we can select dependencies.

Select Window -> Show View -> Other
  * Type "Maven" in filter, select "Maven Repositories" and press "Open".
  * In the "Maven" tab Expand "Global Repositories".
  * Right-click on "central" and select "Rebuild Index".
 
Also set up index to update on Eclipse start-up. 
  * Select Window -> Preferences -> Maven
  * Check "Download repository index updates on startup".

| **Problem**: Rebuild Index does not have any effect. \\ **Solution**: Delete your cached index. It is somewhere in workspace\ .metadata\ .plugins\org.eclipse.m2e.core\nexus (just delete the entire content of the nexus-folder). See stackoverflow [[https://stackoverflow.com/questions/37749785/eclipse-maven-m2e-doesnt-search-or-download-from-central|37749785]] and [[https://stackoverflow.com/questions/7065478/classic-error-unable-to-update-index-for-centralhttp-repo1-maven-org-maven2|7065478]]. |


====== Projects ======

| ** Prerequisite** | All relevant repositories are cloned into ''~/savapage/repos/'' as explained in the "Getting started" section of ''[[https://gitlab.com/savapage/savapage-make/-/blob/develop/README.md|savapage-make/README.md]]''. |
| **Important** | To contribute code, fork/clone the target SavaPage repositories. Edit/commit in ''develop'' branch, and create Merge Requests to push changes upstream. |
===== savapage-make =====

Create ''savapage-make/.project'' file ... 

<file xml savapage-make/.project>
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
    <name>savapage-make</name>
    <comment/>
    <projects/>
    <buildSpec/>
    <natures/>
</projectDescription>
</file>
 ... and import this project via "Import -> General -> Existing Projects" into Workspace.

==== thirdparty ====

Download/install thirdparty files in addition to SavaPage.

<code bash>
cd ~/savapage
wget https://www.savapage.org/download/development/thirdparty-savapage-fonts.tar.gz -O - | tar -xz
</code>

===== Maven projects =====

Add each Maven project with: File -> Import -> Maven -> Existing Maven Projects.

For each project, select the project in the Project Explorer and select the project properties. 
  * -> Checkstyle : enable "Checkstyle active for this project".
    * "Simple - use the following check configuration for all files: ''Sun Checks -(Global)''
  * -> SpotBugs : enable "Run automatically".

==== savapage-core ====

Select the savapage-core project, right-click and select from main menu: Run As -> Run Configurations... and 
Right-click on "Java Application".
----

Select "New Configuration" and enter the following on tab "Main":

| Name | AppDb |
| Main class | org.savapage.core.cli.AppDb |

On tab "Arguments" enter the following "Program Arguments":
  * ''${string_prompt}'' \\

On tab "Arguments" enter the following "VM arguments":
<code>
-Dserver.home=${project_loc}/../savapage-server/server.home    
-Dlog4j.configuration=file://${project_loc}/../savapage-server/server.home/lib/log4j.properties
</code>
----

Select "New Configuration" and enter the following on tab "Main":

| Name | App |
| Main class | org.savapage.core.cli.server.App |

On tab "Arguments" enter the following "Program Arguments":
  * ''${string_prompt}'' \\

On tab "Arguments" enter the following "VM arguments":
<code>
-Dserver.home=${project_loc}/../savapage-server/server.home    
-Dlog4j.configuration=file://${project_loc}/../savapage-server/server.home/lib/log4j.properties
</code>
----

=== Fonts ===
Embed fonts:
<code bash>
cd ~/savapage/repos/savapage-core
cd src/main/java/org/savapage/core/fonts/
mkdir truetype
# copy font directories from thirdparty
cp -r ~/savapage/thirdparty-savapage/fonts/savapage/0.9.7/* truetype/
</code>
----

=== Java Build Path ===

  * Open the ''savapage-core'' project properties
  * Select the "Java Build Path -> Source" -> ''savapage-core/src/main/java'' source folder.
    * Make sure ''Included: (All)'' and ''Excluded: (None)'' is selected. In this way XML and PNG and .properties files used in the Jasper Reports will be present in the ''Output folder'', as needed for testing in the Eclipse environment.
  * Select the "Java Build Path -> Source" -> ''savapage-core/src/main/resources'' source folder.
    * Make sure ''Included: (All)'' and ''Excluded: (None)'' is selected. In this way the Hibernate ''META-INF/persistence.xml'' files will be present in the ''Output folder'', as needed for testing in the Eclipse environment.

| **Beware** | Java Build Path settings might be (bug?) overwritten when performing a "Maven -> Update project" action. |
| **Note**  | Also see ''savapage-server'' build path problems. |


==== savapage-server ====

  * Copy ''savapage-make/eclipse/server.home.template'' to ''savapage-server/server.home''.
  * Follow the instructions in the ''savapage-make/eclipse/server.home.template.md'' file.

Select the savapage-server project, right-click and select from main menu: Run As -> Run Configurations...

Right-click on "Java Application", select "New Configuration" and enter the following on tab "Main":

| Name | WebServer |
| Main class | org.savapage.server.WebServer |

On tab "Arguments" enter the following "VM arguments":
<code>
-Dserver.home=${project_loc}/server.home 
-Dclient.home=${project_loc}/client.home 
-Dwicket.configuration=development
-Dlog4j.configuration=file://${project_loc}/server.home/lib/log4j.properties
-Dcom.sun.management.config.file=${project_loc}/server.home/jmxremote.properties
-Djava.net.preferIPv4Stack=true
-Djava.io.tmpdir=${project_loc}/server.home/tmp
</code>

| **Java-11** | As explained in ''java --help-extra'' add ''--illegal-access=debug'' as first line to "VM arguments". This will write a stack-trace to stdout so "Illegal reflective access warnings" can be pinpointed. Add ''--add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED'' as second line. |
| **Note** | Use ''-Dwicket.configuration=deployment'' if you want to run in deployment mode. | 

=== Java Build Path ===

  * Open the "savapage-server" project properties
  * Select the "Java Build Path"

**IMPORTANT**
  * To test the ''savapage-ext-*'' projects, their ''target/classes'' folders must be added ("Add Class Folder...") to the "Java Build Path -> Libraries" of the `savapage-server` project.
  * To test the ''savapage-i18n-*'' projects, their ''target/classes'' folders must be added ("Add Class Folder...") to the "Java Build Path -> Libraries" of the ''savapage-server'' project.

**IMPORTANT** : 
  * Select the "Java Build Path -> Source" -> ''savapage-server/src/main/java'' source folder.
  * Make sure ''Included: (All)'' and ''Excluded: (None)'' is selected. In this way the Wicket ''*.html'' files will be present in the ''Output folder'', as needed for testing in the Eclipse environment.
    * As an alternative you can also add ''%%**%%/*.html'' to the ''Included'' section (where ''%%*%%*/*.java'' most probably is already present)
    * Beware: this setting might be (when?) overwritten when performing a "Maven -> Update project" action.

| **Note** | Also see build ''savapage-core'' path problems. |

Create directory ''savapage-server/client.home/'' and copy ''SAVAPAGE.ppd'' to it.
----

=== log4j ===

Copy content from ''savapage-make/setup-template/savapage/server/lib/log4j.properties'' to ''savapage-server/server.home/lib/log4j.properties'' and add/replace:

<file properties server.home/lib/log4j.properties>
# ...
### log messages to stdout  ###
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %5p %c{1}:%L - %m [%t]%n
log4j.appender.stdout.encoding=UTF8
# ...
log4j.rootLogger=ERROR, file, stdout
# ...
# end-of-file
</file>
----

=== server.properties ===

Copy content from: ''savapage-make/setup-template/savapage/server/server.properties'' to ''savapage-server/server.home/server.properties'', and:
  * Modify the IP Port numbers (http, https, raw print)
  * Optionally change other values.

<file properties server.home/server.properties>
server.port=8080
server.ssl.port=8443
server.print.port.raw=9101
</file>

==== savapage-client ====

Create directory ''savapage-client/client.home/'' with the following files:
  * ''client.home/log4j.properties''
    * see snippet below
  * ''client.home/app/config/client.properties''
    * Copy from ''savapage-make/setup-template/savapage/client/app/config/client.properties'' and edit ''server-host'', ''server-port'' and optionally other values.

<file properties savapage-client/client.home/log4j.properties>
### direct log messages to stdout ###
log4j.appender.Stdout=org.apache.log4j.ConsoleAppender
log4j.appender.Stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.Stdout.layout.conversionPattern=%d{ISO8601} %-5p %c{1}:%L - %m [%t]\n

### direct messages to file  ###
log4j.appender.file=org.apache.log4j.RollingFileAppender
log4j.appender.file.MaxFileSize=10MB
log4j.appender.file.MaxBackupIndex=10
log4j.appender.file.File=${app.home}/logs/client.log
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{ISO8601} %5p %c{1}:%L - %m [%t]%n
log4j.appender.file.encoding=UTF8

###
log4j.rootLogger=ERROR, Stdout, file

###
log4j.logger.org.savapage=WARN

#log4j.logger.org.eclipse.jetty=DEBUG
#log4j.logger.org.cometd=DEBUG

# end-of-file
</file>
Select the savapage-client project, right-click and select from main menu: Run As -> Run Configurations...

Right-click on "Java Application", select "New Configuration" and enter the following on tab "Main":

| Name | ClientApp |
| Main class | org.savapage.client.ClientApp |

On tab "Arguments" enter the following "Program Arguments":
  * ''${string_prompt}'' \\

On tab "Arguments" enter the following "VM arguments":
<code>
-Dapp.home=${project_loc}/client.home 
-Dapp.name=savapage-client
-Dlog4j.configuration=file://${project_loc}/client.home/log4j.properties
</code>

==== savapage-util ====

Select the savapage-util project, right-click and select from main menu: Run As -> Run Configurations...

Right-click on "Java Application", select "New Configuration" and enter the following on tab "Main":

| Name | AppUtil |
| Main class | org.savapage.util.App |

On tab "Arguments" enter the following "Program Arguments":
  * ''${string_prompt}'' \\

On tab "Arguments" enter the following "VM arguments":
<code>
-Dserver.home=${project_loc}/../savapage-server/server.home
-Dlog4j.configuration=file://${project_loc}/../savapage-server/server.home/lib/log4j.properties
</code>

====== Running and Debugging ======

| WebServer | Select "savapage-server" from Project Explorer and press F11 |
| ClientApp | Select "savapage-client" from Project Explorer and press F11 |
| App | Select "savapage-core" from Project Explorer -> Run Configurations -> Java Application -> App -> Run |
| AppDb | Select "savapage-core" from Project Explorer -> Run Configurations -> Java Application -> AppDb -> Run |

====== Database Tooling ======
===== Squirrel =====

Download/install from http://www.squirrelsql.org/
  * Select ALL optional plug-ins.

==== Configure Drivers ====

Open the "Drivers" view and configure each driver used.

**Apache Derby** :
  * Select "Apache Derby Embedded", right-click and select "Modify driver..."
  * Select "Extra Class Path" tab and Add the .jar file from the ''.m2'' directory that corresponds with the ''derby.version'' in the ''savapage-core/pom.xml''file. For example:
    * ''~/.m2/repository/org/apache/derby/derby/10.14.2.0/derby10.14.2.0.jar''

**PostgreSQL** :
  * Select "PostgreSQL", right-click and select "Modify driver..."
  * Select "Extra Class Path" tab and Add the .jar file from the ''.m2'' directory that corresponds with the ''derby.version'' in the ''savapage-core/pom.xml''file. For example:
    * ''~/.m2/repository/org/postgresql/postgresql/42.2.14/postgresql-42.2.14.jar''

==== Add Databases ====

Open the "Aliases" View and "Create a New Alias" for your databases. For example:

^ Name ^ Driver ^ URL ^ User Name ^ Password ^ Auto Logon ^
| savapage-dev-derby | Apache Derby Embedded | jdbc:derby:[absolute-path-to]/savapage-server/server.home/data/internal/Derby | | |  Y  |
| savapage-dev-postgres | PostgreSQL | jdbc:postgresql:%%//%%localhost/your-db-name | user | password |  Y  |


https://www.savapage.org/download/design/savapage-database-schema-1.10.pdf