Home

Java Leaflet (JLeaflet) Wiki

Welcome to the comprehensive wiki for Java Leaflet - a powerful Java library for integrating Leaflet maps into Java applications with full support for JavaFX and Vaadin frameworks.

📚 Table of Contents

Getting Started

• Getting Started Guide - Quick start guide for JavaFX and Vaadin
• Installation & Setup - Maven dependencies and project setup
• Your First Map - Create your first map in under 5 minutes

Core Concepts

• Architecture Overview - Understanding the multi-module architecture
• API Reference - Complete API documentation
• Layer System - UI, Vector, Control, and GeoJSON layers
• Event Handling - Handling map and object events

Features

• Context Menu System - Adding context menus to map objects
• Journey System - Creating animated map journeys
• Markers & Popups - Interactive map markers
• Vector Shapes - Polygons, polylines, and circles
• GeoJSON Support - Loading and styling GeoJSON data

Examples & Tutorials

• Examples & Tutorials - Comprehensive code examples
• Common Patterns - Best practices and recipes
• Advanced Examples - Complex use cases

Testing & Development

• Testing Guide - Running tests and generating coverage reports
• Contributing - How to contribute to the project

---

🚀 Quick Links

For JavaFX Developers

JLMapView map = JLMapView.builder()
    .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
    .startCoordinate(new JLLatLng(51.505, -0.09))
    .showZoomController(true)
    .build();

For Vaadin Developers

JLMapView map = JLMapView.builder()
    .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
    .startCoordinate(new JLLatLng(48.864716, 2.349014))
    .showZoomController(true)
    .build();

---

📦 What is Java Leaflet?

Java Leaflet is a comprehensive Java library that brings the power of Leaflet.js - the leading open-source JavaScript library for mobile-friendly interactive maps - to Java applications.

Key Features

• ✅ Multi-Framework Support - JavaFX and Vaadin implementations with unified API
• ✅ Java 17+ & JPMS - Full Java Platform Module System support
• ✅ Type-Safe API - Fluent builder pattern with compile-time safety
• ✅ Rich Interactions - Markers, polygons, polylines, circles, context menus
• ✅ Event System - Comprehensive event handling for user interactions
• ✅ GeoJSON Support - Load and style GeoJSON data with custom filters
• ✅ Animation Support - Create animated journeys and transitions
• ✅ Multiple Providers - OpenStreetMap, MapTiler, and custom tile providers

---

🏗️ Project Structure

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

Module Overview

Module	Description	Use Case
jlmap-api	Core abstractions, interfaces, and models	Required by all implementations
jlmap-fx	JavaFX-specific implementation using WebView	Desktop applications
jlmap-vaadin	Vaadin component for web applications	Web applications
jlmap-vaadin-demo	Complete demo showcasing features	Learning and reference

---

📖 Documentation Structure

This wiki is organized into the following sections:

1. Getting Started

Perfect for newcomers to get up and running quickly.

• Installation instructions
• First map creation
• Basic concepts

2. Architecture

Deep dive into the technical architecture.

• Multi-module design
• Layer system
• Transport layer
• Design patterns

3. API Reference

Complete reference documentation.

• All classes and interfaces
• Method signatures
• Usage examples
• Parameters and return types

4. Feature Guides

In-depth guides for specific features.

• Context menus
• Journey animations
• GeoJSON handling
• Event handling

5. Examples & Tutorials

Learn by example.

• Simple examples
• Complex use cases
• Best practices
• Common patterns

6. Testing & Contributing

For developers and contributors.

• Testing guide
• Coverage reports
• CI/CD pipeline
• Contribution guidelines

---

🌟 Version 2.0.0 Highlights

Version 2.0.0 represents a major overhaul of the library:

New Features

• Vaadin Support - Brand new Vaadin component implementation
• Multi-Module Architecture - Clean separation of concerns
• Unified API - Consistent interface across frameworks
• Context Menus - Rich context menu support on all objects
• Journey System - Declarative animated journeys
• Enhanced Documentation - Comprehensive JavaDoc and wiki

Improvements

• Better Modularity - JPMS support for better encapsulation
• Type Safety - Enhanced builder pattern with generics
• Event System - More comprehensive event types
• Performance - Optimized transport layer
• Testing - 74% instruction coverage with 120+ tests

---

📋 Requirements

• Java: 17 or higher
• Maven: 3.6+ (for building)
• JavaFX: 19.0.2.1+ (for JavaFX implementation)
• Vaadin: 24.8.6+ (for Vaadin implementation)

---

🤝 Getting Help

• GitHub Issues: Report bugs or request features
• Wiki: Comprehensive documentation (you're here!)
• Examples: See jlmap-vaadin-demo for working examples
• Source Code: GitHub Repository

---

📄 License

This project is licensed under the GNU Lesser General Public License (LGPL) Version 2.1 or later.

See the LICENSE file for details.

---

👨‍💻 Author

Matt Akbarian (@makbn)

---

🔗 External Resources

• Leaflet.js Documentation: https://leafletjs.com/
• Vaadin Documentation: https://vaadin.com/docs
• JavaFX Documentation: https://openjfx.io/
• GeoJSON Specification: https://geojson.org/

---

🗺️ Navigation

Next: Getting Started Guide →

Start your journey with Java Leaflet by creating your first interactive map!