We enforce code style conventions with the [maven checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/). This plugin uses the following components:
* The plugin entry in the parent [pom.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/pom.xml)
* we use the maven *pluginManagement* to set a global configuration for the checkstyle plugin used by all modules
* The module [`famer-checkstyle`](https://git.informatik.uni-leipzig.de/dbs/FAMER/tree/master/famer-checkstyle), holding:
* the [checkstyle.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-checkstyle/src/main/resources/famer/checkstyle.xml): the code conventions the plugin will check
* the [checkstyle-suppressions.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-checkstyle/src/main/resources/famer/checkstyle-suppressions.xml): all exceptions to the conventions which the plugin is going to ignore
* the [famer-idea-codestyle.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-checkstyle/src/main/resources/famer/famer-idea-codestyle.xml): a code style scheme according to the plugin settings for the automatic code checking and formatting on IDE level for Intellij IDEA (Note: this does not cover all conventions, some need to be made manually)
* The plugin entry for each module pom.xml
* this will execute the checkstyle plugin with the global configuration for a module in the `build` life cycle
Additionally, we use the [github spotbugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin/) to check for common bugs in java code. This plugin uses the following components:
* The plugin entry in the parent [pom.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/pom.xml) declared in the *pluginManagement* section
* The plugin entry for each module pom.xml
* this will execute the spotbugs plugin for a module in the `build` life cycle
* the [spotbugs-exclude.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-checkstyle/src/main/resources/famer/spotbugs-exclude.xml): all exceptions which the plugin is going to ignore
## Code styles definitions
This version of checkstyle is based on the Giraph checkstyle configurations. It is a best effort attempt to try to match the Oracle ["Code Conventions for the Java Programming Language"](http://www.oracle.com/technetwork/java/codeconvtoc-136057.html). So for example:
* Names for classes, methods and variables have to use camel-case
* Names for classes have to start with a capital letter
* Constructs like `for` or `if` have to use braces `{}`
* Inner assignments like `isPerfect = isCompletePerfect = isPerfectIsolated = false;` should be avoided
*`Switch` statements should be complete and with independent cases
* ...
## Usage
### IDEA code style scheme
* Add the code style scheme shipped with the [famer-idea-codestyle.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-checkstyle/src/main/resources/famer/famer-idea-codestyle.xml) to your Intellij IDEA IDE:
* Automatic code reformatting according to the code style scheme can be done for selected code with `Code` - `Reformat code` or for whole classes and modules with `Right click` - `Reformat code`
***all modules have already undergone an initial reformatting by now**
### Maven checkstyle plugin and Github spotbugs plugin
* At the moment, the execution for the maven checkstyle plugin and the spotbugs plugin is activated for all modules but for the famer-example module
* This is since the build cycle will stop with an according error, if those plugins find code style violations or bugs
* To activate both plugin, uncomment the following lines in the module pom.xml:
```xml
<!-- uncomment to run maven checkstyle plugin on module with: mvn clean install -DskipTests
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>
<plugin>
<groupId>com.github.spotbugs</groupId>
<artifactId>spotbugs-maven-plugin</artifactId>
</plugin>
-->
```
* in the Terminal, run `mvn clean install -DskipTests` on parent project level
* this will start the build process and creates the target directories for the project holding the compiled java code
* the checkstyle and the spotbugs plugins are associated with the maven `verify` phase which runs befor `install`
* it will first run the maven checkstyle plugin on the module where the plugin is activated
* if the checkstyle plugin found no violations, it will run the spotbugs plugin
*`-DskipTests` omits the unit test execution for a faster result
* if both plugins found no violations, the build will successfully be finished
* Errors thrown by the checkstyle and spotbugs plugins may look look this:
```
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/Cluster2cluster_clusterId.java:10:14: Name 'Cluster2cluster_clusterId' must match pattern '^[A-Z][a-zA-Z0-9]*$'. [TypeName]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/Links2Collections.java:0: File does not end with a newline. [NewlineAtEndOfFile]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/Links2Collections.java:20:39: Name 'edge_type' must match pattern '^[a-z][a-zA-Z0-9]*$'. [LocalVariableName]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/DenotateCluster.java:10:3: Missing a Javadoc comment. [JavadocVariable]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/DenotateCluster.java:12:3: Missing a Javadoc comment. [JavadocMethod]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/DenotateCluster.java:12:34: Name 'SourceNo' must match pattern '^[a-z][a-zA-Z0-9]*$'. [ParameterName]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/DenotateCluster.java:16:3: Missing a Javadoc comment. [JavadocMethod]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/GetClusterEdges.java:17: 'for' construct must use '{}'s. [NeedBraces]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/GetClusterEdges.java:20: 'for' construct must use '{}'s. [NeedBraces]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/ClassifyLinks.java:70:69: '{' is not followed by whitespace. [WhitespaceAround]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/ClassifyLinks.java:73:9: '{' at column 9 should be on the previous line. [LeftCurly]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/ClassifyLinks.java:78:7: '{' at column 7 should be on the previous line. [LeftCurly]
[ERROR] /home/matthias/git/FAMER/famer-common/src/main/java/org/gradoop/famer/common/impl/functions/ClassifyLinks.java:85:3: Missing a Javadoc comment. [JavadocMethod]
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-checkstyle-plugin:3.0.0:check (default) on project famer-common: Failed during checkstyle execution: There are 857 errors reported by Checkstyle 6.18 with famer/checkstyle.xml ruleset. -> [Help 1]
```
***fix _ALL_ the errors in the module you are currently working on and rerun the execution until the build for your module succeeds with _NO_ code style and bug violations**
**Leave the execution for both plugins activated for your module to allow automatic checks for all future code contributions**
# 2. Maven shade plugin for JAR-building
When running the Maven build via `mvn clean install`, the [Maven shade plugin](https://maven.apache.org/plugins/maven-shade-plugin/) will be activated in the preceding package-goal. The plugin is called by the `famer-configuration` module and builds an executable FAMER-jar named `famer-{version}-executable.jar` in the directory `build` in the project root.
This jar contains all necessary dependencies to run FAMER as a Flink job and provides the class [`FamerConfiguration`](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-configuration/src/main/java/org/gradoop/famer/configuration/FamerConfiguration.java) as entry point.
Run FAMER by passing the path to the JSON config file as a command line argument, e.g.:
`./bin/flink run path/to/famer-0.1.0-SNAPSHOT-executable.jar path/to/famer-config.json`
**Note: The Maven shade plugin will replace any already existing `famer-{version}-executable.jar` and backup the original jar as `original-famer-{version}-executable.jar` in the same directory.**
# 3. Maven license plugin
The project is licensed under the [Apache Software License 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt). [Maven License Plugin](https://github.com/mycila/license-maven-plugin) is used to enforce the existence of the license header in each code file. The plugin provides goals like `license:check` which is attached to the `verify` phase of project build, thus if there any missing headers the build will fail. The `license:format` goal can be used to add the header when missing. This plugin reads the `<inceptionYear>2016 - 2020</inceptionYear>` from [pom.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/-/blob/master/pom.xml) and composes the header with its value. This needs to be changed once every year.
The license header is not needed in some files, like `checkstyle.xml`, etc., the plugin configuration in the parent [pom.xml](https://git.informatik.uni-leipzig.de/dbs/FAMER/-/blob/master/pom.xml) allows to exclude those file.
Additionally, [maven checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/) will check the text of the license header if it matches the desired license, the header text is kept in [LICENSE.txt](https://git.informatik.uni-leipzig.de/dbs/FAMER/blob/master/famer-checkstyle/src/main/resources/famer/LICENSE.txt) for comparison and in the `verify` phase it will be compared to the headers in files.
[NOTICE](https://git.informatik.uni-leipzig.de/dbs/FAMER/-/blob/master/NOTICE) and [NOTICE-binary](https://git.informatik.uni-leipzig.de/dbs/FAMER/-/blob/master/NOTICE-binary) files maintain a list of the used dependencies and their licenses, where the latter contain only the dependencies that are shipped with the final JAR file. Please update accordingly when new dependencies are added to the project. For more information please see [here](http://www.apache.org/dev/licensing-howto.html).
Note: To get a quick report of the used dependencies in the project run `mvn project-info-reports:dependency-management` in the parent folder. A report will be generated in the `target` folder on parent level, containing a `site` subfolder with a HTML-based dependency overview. This command may fail is you never run `mvn clean install` at least once before.
