Maven Integration allows BoxLang to seamlessly incorporate Java dependencies into your runtime, expanding your application's capabilities with the vast Java ecosystem.
BoxLang offers seamless integration with , the widely used Java build and dependency management tool. This integration enables you to easily integrate third-party Java libraries into your BoxLang runtime, providing access to the vast Java ecosystem without requiring complex setup procedures.
Overview
The Maven integration in BoxLang works through a simple but powerful mechanism:
Centralized Dependency Management: Use Maven's pom.xml to declare all your Java dependencies
Automatic Download: Maven handles downloading and resolving dependency conflicts
Runtime Integration: BoxLang automatically loads all JARs from the lib/ folder
Simple Workflow: Add dependencies, run mvn install, and start using Java libraries immediately
Installing Maven
Before you can use Maven integration, you need to have Maven installed on your system.
Option 1: Using Chocolatey (Recommended)
choco install maven
Option 2: Using Scoop
scoop install maven
Option 3: Manual Installation
Extract to C:\Program Files\Apache\maven
Add C:\Program Files\Apache\maven\bin to your PATH environment variable
Option 1: Using Homebrew (Recommended)
brew install maven
Option 2: Using MacPorts
sudo port install maven3
Option 3: Using sdkman
sdk install maven {version}
Ubuntu/Debian:
sudo apt update
sudo apt install maven
CentOS/RHEL/Fedora:
sudo yum install maven
# or for newer versions
sudo dnf install maven
Arch Linux:
sudo pacman -S maven
SDKMan:
sdk install maven {version}
Verify Installation
After installation, verify that Maven is working:
mvn -version
You should see output showing the Maven version, Java version, and OS information.
Getting Started
The BoxLang home by default is located in your user's home directory: ~/.boxlang from here is where you will be making maven installation commands. Fire up a terminal and navigate to your BoxLang HOME.
cd $BOXLANG_HOME
// or
cd ~/.boxlang
The BoxLang POM File
BoxLang Home includes a pre-configured pom.xml file specifically designed for runtime dependency management:
Edit the POM: Add your desired dependencies to the <dependencies> section
Install Dependencies: Run mvn install in the BoxLang Home directory
Use Libraries: Start using the Java libraries in your BoxLang code immediately
Adding Dependencies
Finding Dependencies
Adding a Dependency
Edit the pom.xml file and add your dependency inside the <dependencies> section:
<dependencies>
<!-- Apache Commons Text for string manipulation -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-text</artifactId>
<version>1.12.0</version>
</dependency>
<!-- QR Code generation -->
<dependency>
<groupId>com.google.zxing</groupId>
<artifactId>core</artifactId>
<version>3.5.2</version>
</dependency>
<!-- PDF generation with iText -->
<dependency>
<groupId>com.itextpdf</groupId>
<artifactId>itext7-core</artifactId>
<version>8.0.2</version>
<type>pom</type>
</dependency>
</dependencies>
Installing Dependencies
Navigate to your BoxLang Home directory and run:
mvn install
This command will:
Download all declared dependencies and their transitive dependencies
Place all JARs in the lib/ folder
Make them available to the BoxLang runtime
Cleaning Dependencies
To remove all downloaded dependencies:
mvn clean
This will clear the lib/ folder of all Maven-managed JARs.
Practical Examples
Text Processing with Apache Commons
Add powerful text processing capabilities to your BoxLang applications:
<!-- Add to pom.xml -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-text</artifactId>
<version>1.12.0</version>
</dependency>
// Use in BoxLang after mvn install
stringEscapeUtils = new org.apache.commons.text.StringEscapeUtils()
wordUtils = new org.apache.commons.text.WordUtils()
// Escape HTML
safeHTML = stringEscapeUtils.escapeHtml4( "<script>alert('xss')</script>" )
println( "Safe HTML: " & safeHTML )
// Capitalize words
title = wordUtils.capitalizeFully( "the quick brown fox" )
println( "Title: " & title ) // "The Quick Brown Fox"
// Text similarity
similarity = new org.apache.commons.text.similarity.JaroWinklerSimilarity()
score = similarity.apply( "BoxLang", "BoxScript" )
println( "Similarity: " & score )
QR Code Generation
Add QR code generation capabilities to your BoxLang applications:
<!-- Add to pom.xml -->
<dependency>
<groupId>com.google.zxing</groupId>
<artifactId>core</artifactId>
<version>3.5.2</version>
</dependency>
// QR Code generator utility
function createQRCodeGenerator() {
return {
"generate": ( text, size = 300 ) -> {
var writer = new com.google.zxing.qrcode.QRCodeWriter()
var bitMatrix = writer.encode(
text,
new com.google.zxing.BarcodeFormat().QR_CODE,
size,
size
)
return new com.google.zxing.client.j2se.MatrixToImageWriter()
.toBufferedImage( bitMatrix )
},
"saveToFile": ( text, filePath, size = 300 ) -> {
var image = this.generate( text, size )
var file = new java.io.File( filePath )
new javax.imageio.ImageIO().write( image, "PNG", file )
return filePath
},
"generateDataURL": ( text, size = 300 ) -> {
var image = this.generate( text, size )
var baos = new java.io.ByteArrayOutputStream()
new javax.imageio.ImageIO().write( image, "PNG", baos )
var bytes = baos.toByteArray()
var encoder = new java.util.Base64().getEncoder()
return "data:image/png;base64," & encoder.encodeToString( bytes )
}
}
}
// Usage
qrGenerator = createQRCodeGenerator()
// Generate QR code for a URL
qrFile = qrGenerator.saveToFile(
"https://boxlang.ortussolutions.com",
"/tmp/boxlang-qr.png",
400
)
println( "QR code saved to: " & qrFile )
// Generate QR code as data URL for web use
dataURL = qrGenerator.generateDataURL( "BoxLang is awesome!" )
println( "Data URL: " & dataURL.left( 50 ) & "..." )
Regularly check for newer versions of your dependencies:
mvn versions:display-dependency-updates
2. Use Specific Versions
Always specify exact versions rather than ranges:
<!-- Good -->
<version>2.16.0</version>
<!-- Avoid -->
<version>[2.0,3.0)</version>
3. Document Your Dependencies
Add comments explaining why each dependency is needed:
<dependencies>
<!-- Apache Commons Text - Used for advanced string manipulation in templates -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-text</artifactId>
<version>1.12.0</version>
</dependency>
<!-- ZXing - Required for QR code generation in reports -->
<dependency>
<groupId>com.google.zxing</groupId>
<artifactId>core</artifactId>
<version>3.5.2</version>
</dependency>
<!-- iText - PDF generation for invoices and reports -->
<dependency>
<groupId>com.itextpdf</groupId>
<artifactId>itext7-core</artifactId>
<version>8.0.2</version>
<type>pom</type>
</dependency>
<!-- Bouncy Castle - Cryptography for secure operations -->
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk18on</artifactId>
<version>1.77</version>
</dependency>
</dependencies>
4. Test After Adding Dependencies
Always test your BoxLang application after adding new dependencies:
// Test that dependencies loaded correctly
function testDependencies() {
try {
// Test ZXing (QR Codes)
var qrWriter = new com.google.zxing.qrcode.QRCodeWriter()
println( "✅ ZXing QR Code library loaded successfully" )
// Test iText (PDF)
var pdfWriter = new com.itextpdf.kernel.pdf.PdfWriter()
println( "✅ iText PDF library loaded successfully" )
// Test Bouncy Castle
var provider = new org.bouncycastle.jce.provider.BouncyCastleProvider()
println( "✅ Bouncy Castle loaded successfully" )
return true
} catch ( any e ) {
println( "❌ Dependency loading failed: " & e.message )
return false
}
}
testDependencies()
5. Monitor Dependency Size
Keep an eye on the total size of your lib/ folder:
# Check total size of dependencies
du -sh lib/
# List individual JAR sizes
ls -lh lib/*.jar
Troubleshooting
Dependency Conflicts
If you encounter dependency conflicts, use Maven's dependency tree to investigate:
mvn dependency:tree
Class Loading Issues
If classes aren't found after installation:
Verify the JAR is in the lib/ folder
Restart the BoxLang runtime
Check for package name typos in your BoxLang code
If you continue to experience class loading issues, we recommend building BoxLang modules for complete isolation.
Version Compatibility
Some dependencies may require specific versions of Java. Check compatibility before adding:
# Check Java version
java -version
# Check Maven version
mvn -version
Conclusion
Maven integration makes BoxLang incredibly powerful by providing access to the entire Java ecosystem. Whether you need advanced text processing, HTTP clients, database drivers, encryption libraries, or specialized tools, Maven integration makes it simple to add and manage these dependencies.
Key benefits:
🚀 Easy Setup: Simple mvn install command to add dependencies
🔧 Automatic Management: Maven handles dependency resolution and conflicts
📚 Vast Ecosystem: Access to thousands of Java libraries
🔄 Version Control: Easy dependency updates and rollbacks
🧹 Clean Management: Simple cleanup with mvn clean
With Maven integration, BoxLang applications can leverage decades of Java library development, making it possible to build enterprise-grade applications with minimal setup complexity.
Download Maven from
Use to find the dependencies you need. Simply search for the library and copy the Maven coordinates.