Java docs (#129)

Added java docs
Inedo · Mar 20, 2020 · cf2106b · cf2106b
1 parent 66f3fd1
commit cf2106b
Show file tree

Hide file tree

Showing 11 changed files with 713 additions and 74 deletions.
diff --git a/BuildMaster/platforms/java/#.md b/BuildMaster/platforms/java/#.md
@@ -1,65 +1,78 @@
 ---
 title: Java
-subtitle: Java Applications & Maven Goals
+subtitle: Building Java Applications
 sequence: 200
+show-headings-in-nav: true
 ---
 
-You can use BuildMaster to build applications and components written in any language. That includes Java-based projects that use Maven to manage the build automation.
+[Java](https://www.java.com/) is one of the top five programming languages in the software ecosystem, running on billions of devices from global cloud systems to single-board computers like Raspberry Pi. 
 
-[Maven](http://maven.apache.org/) allows a project to build using its project object model (POM) and a set of plugins that are shared by all projects using Maven, providing a uniform build system.  Maven is a project management tool that uses a build lifecycle framework for developers. It is a build automation tool used primarily for Java projects.
+[Jakarta EE](https://jakarta.ee/) is the de-facto set of multi-tier specifications and extensions to Java SE that enables enterprise application services such as:
 
-To build Java-based projects, you can the Maven operation within BuildMaster's [Java extension](https://inedo.com/den/inedox/java) to execute goals and phases.
+{.docs}
+ - Servlets
+ - JavaServer Faces (JSF) *(component-based UI for web apps)*
+ - Web services
+ - Framework libraries & APIs:
+   - Dependency injection
+   - Persistence
+   - Transactions
 
-## What are Maven Phases and Goals?
+Formerly known as Java Enterprise Edition (Java EE) and Java 2 Platform, Enterprise Edition (J2EE), it is sponsored by the [Eclipse Foundation] and contributed to by Oracle.
 
-A Maven _phase_ represents a stage in the Maven build lifecycle. Each Build Lifecycle is Made Up of Phases.
+The most common Java application servers are: 
 
-There are three major _built-in_ Build Life Cycles:
+{.docs} 
+ - [Apache TomEE](java/tomcat)
+ - [Red Hat WildFly](java/wildfly) (formerly JBoss Application Server) 
+ - [JBoss Enterprise Application Platform (EAP)](java/wildfly) (paid version of WildFly)
+ - [Oracle WebLogic](https://www.oracle.com/middleware/technologies/weblogic.html)
+ - [Eclipse Glassfish](https://projects.eclipse.org/proposals/eclipse-glassfish) (formerly Oracle)
+ - [IBM WebSphere](https://www.ibm.com/cloud/websphere-application-platform/)
 
-1. default
-2. clean
-2. site
+When deploying Java locally or to small web servers, the most common web servers are:
 
-The default lifecycle comprises of the following Build Phases:
+{.docs}
+ - [Eclipse Jetty](java/jetty)
+ - [Apache Tomcat](java/tomcat)
 
-```
-- 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.
-```
+## Building Java Applications {#building data-title="Build Process"}
 
-When you run a phase – all goals bound to this phase are executed in order. So to go through the above phases, we just have to call one command:
+Java programs are compiled into bytecode as `.class` files and packaged into one of many types of [JAR files](https://docs.oracle.com/javase/tutorial/deployment/jar/basicsindex.html). At run time, bytecode is interpreted and executed by the Java Virtual Machine ([JVM](https://docs.oracle.com/javase/specs/jvms/se13/html/jvms-1.html#jvms-1.2)). To develop Java, you'll always develop against the [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/javase-jdk13-doc-downloads.html).
 
-`mvn <phase> { Ex: mvn install }`
+Common tools used to build and test Java programs are:
 
-The above command, will start from the `validate` phase and continue until all the phases are executed sequentially until the `install` phase. Maven can either execute a goal or a phase (or even multiple goals or multiple phases) as follows:
+{.docs}
+ - [**javac**](https://docs.oracle.com/en/java/javase/13/docs/specs/man/javac.html) - primary Java compiler included with the JDK
+ - [**Maven**](java/maven) - most common XML-based build and deployment tool with all the support of Ant plus dependency management, packaging, publish support
+ - [**Ant**](java/ant) - basic build tool with customizable XML build tasks
+ - [**Gradle**](java/gradle) - similar to Maven but uses a [Groovy](http://groovy-lang.org/)-based configuration file
+ - [**JUnit**](java/junit) - most common unit test framework for Java applications
 
-`mvn clean install plugin:goal`
+## Automation with BuildMaster {#buildmaster data-title="Automation with BuildMaster"}
 
-## How to Execute a Maven Goal in BuildMaster
+At a high level, the process of building and deploying Java applications with BuildMaster is:
 
-There are two ways to excute a maven goal in BuildMaster. Either with the `Execute-Maven` operation or the `InedoCore::Exec`.  
+{.docs}
+ - Get source code from the source control repository
+ - Compile project with Maven
+ - Capture artifact for deployment
 
-`Excute-Maven` is included in our Java Extension. and Can be executed with this simple OtterScript.  
-```
-Execute-Maven
- (
-     GoalsAndPhases: "<PLUGIN>:<GOAL>"
- );
-```
+## Deploying Java Applications {#deployment data-title="Deployment Process"}
 
-Using the InedoCore::Exec command will require you to [install maven](http://maven.apache.org/) on the build machine. Maven is a Java based tool, therefore JDK (JDK 1.7 or above, preferably JDK 1.8) installation on your system is a pre-requisite.
-```
- InedoCore::Exec
- (
-     FileName: ~\FullPathToMaven\mvn,
-     Arguments: <PLUGIN>:<GOAL>
- );
-```
+Java applications in an enterprise are typically deployed to on-premise or to hosted application servers such as:
 
-_To find out more information about running maven commands you can review [this documentation](http://maven.apache.org/run.html)_
+{.docs}
+ - IBM WebSphere
+ - Oracle WebLogic
+ - Red Hat JBoss/WildFly
+ - Tomcat
+
+Deployment to application servers involves running a host-specific "deploy" command on a remote server, typically with a WAR file as an input argument.
+
+Deploying to web servers is a little different. Deploying to Tomcat servers, for example, follows the common format:
+
+{.docs}
+ - Stop Tomcat services
+ - Deploy WAR file
+ - Start Tomcat services
diff --git a/BuildMaster/platforms/java/ant.md b/BuildMaster/platforms/java/ant.md
@@ -0,0 +1,153 @@
+---
+title: Ant
+subtitle: Building Java Applications with Ant
+sequence: 200
+show-headings-in-nav: true
+---
+
+[Ant](https://ant.apache.org) is a Java-based build tool for Java.
+
+Written in Java, the original author, James Duncan Davidson, said the name is an acronym for "Another Neat Tool." Ant was released on April 19th, 2000, as part of [Tomcat](java/tomcat) 3.1 and was used to build Tomcat and nothing else. Ant was then separated after it's donation to the Apache Software Foundation because it was determined it could fix many issues developers had with Makefiles, and the first official standalone release was Ant 1.1 on July 19th, 2000. It was the most popular build tool for Java until [Maven](java/maven).
+
+Some of Ant's best qualities: 
+  - extremely flexible
+  - does not impose coding conventions
+  - does not impose directory layouts
+
+## Overview & Concepts {#overview data-title="Ant Overview"}
+
+Because Ant is built on Java, it can be run on any OS. Ant uses XML-based configuration files called build files that define a target tree. 
+
+These configuration files are made up of:
+
+{.docs}
+- Project: the master build definition containing all of the targets, tasks, and properties 
+  - Each project defines one or more targets.
+- Targets: a set of tasks you want to be executed
+  - Can depend on other targets
+  - When starting Ant, you select which target(s) you want executed
+- Tasks: a piece of code that can be executed 
+- Properties: key/value pairs used to customize or provide shortcuts to values used within targets and tasks
+  - These can be set:
+    - externally and passed in when calling Ant
+    - internally within a target or task
+
+To extend Ant, users can develop their own "antlibs" containing Ant tasks and types. These are based in Java and have specific interfaces they must implement. For dependency management, use [Apache Ivy](https://ant.apache.org/ivy/).
+
+## Apache Ivy {#ivy data-title="Apachy Ivy"}
+
+[Apache Ivy](https://ant.apache.org/ivy/) is a tool for recording, tracking, resolving, and reporting project dependencies, and it's characterized by flexibility, configurability, and tight integration to Ant.  IT is the best option for managing dependencies when using Ant.
+
+Ivy uses the Maven 2 repository to resolve the dependencies you declare in an Ivy file, and its syntax is very similar to Apache Ant.
+
+## Building with Ant {#building data-title="Building with Ant"}
+
+First, create a build file for Ant. 
+
+A basic build file typically includes these targets:
+
+{.docs}
+- `init`: Creates the build directory structure used by compile 
+- `compile`: Compiles the java files in the src folder into bytecode and outputs them into the build folder
+- `dist`: Packages the build folder into a JAR, WAR, etc... and copies that into the dist folder
+- `clean`: Deletes the build and dist directories
+
+Defining your project default target to be `dist` will simplify executing an Ant build. Additional targets can be included.
+
+### Example Build File
+```
+<project name="ProfitCalcJava" default="dist" basedir=".">
+  <description>
+    simple example build file
+  </description>
+  <!-- set global properties for this build -->
+  <property name="src" location="src"/>
+  <property name="build" location="build"/>
+  <property name="dist" location="dist"/>
+  <property name="version" value="1.0"/>
+
+  <target name="init">
+    <!-- Create the time stamp -->
+    <tstamp/>
+    <!-- Create the build directory structure used by compile -->
+    <mkdir dir="${build}"/>
+  </target>
+
+  <target name="compile" depends="init"
+        description="compile the source">
+    <!-- Compile the Java code from ${src} into ${build} -->
+    <javac srcdir="${src}" destdir="${build}"/>
+  </target>
+
+  <target name="dist" depends="compile"
+        description="generate the distribution">
+    <!-- Create the distribution directory -->
+    <mkdir dir="${dist}/lib"/>
+
+    <!-- Put everything in ${build} into the ProfitCalcJava-${version}.jar file -->
+    <jar jarfile="${dist}/lib/ProfitCalcJava-${version}.jar" basedir="${build}"/>
+  </target>
+
+  <target name="clean" description="clean up">
+    <!-- Delete the ${build} and ${dist} directory trees -->
+    <delete dir="${build}"/>
+    <delete dir="${dist}"/>
+  </target>
+</project>
+```
+
+### Running Ant Via the Command Line
+
+##### Using the Default Target
+```
+ant -buildfile "ProfitCalcJava.build" -Dversion:1.1
+```
+
+##### Specifying Targets
+```
+ant -buildfile "ProfitCalcJava.build" -Dversion:1.1 clean dist
+```
+
+## Executing Ant with BuildMaster {#buildmaster data-title="Ant in BuildMaster"}
+
+Ant must be installed on the build server prior to executing any of these commands. Setting ANT_HOME in the path is preferable, but you can use the AntPath variable function to override it. To do any of this, however, the Java extension must be installed in BuildMaster.
+
+Use the following OtterScript in a deployment plan:
+
+```
+Java::Build-AntProject
+(
+    BuildPath: ProfitCalcJava.build
+    ProjectBuildTarget: dist,
+    ProjectBuildTarget: target,
+    BuildProperties: @(version=$ReleaseNumber.$BuildNumber)
+)
+```
+
+- Running Ant directly:
+```
+Exec "ant -buidfile ProfitCalcJava.build -Dversion:$ReleaseNumber.$BuildNumber dist";
+```
+
+- Example plan that gets the latest source code from Git and captures a Maven artifact as a BuildMaster artifact:
+```
+Git::Get-Source
+(
+    RepositoryUrl: https://github.com/Inedo/ProfitCalcJava.git,
+    Branch: master
+);
+
+Java::Build-AntProject
+{
+    BuildPath: ProfitCalcJava.build
+    BuildTarget: dist
+    ProjectBuildTarget: target,
+    BuildProperties: @(version=$ReleaseNumber.$BuildNumber)
+};
+
+Create-Artifact ProfitCalcJava
+(
+    From: target,
+    Include: @(*.jar, *.war, *.ear)
+);
+```