Merge pull request #88 from OpenCageData/release-3.0.0

Release 3.0.0

Author: tsamaya

.github/workflows/java.yml

@@ -0,0 +1,36 @@
+name: Java workflow
+
+on:
+  push:
+    branches:
+      - "**"
+    tags-ignore:
+      - "*.*"
+    paths-ignore:
+      - README.md
+      - CHANGELOG.md
+
+jobs:
+  gradle_tests:
+    name: Gradle Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout latest source
+        uses: actions/checkout@v6
+
+      - name: Set up JDK
+        uses: actions/setup-java@v5
+        with:
+          distribution: "temurin"
+          java-version: 17
+          cache: "gradle"
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Run Tests
+        run: ./gradlew -DOPENCAGE_API_KEY=${{ secrets.OPENCAGE_API_KEY }} test
+
+      - name: Run Build
+        run: ./gradlew -DOPENCAGE_API_KEY=${{ secrets.OPENCAGE_API_KEY }} build

.github/workflows/unit-tests.yml

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Changed
+
+- The methods `forward` and `reverse` can throw Exceptions [#32](https://github.com/OpenCageData/jopencage/issues/32)
+- updates gradle to 9.2
+- updates dependencies httpClient 5.6, jackson 2.19, junit 6
+
+### Added
+
+- Javadoc published on GH Pages, thanks to action [deploy-publish-javadoc](https://github.com/marketplace/a
 
 ## [2.2.2] - 2024-08-14
 

.idea/inspectionProfiles/Project_Default.xml

@@ -1,8 +1,10 @@
 # JOpenCage
 
+:warning: This is an unstable branch that only contains SNAPSHOT versions; it is still under development.
+
 [![Maven Central](https://img.shields.io/maven-central/v/com.opencagedata/jopencage.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/com.opencagedata/jopencage)
 [![UnitTests](https://github.com/OpenCageData/jopencage/actions/workflows/unit-tests.yml/badge.svg?branch=master)](https://github.com/OpenCageData/jopencage/actions)
-[![Javadoc](https://img.shields.io/badge/JavaDoc-Online-green)](https://OpenCageData.github.io/jopencage/javadoc/)
+[![Javadoc](https://img.shields.io/badge/JavaDoc-Online-green)](https://opencagedata.github.io/jopencage/javadoc/)
 
 [![security status](https://www.meterian.io/badge/gh/OpenCageData/jopencage/security?branch=master)](https://www.meterian.io/report/gh/OpenCageData/jopencage)
 [![stability status](https://www.meterian.io/badge/gh/OpenCageData/jopencage/stability?branch=master)](https://www.meterian.io/report/gh/OpenCageData/jopencage)
@@ -35,9 +37,9 @@ Signup for a [free-trial API Key](https://opencagedata.com/users/sign_up).
     implementation "com.opencagedata:jopencage:REPLACE.WITH.VERSION"
 ```
 
-### Example
+### Examples
 
-Forward
+#### Forward
 
 ```java
 // In real live application the JOpenCageGeocoder should be a Singleton
@@ -47,10 +49,10 @@ JOpenCageForwardRequest request = new JOpenCageForwardRequest("Graz");
 request.setMinConfidence(1);
 request.setNoAnnotations(false);
 request.setNoDedupe(true);
-JOpenCageResponse response = jOpenCageGeocoder.forward(request);
+JOpenCageResponse response = jOpenCageGeocoder.forward(request); // try..catch or throw JOpenCageException
 ```
 
-Reverse
+#### Reverse
 
 ```java
 // In real live application the JOpenCageGeocoder should be a Singleton
@@ -59,11 +61,23 @@ JOpenCageGeocoder jOpenCageGeocoder = new JOpenCageGeocoder(YOUR_API_KEY);
 JOpenCageReverseRequest request = new JOpenCageReverseRequest(-22.6792, 14.5272);
 request.setNoAnnotations(true);
 
-JOpenCageResponse response = jOpenCageGeocoder.reverse(request);
+JOpenCageResponse response = jOpenCageGeocoder.reverse(request);  // try..catch or throw JOpenCageException
 ```
 
+## Upgrading from 1.x or 2.x to 3.x
+
+Starting with version 3.x, the methods `forward()` and `reverse()` can throw a `com.opencagedata.jopencage.JOpenCageException`.
+
+## Javadoc
+
+https://opencagedata.github.io/jopencage/javadoc/
+
 ## Libraries
 
+-   JDK 17+
+-   Apache Http Client
+-   FasterXml Jackson
+-   Slf4j
 -   JDK 8+
 -   Apache Http Client
 -   FasterXml Jackson
@@ -73,14 +87,14 @@ JOpenCageResponse response = jOpenCageGeocoder.reverse(request);
 
 For running the tests you have to use your _OWN_ OpenCage Geocoding API Key. Get a free trial key at https://opencagedata.com
 
-```
+```bash
 ./gradlew -DOPENCAGE_API_KEY=<your apikey> test
 ```
 
 ## Gradle
 
 ```bash
-./gradlew wrapper --gradle-version 9.0.0
+./gradlew wrapper --gradle-version 9.2.1
 ```
 
 ## Contribute

CHANGELOG.md

@@ -9,7 +9,6 @@ repositories {
 }
 
 dependencies {
-
 	implementation "org.apache.httpcomponents.client5:httpclient5:${httpClientVersion}"
 	implementation "com.fasterxml.jackson.core:jackson-databind:${jacksonVersion}"
 	implementation "com.fasterxml.jackson.core:jackson-core:${jacksonVersion}"
@@ -18,13 +17,16 @@ dependencies {
 	// Tests
 	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
 
-	testImplementation(platform("org.junit:junit-bom:${junitVersion}"))
-	testImplementation("org.junit.jupiter:junit-jupiter:${junitVersion}")
+	testImplementation platform("org.junit:junit-bom:${junitVersion}")
+	testImplementation "org.junit.jupiter:junit-jupiter:${junitVersion}"
+	
+	// https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-slf4j2-impl
+	testImplementation group: 'org.apache.logging.log4j', name: 'log4j-slf4j2-impl', version: "${slf4j2Version}"
 }
 
 java {
-	sourceCompatibility = JavaVersion.VERSION_1_8
-	targetCompatibility = JavaVersion.VERSION_1_8
+	sourceCompatibility = JavaVersion.VERSION_17
+	targetCompatibility = JavaVersion.VERSION_17
 
 	withJavadocJar()
 	withSourcesJar()

README.md

@@ -1,8 +1,9 @@
 group=com.opencagedata
 artifactId=jopencage
-version=2.2.2
+version=3.0.0-SNAPSHOT
 
 httpClientVersion=5.6
 jacksonVersion=2.19.2
 
-junitVersion=5.14.1
+junitVersion=6.0.1
+slf4j2Version=2.22.1

build.gradle

@@ -0,0 +1,26 @@
+package com.opencagedata.jopencage;
+
+/**
+ * BadRequestException
+ *
+ * @author Arnaud
+ * @since 3.0
+ */
+
+public class BadRequestException extends JOpenCageException {
+    /**
+     * Creates a new BadRequestException with a <code>null</code> detail message.
+     */
+    public BadRequestException() {
+        super();
+    }
+
+    /**
+     * Creates a new BadRequestException with the specified detail message.
+     *
+     * @param message The error message
+     */
+    public BadRequestException(String message) {
+        super(message);
+    }
+}

gradle.properties

@@ -0,0 +1,26 @@
+package com.opencagedata.jopencage;
+
+/**
+ * ForbiddenException
+ *
+ * @author Arnaud
+ * @since 3.0
+ */
+
+public class ForbiddenException extends JOpenCageException {
+    /**
+     * Creates a new ForbiddenException with a <code>null</code> detail message.
+     */
+    public ForbiddenException() {
+        super();
+    }
+
+    /**
+     * Creates a new ForbiddenException with the specified detail message.
+     *
+     * @param message The error message
+     */
+    public ForbiddenException(String message) {
+        super(message);
+    }
+}

src/main/java/com/opencagedata/jopencage/BadRequestException.java

@@ -0,0 +1,38 @@
+package com.opencagedata.jopencage;
+
+/**
+ * HttpClientErrorException
+ *
+ * @author Arnaud
+ * @since 3.0
+ */
+
+public class HttpClientErrorException extends JOpenCageException {
+    /**
+     * Creates a new HttpClientErrorException with a <code>null</code> detail
+     * message.
+     */
+    public HttpClientErrorException() {
+        super();
+    }
+
+    /**
+     * Creates a new HttpClientErrorException with the specified detail message.
+     *
+     * @param message The error message
+     */
+    public HttpClientErrorException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new HttpClientErrorException with the specified detail message and
+     * its Throwable cause.
+     *
+     * @param message The error message
+     * @param cause   The cause
+     */
+    public HttpClientErrorException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}