- Running a Maven Project from the Command Line (and Building Jar Files)
- Creating a New Maven Project#
- Compiling and Packaging Our JAR File#
- Running Our Code#
- Adding More Classes#
- Running Unit Tests#
- Running Single Test Classes or Methods#
- Adding Dependencies with the Maven Assembly Plugin#
- Adding Command Line Arguments#
Running a Maven Project from the Command Line (and Building Jar Files)
This tutorial will show you how to run a basic Java Maven project on the command line (as opposed to on an IDE).
- Create a new maven project
- Compile, package, and execute your Java code from an executable JAR file
- Run unit tests for your code
- Add external dependencies to your project
All of these tasks will be done on the command line, so that you can have a better idea on what’s going on under the hood, and how you can run a Java application without needing an IDE like Eclipse or IntelliJ.
If you just want to see the example code, you can view it on Github
Creating a New Maven Project#
If you haven’t already, install OpenJDK on your system, after which you can install maven.
First, let’s create a new project folder using the maven command line tools:
mvn -B archetype:generate -DgroupId=com.sohamkamani -DartifactId=mvn-example -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 I’ve used a groupID corresponding to my domain (sohamkamani.com), you should replace this with your own choice
This generates a new project folder with the following structure:
mvn-example ├── pom.xml └── src ├── main │ └── java │ └── com │ └── sohamkamani │ └── App.java └── test └── java └── com └── sohamkamani └── AppTest.java App.java contains simple code that prints Hello World! when run.
Compiling and Packaging Our JAR File#
Before running a Java application in production, we’ll need to compile the Java code into byte-code that can be run on the JVM.
If we have multiple classes and folder (which we most likely will), we have to package the compiled code into a common format (like a .jar file).
We can perform compilation and packaging by running the following command:
We can combine these two commands by running mvn package .
Since compile and package are part of the same lifecycle, running mvn package will execute all lifecycle steps upto package , which includes the compile step
Running this command will create a bunch of files in a new target directory:
mvn-example ├── pom.xml ├── src/. └── target ├── classes │ └── com │ └── sohamkamani │ └── App.class ├── test-classes │ └── com │ └── sohamkamani │ └── AppTest.class └── mvn-example-1.0-SNAPSHOT.jar Some auxillary files are omitted from here for the sake of clarity
The JAR file is the final output that can be executed by the JVM. However, we still have to perform some additional steps before we can run our code.
Running Our Code#
We can use the java command to execute our JAR file:
java -jar target/mvn-example-1.0-SNAPSHOT.jar If we run this now, we will get the following error:
no main manifest attribute, in target/tmp-mvn-example-1.0-SNAPSHOT.jar This is because the JAR file doesn’t know the entry point, so it has no idea where the main method is.
We can make use of the Maven JAR plugin, which gives us additional capabilities to build JAR files.
We can add the following configuration as a child of the tag:
--> org.apache.maven.plugins maven-jar-plugin 3.1.0 true com.sohamkamani.App
We can now rebuild the project by running:
The clean subcommand removes previous artifacts in the target directory, such as the previous stale JAR file
Next, we can execute the JAR file by running:
java -jar target/mvn-example-1.0-SNAPSHOT.jar Which will give us the output:
Adding More Classes#
To organize code better, we can add more classes to our project. These will be compiled and packaged along with the rest of the code automatically.
To illustrate, let’s create a new class called Calculator within src/main/java/com/sohamkamani/Calculator.java :
package com.sohamkamani; public class Calculator public static int add(int n1, int n2) return n1 + n2; > > This is a simple class with a single static method that adds two numbers.
We can now use this class within our App class:
public class App public static void main(String[] args) // Now, we will print "Hello World!" along with the result of the add method System.out.printf("Hello World! %d", Calculator.add(4, 5)); > > Running Unit Tests#
Maven can also be used to run tests that we’ve defined in our project.
By convention, all tests reside within the src/test directory.
We can now create a unit test for the Calculator.add method within src/test/java/com/sohamkamani/CalculatorTest.java :
package com.sohamkamani; // the JUnit library is used for testing import static org.junit.Assert.assertEquals; import org.junit.Test; public class CalculatorTest @Test public void ShouldAdd() assertEquals(2, Calculator.add(1, 1)); > > By default, the maven project folder comes bundled with the JUnit library for running unit tests
To run tests, we can run the mvn test command — this will run all tests, tell us how many passed and failed, and give us more information about the failed tests.
In our case, if we run the tests, we will get the following output:
[INFO] ------------------------------------------------------- [INFO] T E S T S [INFO] ------------------------------------------------------- [INFO] Running com.sohamkamani.CalculatorTest [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.015 s - in com.sohamkamani.CalculatorTest [INFO] [INFO] Results: [INFO] [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 [INFO] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.086 s [INFO] Finished at: 2023-06-30T13:07:02+05:30 [INFO] ------------------------------------------------------------------------ And, if we change the test to fail:
public class CalculatorTest @Test public void ShouldAdd() // this is wrong, and should fail assertEquals(3, Calculator.add(1, 1)); > > The we will get some additional information about the failed test:
[INFO] ------------------------------------------------------- [INFO] T E S T S [INFO] ------------------------------------------------------- [INFO] Running com.sohamkamani.CalculatorTest [ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.017 s but was: at com.sohamkamani.CalculatorTest.ShouldAdd(CalculatorTest.java:11) [INFO] [INFO] Results: [INFO] [ERROR] Failures: [ERROR] CalculatorTest.ShouldAdd:11 expected: but was: [INFO] [ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0 [INFO] [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.006 s [INFO] Finished at: 2023-06-30T13:08:21+05:30 [INFO] ------------------------------------------------------------------------ Running Single Test Classes or Methods#
When running tests in the previous section, we ran all tests in the project. However, we can also run a single test class or method by specifying the class name or method name:
# Running all tests in a single class mvn test -Dtest=MyClassName # Running a single test method mvn test -Dtest=MyClassName#myTestMethod For example, let’s say we had another test class called FailedTest in the same test package:
src/test └── java └── com └── sohamkamani ├── CalculatorTest.java └── FailedTest.java This class contains a single test which always fails:
public class FailedTest @Test public void alwaysFails() Assert.fail("This test should fail"); > > In this case, we only want to run the tests in CalculatorTest.java , and not FailedTest.java . We can do this by specifying the class name:
mvn test -Dtest=CalculatorTest This will run all test methods within the CalculatorTest class, and ignore all other classes.
Now, let’s say we add a new test method called ShouldAddNegativeValues to CalculatorTest.java :
public class CalculatorTest @Test public void ShouldAdd() assertEquals(2, Calculator.add(1, 1)); > @Test public void ShouldAddNegativeValues() assertEquals(-2, Calculator.add(-1, -1)); > > If we only want to test this single method, we can run:
mvn test -Dtest="CalculatorTest#ShouldAddNegativeValues" Isolating tests in this way can be useful when debugging, since running all the tests every time can be time consuming and make it harder to find the issue when a test fails.
Adding Dependencies with the Maven Assembly Plugin#
Let’s look at how to add dependencies and package them in our JAR file.
For most applications need external libraries (like Spring Boot or Apache Commons) to implement common functionality. Maven allows us to install these dependencies by specifying them in our pom.xml file.
For this example, let’s install the Cowsay library, which will display our output as a quote from a friendly cartoon figure of a cow.
First, we have to add Cowsay as a dependency in our pom.xml file:
junit junit 4.11 test com.github.ricksbrown cowsay 1.1.0 lib Next, we can use the Cowsay.say method within our main method to print the final output string:
package com.sohamkamani; // import Cowsay class from the library import com.github.ricksbrown.cowsay.Cowsay; public class App public static void main(String[] args) int result = Calculator.add(4, 5); // We can specify the arguments and get the display // string from the `Cowsay.say` method String[] cowArgs = new String[] String.valueOf(result) >; String cowString = Cowsay.say(cowArgs); // print the final output string System.out.printf(cowString); > > However, there’s a problem - If we recompile our code and try to run the app now, we will get an error:
$ mvn clean compile package $ java -jar target/mvn-example-1.0-SNAPSHOT.jar Exception in thread "main" java.lang.NoClassDefFoundError: com/github/ricksbrown/cowsay/Cowsay at com.sohamkamani.App.main(App.java:13) Caused by: java.lang.ClassNotFoundException: com.github.ricksbrown.cowsay.Cowsay at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641) at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188) at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520) . 1 more It looks like the Java class loader couldn’t find the classes for the Cowsay library, even though we added it as a dependency in the pom.xml file.
This happens because by default, maven doesn’t bundle the dependency class files along with the application code. To enable this, we can use the maven-assembly-plugin.
This plugin includes all of our applications dependencies into the JAR file. This increases its overall size, but ensures that we can run it as a standalone executable using the java -jar command.
Let’s add the Maven assembly plugin in the pom.xml build definition:
org.apache.maven.plugins maven-jar-plugin 3.1.0 true com.sohamkamani.App maven-assembly-plugin com.sohamkamani.App jar-with-dependencies To assemble our JAR file, we can run the assembly:single goal after the compile goal:
mvn clean compile assembly:single This creates a new JAR file in the target directory that you can run using the java -jar command:
$ java -jar target/mvn-example-1.0-SNAPSHOT-jar-with-dependencies.jar ___ < 9 >--- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || || Adding Command Line Arguments#
We can pass in custom arguments directly from the command line when we run the java command.
java -jar target/mvn-example-1.0-SNAPSHOT-jar-with-dependencies.jar lorem ipsum The lorem and ipsum strings can be accessed within the main method using the args array:
public static void main(String[] args) // args is the array of command line arguments // in this case, args[0] = "lorem" and args[1] = "ipsum" > We can pass in any number of arguments, and access them in this way.
As an example, we can modify our code so that it prints the first argument as a famous quote, and the second argument as the author:
public class App public static void main(String[] args) // first, we should check if the user has provided the correct number of arguments if (args.length != 2) // if not, we should print a usage message and exit System.out.println( "Usage: java -jar target/cowsay-1.0-SNAPSHOT.jar \"quote\" \"author\""); System.exit(1); > String quote = args[0]; String author = args[1]; String[] cowArgs = new String[] quote, " --" + author>; String cowString = Cowsay.say(cowArgs); System.out.printf(cowString); > > Now, if we compile and run the application with the correct number of arguments, we will get the following output:
java -jar target/mvn-example-1.0-SNAPSHOT-jar-with-dependencies.jar "e=mc2" "Albert Einstein" _________________________ < e=mc2 --Albert Einstein >------------------------- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || || You can view the complete example code for this post on Github
How do you organize your Java projects? Do you ever use the command line for common tasks? Let me know in the comments!