Skip to content

Commit dd52890

Browse files
makbnmakbn
committed
docs: rewrite README with modular JavaFX guide and modern usage examples
- Overhauled README.md with a new structure, aligned with JPMS and JavaFX 19+ - Added detailed module usage instructions, Maven setup, and quick start guide - Documented map layers, events, and GeoJSON usage more clearly - Updated changelog for v1.9.5 build: migrate project to Java 17 with full JPMS support - Set compiler target to Java 17 in pom.xml - Updated all JavaFX dependencies to use ${javafx.version} property (19.0.2.1) - Added lombok annotation processor to support modular build - Updated maven-compiler-plugin with required --add-modules and --add-opens flags - Added maven-jar-plugin and maven-surefire-plugin configurations for module support - Removed use of internal JavaFX APIs (e.g., WebConsoleListener) for module compatibility
1 parent 5026f52 commit dd52890

File tree

3 files changed

+250
-142
lines changed

3 files changed

+250
-142
lines changed

‎README.md‎

Lines changed: 192 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,170 @@
1-
## Java Leaflet
2-
Java wrapper for Leaflet, JavaScript library for mobile-friendly interactive maps.
1+
# Java Leaflet (JLeaflet)
32

4-
* Current version: **v1.9.4**
5-
* Previous version: [v1..6.0](https://github.com/makbn/java_leaflet/tree/release/1.6.0)
3+
A Java library for integrating Leaflet maps into JavaFX applications with full Java Platform Module System (JPMS) support.
4+
5+
* Current version: **v1.9.5**
66

77
Project Source Code: https://github.com/makbn/java_leaflet
88

99
![Java-Leaflet Test](https://github.com/makbn/java_leaflet/blob/master/.github/doc/app.png?raw=true)
10-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmakbn%2Fjava_leaflet.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmakbn%2Fjava_leaflet?ref=badge_shield)
1110

1211
> 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.
1312
> 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.
1413
14+
## Features
1515

16-
## Getting start
16+
- **Java Platform Module System (JPMS) Compatible**: Fully modularized for Java 17+
17+
- **JavaFX Integration**: Native JavaFX WebView integration
18+
- **Multiple Map Providers**: Support for OpenStreetMap, Mapnik, and other tile providers
19+
- **Interactive Features**: Markers, polygons, polylines, circles, and more
20+
- **Event Handling**: Comprehensive event system for map interactions
21+
- **GeoJSON Support**: Load and display GeoJSON data
22+
- **Customizable**: Extensive customization options for map appearance and behavior
1723

18-
Since you are working on JavaFX application you know you need to have the JavaFX runtime.
19-
Read more about installing JavaFx:
20-
* https://openjfx.io/openjfx-docs/#introduction
24+
## Requirements
2125

22-
To run the [Leaflet example](src/test/java/io/github/makbn/jlmap/Leaflet.java) class you need to set the module path
23-
as VM options:
26+
- **Java**: 17 or higher
27+
- **JavaFX**: 19.0.2.1 or higher
28+
- **Maven**: 3.6+ (for building)
2429

25-
```java
26-
--module-path [PATH_TO_JAVA_FX_LIB_FOLDER]
27-
--add-exports javafx.web/com.sun.javafx.webkit=ALL-UNNAMED
28-
--add-modules=javafx.graphics,javafx.web
29-
```
30+
## Module Information
3031

31-
There is an issue with JavaFX v17.X javafx.web engine and OSM tiles, I tried JavaFX v19.0.2.1 and it works fine!
32+
This project is fully modularized using the Java Platform Module System (JPMS). The module name is `io.github.makbn.jlmap`.
3233

33-
First, you need to initialize an instance of `JLMapView`:
34+
### Module Dependencies
3435

35-
```java
36-
final JLMapView map = JLMapView
37-
.builder()
38-
.mapType(JLProperties.MapType.OSM_MAPNIK)
39-
.showZoomController(true)
40-
.startCoordinate(JLLatLng.builder()
41-
.lat(51.044)
42-
.lng(114.07)
43-
.build())
44-
.build();
36+
The module requires the following dependencies:
4537

46-
```
38+
- **JavaFX Modules**: `javafx.controls`, `javafx.base`, `javafx.swing`, `javafx.web`, `javafx.graphics`
39+
- **JDK Modules**: `jdk.jsobject`
40+
- **Logging**: `org.apache.logging.log4j`, `org.apache.logging.log4j.core`
41+
- **JSON Processing**: `com.google.gson`, `com.fasterxml.jackson.databind`
42+
- **Annotations**: `org.jetbrains.annotations`, `lombok`
4743

48-
Based on Leaflet JS, you can interact with map in different layers. in this project, you can access different functions with this layer:
49-
* `map` for direct changes on map
50-
* `map.getUiLayer()` for changes on UI layer like markers.
51-
* `map.getVectorLayer()` represents the Vector layer on Leaflet map.
52-
* `map.getControlLayer()` represents the control layer for setting the zoom level.
53-
* `map.getGeoJsonLayer()` represents the GeoJson layer.
44+
### Module Exports
5445

46+
The following packages are exported for public use:
5547

56-
### Map functions
48+
- `io.github.makbn.jlmap` - Main package
49+
- `io.github.makbn.jlmap.layer` - Layer management
50+
- `io.github.makbn.jlmap.layer.leaflet` - Leaflet-specific layer interfaces
51+
- `io.github.makbn.jlmap.listener` - Event listeners
52+
- `io.github.makbn.jlmap.model` - Data models
53+
- `io.github.makbn.jlmap.exception` - Custom exceptions
54+
- `io.github.makbn.jlmap.geojson` - GeoJSON support
5755

58-
Some map view functionalities are available in map layer like `setView` or `setMapListener` as a callback for map events:
56+
## Installation
5957

60-
* Change the current coordinate of map center:
58+
### Maven
6159

62-
```java
63-
map.setView(JLLatLng.builder()
64-
.lng(10)
65-
.lat(10)
66-
.build());
60+
Add the following dependency to your `pom.xml`:
61+
62+
```xml
63+
<dependency>
64+
<groupId>io.github.makbn</groupId>
65+
<artifactId>jlmap</artifactId>
66+
<version>1.9.5</version>
67+
</dependency>
6768
```
6869

69-
* Add a listener for map events:
70+
### Module Path
71+
72+
When running your application, ensure you include the module in your module path:
73+
74+
```bash
75+
java --module-path /path/to/jlmap-1.9.5.jar --add-modules io.github.makbn.jlmap your.main.Class
76+
```
77+
78+
## Quick Start
79+
80+
### Basic Map Setup
7081

7182
```java
72-
map.setMapListener(new OnJLMapViewListener() {
73-
@Override
74-
public void mapLoadedSuccessfully(JLMapView mapView) {
75-
76-
}
77-
78-
@Override
79-
public void mapFailed() {
80-
log.error("map failed!");
81-
}
82-
83-
@Override
84-
public void onAction(Event event) {
85-
if (event instanceof MoveEvent moveEvent) {
86-
log.info("move event: " + moveEvent.action() + " c:" + moveEvent.center()
87-
+ " \t bounds:" + moveEvent.bounds() + "\t z:" + moveEvent.zoomLevel());
88-
} else if (event instanceof ClickEvent clickEvent) {
89-
log.info("click event: " + clickEvent.center());
90-
map.getUiLayer().addPopup(clickEvent.center(), "New Click Event!", JLOptions.builder()
91-
.closeButton(false)
92-
.autoClose(false).build());
93-
} else if (event instanceof ZoomEvent zoomEvent) {
94-
log.info("zoom event: " + zoomEvent.zoomLevel());
95-
}
96-
}
83+
import io.github.makbn.jlmap.*;
84+
import io.github.makbn.jlmap.model.JLLatLng;
85+
import javafx.application.Application;
86+
import javafx.scene.Scene;
87+
import javafx.scene.layout.AnchorPane;
88+
import javafx.stage.Stage;
89+
90+
public class MapExample extends Application {
91+
92+
@Override
93+
public void start(Stage stage) {
94+
// Create a map view
95+
JLMapView map = JLMapView.builder()
96+
.mapType(JLProperties.MapType.OSM_MAPNIK)
97+
.startCoordinate(JLLatLng.builder()
98+
.lat(51.044)
99+
.lng(114.07)
100+
.build())
101+
.showZoomController(true)
102+
.build();
103+
104+
// Create the scene
105+
AnchorPane root = new AnchorPane(map);
106+
Scene scene = new Scene(root, 800, 600);
107+
108+
stage.setTitle("Java Leaflet Map");
109+
stage.setScene(scene);
110+
stage.show();
111+
}
112+
113+
public static void main(String[] args) {
114+
launch(args);
115+
}
97116
}
98117
```
99118

100-
Read more about map events from `OnJLMapViewListener.Action`.
119+
Based on Leaflet JS, you can interact with map in different layers. in this project, you can access different functions with this layer:
101120

102-
### UI Layer
121+
* `map` for direct changes on map
122+
* `map.getUiLayer()` for changes on UI layer like markers.
123+
* `map.getVectorLayer()` represents the Vector layer on Leaflet map.
124+
* `map.getControlLayer()` represents the control layer for setting the zoom level.
125+
* `map.getGeoJsonLayer()` represents the GeoJson layer.
103126

104-
Layer for adding/removing markers and popup. you can access UI layer from `map.getUiLayer()`. As an example:
127+
### Adding Markers
105128

106129
```java
130+
// Add a marker to the UI layer
107131
map.getUiLayer()
108132
.addMarker(JLLatLng.builder()
109-
.lat(35.63)
110-
.lng(51.45)
111-
.build(), "Tehran", true)
112-
.setOnActionListener(getListener());
133+
.lat(35.63)
134+
.lng(51.45)
135+
.build(), "Tehran", true);
113136
```
114137

115-
Controlling map's zoom level:
138+
139+
Controlling map's zoom level and coordinate:
116140
```java
141+
// change the current coordinate
142+
map.setView(JLLatLng.builder()
143+
.lng(10)
144+
.lat(10)
145+
.build());
146+
117147
// map zoom functionalities
118148
map.getControlLayer().setZoom(5);
119149
map.getControlLayer().zoomIn(2);
120150
map.getControlLayer().zoomOut(1);
121151
```
122152

153+
### Adding Shapes
154+
155+
```java
156+
// Add a circle
157+
map.getVectorLayer()
158+
.addCircle(JLLatLng.builder()
159+
.lat(35.63)
160+
.lng(51.45)
161+
.build(),
162+
30000,
163+
JLOptions.builder()
164+
.color(Color.BLACK)
165+
.build());
166+
```
167+
123168
you can add a listener for some Objects on the map:
124169

125170
```java
@@ -136,69 +181,85 @@ marker.setOnActionListener(new OnJLObjectActionListener<JLMarker>() {
136181
});
137182
```
138183

184+
## Building from Source
139185

140-
### Vector layer
186+
### Prerequisites
141187

142-
Represents the Vector layer for Leaflet map. Poly lines, Polygons, and shapes are available in this layer.
188+
- Java 17 or higher
189+
- Maven 3.6+
143190

144-
```java
145-
map.getVectorLayer()
146-
.addCircleMarker(JLLatLng.builder()
147-
.lat(35.63)
148-
.lng(40.45)
149-
.build()
150-
);
151-
```
152-
153-
### GeoJson layer
154-
Represents the GeoJson layer for Leaflet map and defines methods for adding and managing
155-
GeoJSON data layers in a Leaflet map.
156-
```java
157-
JLGeoJsonObject geoJsonObject = map.getGeoJsonLayer()
158-
.addFromUrl("https://pkgstore.datahub.io/examples/geojson-tutorial/example/data/db696b3bf628d9a273ca9907adcea5c9/example.geojson");
191+
### Build Commands
159192

160-
```
161-
You can add GeoJson data from three different sources:
162-
* From a file using `map.getGeoJsonLayer().addFromFile([FILE])`
163-
* From a URL using `map.getGeoJsonLayer().addFromUrl([URL])`
164-
* From a GeoJson content `map.getGeoJsonLayer().addFromContent([CONTENT])`
165-
### Styling
193+
```bash
194+
# Clean and compile
195+
mvn clean compile
166196

167-
You can pass `JLOptions` to each method for changing the default style!
197+
# Run tests
198+
mvn test
168199

169-
```java
170-
map.getVectorLayer()
171-
.addCircle(JLLatLng.builder()
172-
.lat(35.63)
173-
.lng(51.45)
174-
.build(), 30000,
175-
176-
JLOptions.builder()
177-
.color(Color.BLACK)
178-
.build()
179-
);
200+
# Package
201+
mvn package
202+
203+
# Install to local repository
204+
mvn install
180205
```
181206

182-
For the map itself, you can choose between themes available in `JLProperties.MapType` class. The `JLProperties.MapType.OSM_MAPNIK` is available to be used without any access key but for the rest of them, you need to define your own map using `JLProperties.MapType` and passing proper list of key-values containing all the necessary access keys.
183-
```java
184-
JLProperties.MapType myMapType = new JLProperties.MapType("HEREv3.terrainDay",
185-
Set.of(new JLMapOption.Parameter("apiKey", "<insert apiKey here>")));
186-
187-
JLMapView map = JLMapView
188-
.builder()
189-
.mapType(myMapType)
190-
.showZoomController(true)
191-
.startCoordinate(JLLatLng.builder()
192-
.lat(51.044)
193-
.lng(114.07)
194-
.build())
195-
.build();
207+
### Module-Aware Building
208+
209+
The project uses Maven's module-aware compilation. The `module-info.java` file defines the module structure and dependencies.
210+
211+
212+
## Migration from Non-Modular Version
213+
214+
If you're migrating from a non-modular version:
215+
216+
1. **Update Dependencies**: Ensure all dependencies are module-compatible
217+
2. **Module Declaration**: Add `module-info.java` to your project
218+
3. **Import Updates**: Update any internal JavaFX imports
219+
4. **Build Configuration**: Update Maven configuration for module support
220+
221+
## Troubleshooting
222+
223+
### Common Issues
224+
225+
1. **Module Not Found**: Ensure the module is in your module path
226+
2. **Internal API Access**: Some JavaFX internal APIs are no longer accessible
227+
3. **Lombok Issues**: Ensure annotation processing is properly configured
228+
229+
### Module Path Issues
230+
231+
If you encounter module path issues, verify:
232+
233+
```bash
234+
# Check if the module is properly packaged
235+
jar --describe-module --file target/jlmap-1.9.5.jar
196236
```
197237

198-
Read more:
238+
## Contributing
239+
240+
1. Fork the repository
241+
2. Create a feature branch
242+
3. Make your changes
243+
4. Ensure all tests pass
244+
5. Submit a pull request
245+
246+
## License
247+
248+
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
249+
250+
## Author
199251

200-
* https://github.com/leaflet-extras/leaflet-providers!
252+
**Mehdi Akbarian Rastaghi** (@makbn)
201253

254+
## Changelog
255+
256+
### Version 1.9.5
257+
- **Major**: Upgraded to Java Platform Module System (JPMS)
258+
- **Major**: Updated to Java 17 compatibility
259+
- **Major**: Removed internal JavaFX API dependencies
260+
- **Enhancement**: Improved module structure and encapsulation
261+
- **Enhancement**: Updated Maven configuration for module support
262+
- **Fix**: Resolved Lombok annotation processing in module environment
202263

203264
## TODO
204265

@@ -209,10 +270,8 @@ Read more:
209270
- [ ] Separating JS and HTML
210271
- [ ] Publishing package on GitHub
211272

212-
**Disclaimer**: I've implemented this project for one of my academic paper in the area of geo-visualization. So, im not contributing actively! One more thing, I'm not a Javascript developer!
213-
214-
215273

274+
**Disclaimer**: I've implemented this project for one of my academic paper in the area of geo-visualization. So, im not contributing actively! One more thing, I'm not a Javascript developer!
216275

217-
## License
218-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fmakbn%2Fjava_leaflet.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fmakbn%2Fjava_leaflet?ref=badge_large)
276+
### Previous Versions
277+
See the [GitHub Branches](https://github.com/makbn/java_leaflet/branches) for previous version information.

0 commit comments

Comments
 (0)