====== Apache Maven ======

https://maven.apache.org/

===== Documentation =====

==== What is Maven? ====

https://maven.apache.org/what-is-maven.html

  * POM = Project Object Model
  * POM + Plugins
  * Maven suggest guidelines for project directory layout

  * Features of Maven
    * simple project setup
    * using across many projects
      * => no ramp-up time for new developers
    * dependency management
    * repository of libs and metadata
    * model-based builds
      * JAR, WAR, ...
    * release management and distribution publication
      * For example:
        * integration with SCMs (e.g. Git)
        * releases based on a tag
        * source ditribution

==== Maven in 5 minutes ====

https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

<code>
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
</code>

  * ''archetype:generate''
    * ''archetype'' - plugin
    * ''generate'' - goal
  * A plugin can be understood as a "collection" of goals.
  * this ''generate'' call has created a [[https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html|standard directory layout]]. Like:
    * my-app
      * pom.xml
      * /src
        * /main
          * /java
            * ...
          * ...
        * /test
          * /java
            * ...
          * ...

  * Build the project:
    * ''mvn package''
      * ''package'' is a //phase// (not a goal as ''archetype:generate'')
      * When a phase is given, Maven executes every phase in the sequence up to and including the one defined.
  * To use proper Java version, ''maven-compiler-plugin'' should be properly configured, because by default it uses Java 8.
  * //Default// Maven build lifecycle:
    * ''validate'': validate the project is correct and all necessary information is available
    * ''compile'': compile the source code of the project
    * ''test'': test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
    * ''package'': take the compiled code and package it in its distributable format, such as a JAR.
    * ''integration-test'': process and deploy the package if necessary into an environment where integration tests can be run
    * ''verify'': run any checks to verify the package is valid and meets quality criteria
    * ''install'': install the package into the local repository, for use as a dependency in other projects locally
    * ''deploy'': done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
  * Other build lifecycles (not in //default//):
    * ''clean'': cleans up artifacts created by prior builds
    * ''site'': generates site documentation for this project
  * Phases are actually mapped to underlying goals. The specific goals executed per phase is dependant upon the packaging type of the project. For example, package executes jar:jar if the project type is a JAR, and war:war if the project type is a WAR.
  * An interesting thing to note is that phases and goals may be executed in sequence:
    * ''mvn clean dependency:copy-dependencies package''
==== Maven Getting Started Guide ====

https://maven.apache.org/guides/getting-started/index.html

  * Maven helps to manage:
    * builds
    * documentation
    * reporting
    * dependencies
    * SCMs
    * releases
    * distribution
  * How to make a first Maven project?
    * archetypes = "templates" of a project
    * ''mvn archetype:generate''
      * Example:
        * ''mvn -B archetype:generate -DgroupId=my.company.app DartifactId=my-app -DarchetypeVersion=1.4 -DarchetypeArtifactId=maven-archetype-quickstart''
    * ''pom.xml''
      * contains Project Object Model
    * ''artifactId'' 
      * used for the names of project artifacts
        * e.g. primary artifact (typically JAR): ''myapp-1.0.jar''
    * properties
      * value placeholders accessible anywhere within a POM
  * How do I compile my application sources?
    * ''mvn compile''
    * ''mvn test''
      * compile + execute unit tests
    * ''mvn test-compile''
      * compile unit tests (without executing)
  * How do I create a JAR and install it in my local repository?
    * ''mvn package''
      * packages JAR in "target" directory
    * ''mvn install''
      * installs the JAR in the local repo (default: ''${user.home}/.m2/repository'')
  * How do I use plugins?
    * ''configuration'' element applies the given parameters to every goal from the plugin
  * How do I add resources to my JAR?
    * use standard directory layout
      * ''/src/main/resources''
        * -> goes to the root of JAR
      * ''/src/test/resources''
        * can be addressed in Java code for example as:
          * ''InputStream in = getClass().getResourceAsStream("/test.properties");''
  * How do I filter resource files?
    * To reference a property which value will be known firstly at the build time use ''${<property_name>}''
    * The value of such property can be defined in:
      * pom.xml
        * ''${<property_name>}''
          * e.g. ''${project.name}''
      * settings.xml
        * ''${settings.<property_name>}''
          * e.g.''${settings.localRepository}''
      * external properties file
      * system property
  * How do I use external dependencies?
    * ''dependencies'' section in pom.xml lists all external dependencies
    * each dependency entry defines at least:
      * groupId
      * artifactId
      * version
      * scope
        * e.g. ''test'' or ''compile''
    * dependencies will be fetched from local repo (default: ''${user.home}/.m2/repository'')
      * with command: ''mvn install''
    * if dependency is not in local repo, it will be fetched from a remote repo (by default Maven Central: https://repo.maven.apache.org/maven2)
  * How do I deploy my JAR in my remote repository?
    * configure repo URL in the ''pom.xml''
    * authentication info in ''settings.xml''
  * How do I build more than one project at once?
    * ...

. . .

=== The Build Lifecycle ===

https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html

Three built-in build lifecycles: 
  * default
    * The default lifecycle handles your project deployment
  * clean
    * the clean lifecycle handles project cleaning
  * site
    * the site lifecycle handles the creation of your project's web site.

The full [[https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#lifecycle-reference|Lifecycle reference]].

Default lifecycle:

  * ''validate'' - validate the project is correct and all necessary information is available
  * ''compile'' - compile the source code of the project
  * ''test'' - test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
  * ''package'' - take the compiled code and package it in its distributable format, such as a JAR.
  * ''verify'' - run any checks on results of integration tests to ensure quality criteria are met
  * ''install'' - install the package into the local repository, for use as a dependency in other projects locally
  * ''deploy'' - done in the build environment, copies the final package to the remote repository for sharing with other developers and projects.

===== Misc =====

  * [[https://maven.apache.org/maven-release/maven-release-plugin/|Maven Release Plugin]]
    * [[https://maven.apache.org/maven-release/maven-release-plugin/usage.html|Maven Release Plugin - Usage]]

  * [[https://maven.apache.org/guides/introduction/introduction-to-the-pom.html|Introduction to the POM]]