Skip to content

Commit 51176aa

Browse files
makbnmakbn
committed
added migration guid
1 parent 5eb3f48 commit 51176aa

2 files changed

Lines changed: 363 additions & 1 deletion

File tree

‎MIGRATION_GUIDE.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
# Migration Guide: JavaFX Module (v1.x → v2.0.0)
2+
3+
This guide helps you migrate your JavaFX applications from Java Leaflet v1.x to v2.0.0. The migration is **minimal** and focused - most of your existing code will work without changes.
4+
5+
## 🚀 **What's New in v2.0.0**
6+
7+
- **Multi-Module Architecture**: Clean separation between API, JavaFX, and Vaadin implementations
8+
- **Vaadin Support**: New Vaadin component implementation alongside existing JavaFX support
9+
- **Unified API**: Consistent interface across different UI frameworks
10+
- **Enhanced Modularity**: Better separation of concerns and extensibility
11+
- **Modern Java**: Full Java 17+ and JPMS support
12+
13+
## 🔄 **Migration Overview**
14+
15+
| Component | v1.x | v2.0.0 | Change Required |
16+
|-----------|------|---------|-----------------|
17+
| **Main Class** | `io.github.makbn.jlmap.JLMapView` | `io.github.makbn.jlmap.fx.JLMapView` | ✅ **Yes** |
18+
| **Maven Artifact** | `jlmap` | `jlmap-fx` | ✅ **Yes** |
19+
| **API Classes** | `io.github.makbn.jlmap.*` | `io.github.makbn.jlmap.*` | ❌ **No** |
20+
| **Usage Code** | All existing code | All existing code | ❌ **No** |
21+
22+
## 📋 **Step-by-Step Migration**
23+
24+
### **Step 1: Update Maven Dependency**
25+
26+
**Before (v1.x):**
27+
```xml
28+
<dependency>
29+
<groupId>io.github.makbn</groupId>
30+
<artifactId>jlmap</artifactId>
31+
<version>1.9.5</version>
32+
</dependency>
33+
```
34+
35+
**After (v2.0.0):**
36+
```xml
37+
<dependency>
38+
<groupId>io.github.makbn</groupId>
39+
<artifactId>jlmap-fx</artifactId>
40+
<version>2.0.0</version>
41+
</dependency>
42+
```
43+
44+
### **Step 2: Update Import Statement**
45+
46+
**Before (v1.x):**
47+
```java
48+
import io.github.makbn.jlmap.JLMapView;
49+
```
50+
51+
**After (v2.0.0):**
52+
```java
53+
import io.github.makbn.jlmap.fx.JLMapView;
54+
```
55+
56+
### **Step 3: Update Module Declaration (if using JPMS)**
57+
58+
**Before (v1.x):**
59+
```java
60+
module your.module.name {
61+
requires io.github.makbn.jlmap;
62+
// ... other requires
63+
}
64+
```
65+
66+
**After (v2.0.0):**
67+
```java
68+
module your.module.name {
69+
requires io.github.makbn.jlmap.fx;
70+
// ... other requires
71+
}
72+
```
73+
74+
## 📖 **Complete Migration Examples**
75+
76+
### **Example 1: Basic Map Setup**
77+
78+
**Before (v1.x):**
79+
```java
80+
import io.github.makbn.jlmap.JLMapView;
81+
import io.github.makbn.jlmap.JLProperties;
82+
import io.github.makbn.jlmap.model.JLLatLng;
83+
import javafx.application.Application;
84+
import javafx.scene.Scene;
85+
import javafx.scene.layout.AnchorPane;
86+
import javafx.stage.Stage;
87+
88+
public class MapExample extends Application {
89+
90+
@Override
91+
public void start(Stage stage) {
92+
// Create a map view
93+
JLMapView map = JLMapView.builder()
94+
.mapType(JLProperties.MapType.OSM_MAPNIK)
95+
.startCoordinate(JLLatLng.builder()
96+
.lat(51.044)
97+
.lng(114.07)
98+
.build())
99+
.showZoomController(true)
100+
.build();
101+
102+
// Create the scene
103+
AnchorPane root = new AnchorPane(map);
104+
Scene scene = new Scene(root, 800, 600);
105+
106+
stage.setTitle("Java Leaflet Map");
107+
stage.setScene(scene);
108+
stage.show();
109+
}
110+
111+
public static void main(String[] args) {
112+
launch(args);
113+
}
114+
}
115+
```
116+
117+
**After (v2.0.0):**
118+
```java
119+
import io.github.makbn.jlmap.fx.JLMapView; // ← Only this import changes
120+
import io.github.makbn.jlmap.JLProperties; // ← No change
121+
import io.github.makbn.jlmap.model.JLLatLng; // ← No change
122+
import javafx.application.Application;
123+
import javafx.scene.Scene;
124+
import javafx.scene.layout.AnchorPane;
125+
import javafx.stage.Stage;
126+
127+
public class MapExample extends Application {
128+
129+
@Override
130+
public void start(Stage stage) {
131+
// Create a map view - EXACTLY the same code!
132+
JLMapView map = JLMapView.builder()
133+
.mapType(JLProperties.MapType.OSM_MAPNIK)
134+
.startCoordinate(JLLatLng.builder()
135+
.lat(51.044)
136+
.lng(114.07)
137+
.build())
138+
.showZoomController(true)
139+
.build();
140+
141+
// Create the scene - EXACTLY the same code!
142+
AnchorPane root = new AnchorPane(map);
143+
Scene scene = new Scene(root, 800, 600);
144+
145+
stage.setTitle("Java Leaflet Map");
146+
stage.setScene(scene);
147+
stage.show();
148+
}
149+
150+
public static void main(String[] args) {
151+
launch(args);
152+
}
153+
}
154+
```
155+
156+
### **Example 2: Advanced Map Usage**
157+
158+
**Before (v1.x):**
159+
```java
160+
import io.github.makbn.jlmap.JLMapView;
161+
import io.github.makbn.jlmap.model.JLLatLng;
162+
import io.github.makbn.jlmap.model.JLOptions;
163+
import io.github.makbn.jlmap.listener.OnJLMapViewListener;
164+
165+
public class AdvancedMapExample {
166+
167+
public void setupMap() {
168+
JLMapView map = JLMapView.builder()
169+
.mapType(JLProperties.MapType.OSM_MAPNIK)
170+
.startCoordinate(new JLLatLng(35.63, 51.45))
171+
.showZoomController(true)
172+
.build();
173+
174+
// Add markers
175+
map.getUiLayer().addMarker(
176+
new JLLatLng(35.63, 51.45),
177+
"Tehran",
178+
true
179+
);
180+
181+
// Add shapes
182+
map.getVectorLayer().addCircle(
183+
new JLLatLng(35.63, 51.45),
184+
30000,
185+
JLOptions.DEFAULT
186+
);
187+
188+
// Set view
189+
map.setView(new JLLatLng(10, 10));
190+
map.getControlLayer().setZoom(5);
191+
}
192+
}
193+
```
194+
195+
**After (v2.0.0):**
196+
```java
197+
import io.github.makbn.jlmap.fx.JLMapView; // ← Only this import changes
198+
import io.github.makbn.jlmap.model.JLLatLng; // ← No change
199+
import io.github.makbn.jlmap.model.JLOptions; // ← No change
200+
import io.github.makbn.jlmap.listener.OnJLMapViewListener; // ← No change
201+
202+
public class AdvancedMapExample {
203+
204+
public void setupMap() {
205+
// EXACTLY the same code!
206+
JLMapView map = JLMapView.builder()
207+
.mapType(JLProperties.MapType.OSM_MAPNIK)
208+
.startCoordinate(new JLLatLng(35.63, 51.45))
209+
.showZoomController(true)
210+
.build();
211+
212+
// EXACTLY the same code!
213+
map.getUiLayer().addMarker(
214+
new JLLatLng(35.63, 51.45),
215+
"Tehran",
216+
true
217+
);
218+
219+
// EXACTLY the same code!
220+
map.getVectorLayer().addCircle(
221+
new JLLatLng(35.63, 51.45),
222+
30000,
223+
JLOptions.DEFAULT
224+
);
225+
226+
// EXACTLY the same code!
227+
map.setView(new JLLatLng(10, 10));
228+
map.getControlLayer().setZoom(5);
229+
}
230+
}
231+
```
232+
233+
## 🔍 **What Stays the Same**
234+
235+
✅ **No changes needed for:**
236+
237+
### **API Classes**
238+
- `io.github.makbn.jlmap.JLProperties`
239+
- `io.github.makbn.jlmap.model.*` (JLLatLng, JLOptions, JLColor, etc.)
240+
- `io.github.makbn.jlmap.listener.*` (OnJLMapViewListener, OnJLObjectActionListener, etc.)
241+
- `io.github.makbn.jlmap.layer.leaflet.*` (interfaces)
242+
- `io.github.makbn.jlmap.geojson.*` (GeoJSON support)
243+
- `io.github.makbn.jlmap.exception.*` (exceptions)
244+
245+
### **Functionality**
246+
- Builder pattern usage
247+
- Method calls and API usage
248+
- Event handling and listeners
249+
- Layer management (UI, Vector, Control, GeoJSON)
250+
- Model classes and builders
251+
- Properties and configuration
252+
- Map interactions and controls
253+
254+
## 🏗️ **Project Structure Changes**
255+
256+
### **v1.x (Single Module)**
257+
```
258+
java_leaflet/
259+
├── src/
260+
│ └── main/java/io/github/makbn/jlmap/
261+
│ ├── JLMapView.java ← Main class
262+
│ ├── JLProperties.java ← Properties
263+
│ ├── model/ ← Models
264+
│ ├── layer/ ← Layers
265+
│ └── listener/ ← Listeners
266+
└── pom.xml
267+
```
268+
269+
### **v2.0.0 (Multi-Module)**
270+
```
271+
java_leaflet/
272+
├── jlmap-parent/ ← Parent POM
273+
├── jlmap-api/ ← Core API
274+
│ └── src/main/java/io/github/makbn/jlmap/
275+
│ ├── JLProperties.java ← Properties (same)
276+
│ ├── model/ ← Models (same)
277+
│ ├── layer/ ← Layers (same)
278+
│ └── listener/ ← Listeners (same)
279+
├── jlmap-fx/ ← JavaFX Implementation
280+
│ └── src/main/java/io/github/makbn/jlmap/fx/
281+
│ └── JLMapView.java ← Main class (moved here)
282+
├── jlmap-vaadin/ ← Vaadin Implementation
283+
└── jlmap-vaadin-demo/ ← Vaadin Demo
284+
```
285+
286+
## 🚨 **Common Migration Issues**
287+
288+
### **Issue 1: Class Not Found**
289+
```
290+
Error: cannot find symbol: class JLMapView
291+
```
292+
293+
**Solution:** Update import to `io.github.makbn.jlmap.fx.JLMapView`
294+
295+
### **Issue 2: Module Not Found**
296+
```
297+
Error: module not found: io.github.makbn.jlmap
298+
```
299+
300+
**Solution:** Update module-info.java to `requires io.github.makbn.jlmap.fx;`
301+
302+
### **Issue 3: Maven Dependency Resolution**
303+
```
304+
Error: Could not resolve dependency io.github.makbn:jlmap
305+
```
306+
307+
**Solution:** Change artifactId from `jlmap` to `jlmap-fx`
308+
309+
## 🧪 **Testing Your Migration**
310+
311+
### **1. Build Test**
312+
```bash
313+
mvn clean compile
314+
```
315+
316+
### **2. Runtime Test**
317+
```bash
318+
mvn javafx:run
319+
```
320+
321+
### **3. Module Test (if using JPMS)**
322+
```bash
323+
jar --describe-module --file target/jlmap-fx-2.0.0.jar
324+
```
325+
326+
## 📚 **Additional Resources**
327+
328+
- **API Documentation**: See the `jlmap-api` module for core interfaces
329+
- **JavaFX Examples**: See the `jlmap-fx` module for JavaFX usage
330+
- **Vaadin Examples**: See the `jlmap-vaadin-demo` for Vaadin usage
331+
- **Leaflet Documentation**: [https://leafletjs.com/](https://leafletjs.com/)
332+
333+
## 🎯 **Migration Checklist**
334+
335+
- [ ] Update Maven dependency from `jlmap` to `jlmap-fx`
336+
- [ ] Update import from `io.github.makbn.jlmap.JLMapView` to `io.github.makbn.jlmap.fx.JLMapView`
337+
- [ ] Update module-info.java (if using JPMS) from `requires io.github.makbn.jlmap` to `requires io.github.makbn.jlmap.fx`
338+
- [ ] Test compilation with `mvn clean compile`
339+
- [ ] Test runtime with `mvn javafx:run`
340+
- [ ] Verify all existing functionality works as expected
341+
342+
## 💡 **Pro Tips**
343+
344+
1. **Search and Replace**: Use your IDE's search and replace to update all `JLMapView` imports at once
345+
2. **Incremental Testing**: Test each change individually to isolate any issues
346+
3. **Backup**: Keep a backup of your working v1.x code until migration is complete
347+
4. **Version Control**: Commit your changes incrementally to track progress
348+
349+
## 🤝 **Need Help?**
350+
351+
If you encounter issues during migration:
352+
353+
1. **Check the README**: [README.md](README.md) for comprehensive project information
354+
2. **Review Examples**: Look at the demo applications in `jlmap-fx` and `jlmap-vaadin-demo`
355+
3. **Check Dependencies**: Ensure all required dependencies are properly configured
356+
4. **Verify Java Version**: Ensure you're using Java 17 or higher
357+
358+
---
359+
360+
**Remember**: The migration is designed to be minimal. If you're making extensive changes to your code, you might be doing something wrong. The goal is to change as little as possible while gaining the benefits of the new modular architecture.

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,7 @@ The project uses Maven's module-aware compilation. Each module has its own `modu
295295
- Vaadin Spring Boot Starter
296296
- Vaadin Core components
297297

298-
## Migration from Version 1.x
298+
## 🔄 Migration from Version 1.x
299299

300300
If you're migrating from version 1.x:
301301

@@ -304,6 +304,8 @@ If you're migrating from version 1.x:
304304
3. **Module Declaration**: Ensure your project has proper module configuration
305305
4. **Build Configuration**: Update Maven configuration for the new dependencies
306306

307+
**📖 [Complete Migration Guide](MIGRATION_GUIDE.md)** - Detailed step-by-step instructions for migrating from v1.x to v2.0.0
308+
307309
### Example Migration
308310

309311
**Before (v1.x):**

0 commit comments

Comments
 (0)