java_leaflet

Java Leaflet (JLeaflet)

A Java library for integrating Leaflet maps into Java applications with full Java Platform Module System (JPMS) support. Now supporting both JavaFX and Vaadin implementations with a unified API.

Project Source Code: https://github.com/makbn/java_leaflet Project Wiki: https://github.com/makbn/java_leaflet/wiki

Java-Leaflet Test

Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps. Weighing just about 38 KB of JS, it has all the mapping features most developers ever need. Leaflet is designed with simplicity, performance and usability in mind. It works efficiently across all major desktop and mobile platforms, can be extended with lots of plugins, has a beautiful, easy to use and well-documented API and a simple, readable source code that is a joy to contribute to.

🏗️ Project Structure

This project is now organized as a multi-module Maven project:

java_leaflet/ ├── jlmap-parent/ # Parent POM ├── jlmap-api/ # Core API and abstractions ├── jlmap-fx/ # JavaFX implementation ├── jlmap-vaadin/ # Vaadin component implementation └── jlmap-vaadin-demo/ # Vaadin demo application

Module Overview

✨ Features

The goal is to match almost all the native Leaflet features across both implementations while maintaining a clean and modular architecture. However, some features may be available at the moment. To see which features are supported in each implementation, refer to the Feature Comparison Table.

📋 Requirements

🚀 Quick Start

JavaFX Implementation

Add the JavaFX dependency to your pom.xml:

 <dependency> <groupId>io.github.makbn</groupId> <artifactId>jlmap-fx</artifactId> <version>2.0.0</version> </dependency>

Vaadin Implementation

Add the Vaadin dependency to your pom.xml:

 <dependency> <groupId>io.github.makbn</groupId> <artifactId>jlmap-vaadin</artifactId> <version>2.0.0</version> </dependency>

Also rememebr to allow the module in your properties file:

# For more information https://vaadin.com/docs/latest/flow/integrations/spring/configuration#special-configuration-parameters vaadin.allowed-packages=io.github.makbn.jlmap.vaadin

Read more about Vaadin configuration here!

📖 Usage Examples

JavaFX Implementation

import io.github.makbn.jlmap.fx.JLMapView; import io.github.makbn.jlmap.JLProperties; import io.github.makbn.jlmap.model.JLLatLng; import javafx.application.Application; import javafx.scene.Scene; import javafx.scene.layout.AnchorPane; import javafx.stage.Stage; public class JavaFXMapExample extends Application { @Override public void start(Stage stage) { // Create a map view JLMapView map = JLMapView.builder() .jlMapProvider(JLMapProvider.MAP_TILER.parameter(new JLMapOption.Parameter("key", MAP_API_KEY)).build()) .startCoordinate(JLLatLng.builder() .lat(51.044) .lng(114.07) .build()) .showZoomController(true) .build(); // Create the scene AnchorPane root = new AnchorPane(map); Scene scene = new Scene(root, 800, 600); stage.setTitle("Java Leaflet Map (JavaFX)"); stage.setScene(scene); stage.show(); } public static void main(String[] args) { launch(args); } }

Vaadin Implementation

import io.github.makbn.jlmap.vaadin.JLMapView; import io.github.makbn.jlmap.JLProperties; import io.github.makbn.jlmap.model.JLLatLng; import com.vaadin.flow.component.orderedlayout.VerticalLayout; import com.vaadin.flow.router.Route; @Route("") public class VaadinMapExample extends VerticalLayout { public VaadinMapExample() { setSizeFull(); // Create a map view mapView = JLMapView.builder() .jlMapProvider(JLMapProvider.MAP_TILER.parameter(new JLMapOption.Parameter("key", MAP_API_KEY)).build()) .startCoordinate(new JLLatLng(48.864716, 2.349014)) // Paris .showZoomController(false) .build(); add(map); expand(map); } }

🎯 Core API Features

Map Control

// Change the current coordinate mapView.setView(JLLatLng.builder() .lng(48.864716) .lat(2.349014) .build()); // Map zoom functionalities map. getControlLayer().setZoom(5); map.getControlLayer().zoomIn(2); map.getControlLayer().zoomOut(1);

Adding Markers

// Add a marker to the UI layer JLMarker marker = map.getUiLayer() .addMarker(JLLatLng.builder() .lat(35.63) .lng(51.45) .build(), "Tehran", true); // Add event listeners marker.setOnActionListener((jlMarker, event) -> { if (event instanceof ClickEvent) { log.info("Marker clicked"); } }); marker.remove(); // Remove the marker

Adding GeoJSON

import io.github.makbn.jlmap.model.JLGeoJsonOptions; // Load GeoJSON with custom styling JLGeoJsonOptions options = JLGeoJsonOptions.builder() .styleFunction(features -> JLOptions.builder() .fill(true) .fillColor(JLColor.fromHex((String) features.get(0).get("fill"))) .fillOpacity((Double) features.get(0).get("fill-opacity")) .stroke(true) .color(JLColor.fromHex((String) features.get(0).get("stroke"))) .build()) .build(); JLGeoJson styledGeoJson = map.getGeoJsonLayer() .addFromUrl("https://example.com/data.geojson", options);

Read more about examples in the Examples and Tutorials page.

Layer Management

The API provides access to different map layers:

🏃‍♂️ Running the Demos

JavaFX Demo

cd jlmap-fx mvn javafx:run

Vaadin Demo

cd jlmap-vaadin-demo mvn spring-boot:run

Then open your browser to http://localhost:8080

🔧 Building from Source

Prerequisites

Build Commands

# Build all modules mvn clean install # Build specific module mvn clean install -pl jlmap-api mvn clean install -pl jlmap-fx mvn clean install -pl jlmap-vaadin # Run tests mvn test # Package mvn package

If you’re migrating from version 1.x:

  1. Update Dependencies: Change from jlmap to jlmap-fx or jlmap-vaadin
  2. Package Updates: Update imports to use the new module structure
  3. Module Declaration: Ensure your project has proper module configuration
  4. Build Configuration: Update Maven configuration for the new dependencies

** Complete Migration Guide** - Detailed step-by-step instructions for migrating from v1.x to v2.0.0

Example Migration

Before (v1.x):

 <dependency> <groupId>io.github.makbn</groupId> <artifactId>jlmap</artifactId> <version>1.9.5</version> </dependency>

After (v2.0.0):

<!-- For JavaFX --> <dependency> <groupId>io.github.makbn</groupId> <artifactId>jlmap-fx</artifactId> <version>2.0.0</version> </dependency> <!-- For Vaadin --> <dependency> <groupId>io.github.makbn</groupId> <artifactId>jlmap-vaadin</artifactId> <version>2.0.0</version> </dependency>

Troubleshooting

Common Issues

  1. Module Not Found: Ensure the correct module is in your dependencies
  2. JavaFX Issues: Verify JavaFX is properly configured for your Java version
  3. Vaadin Issues: Ensure Node.js is installed for frontend compilation
  4. Lombok Issues: Verify annotation processing is properly configured

Module Path Issues

If you encounter module path issues, verify:

# Check if the module is properly packaged jar --describe-module --file target/jlmap-fx-2.0.0.jar jar --describe-module --file target/jlmap-vaadin-2.0.0.jar

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Ensure all tests pass
  5. Submit a pull request

License

Since v2.0.0 This project is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 2.1 - see the LICENSE file for details.

Author

Matt Akbarian (@makbn)

Roadmap

Additional Resources

This site is open source. Improve this page.