Updates the platform interface for improved extendability.

- Releases new interface making the Geocoding plugin easier to extend and
  implement on different platforms.
- Moves the old interface into the `legacy` folder. This interface will
  remain available but will no longer be maintained. To import the old
  interface use `import 'package:geocoding_platform_interface/legacy/geocoding_platform_interface.dart`.

Author: mvanbeusekom

geocoding_platform_interface/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 4.0.0
+
+- **BREAKING CHANGES:**
+  - Releases new interface making the Geocoding plugin easier to extend and
+    implement on different platforms.
+  - Moves the old interface into the `legacy` folder. This interface will
+    remain available but will no longer be maintained. To import the old
+    interface use `import 'package:geocoding_platform_interface/legacy/geocoding_platform_interface.dart`.
+
 ## 3.2.1
 
 - Fixed analysis warnings from `flutter analyse`.

geocoding_platform_interface/lib/geocoding_platform_interface.dart

@@ -1,3 +1,3 @@
-export 'src/errors/errors.dart';
-export 'src/geocoding_platform_interface.dart';
-export 'src/models/models.dart';
+export 'src/geocoding.dart';
+export 'src/geocoding_platform_factory.dart';
+export 'src/types/types.dart';

geocoding_platform_interface/lib/legacy/geocoding_platform_interface.dart

@@ -0,0 +1,3 @@
+export 'src/errors/errors.dart';
+export 'src/geocoding_platform_interface.dart';
+export 'src/models/models.dart';

geocoding_platform_interface/lib/src/errors/errors.dart renamed to geocoding_platform_interface/lib/legacy/src/errors/errors.dart

@@ -38,11 +38,10 @@ abstract class GeocodingPlatform extends PlatformInterface {
   ///
   /// The `localeIdentifier` should be formatted using the syntax:
   /// [languageCode]_[countryCode] (eg. en_US or nl_NL).
-  Future<void> setLocaleIdentifier(
-    String localeIdentifier,
-  ) {
+  Future<void> setLocaleIdentifier(String localeIdentifier) {
     throw UnimplementedError(
-        'setLocaleIdentifier() has not been implementated.');
+      'setLocaleIdentifier() has not been implementated.',
+    );
   }
 
   /// Returns a list of [Location] instances found for the supplied address.
@@ -51,11 +50,10 @@ abstract class GeocodingPlatform extends PlatformInterface {
   /// However in some situations where the supplied address could not be
   /// resolved into a single [Location], multiple [Location] instances may be
   /// returned.
-  Future<List<Location>> locationFromAddress(
-    String address,
-  ) {
+  Future<List<Location>> locationFromAddress(String address) {
     throw UnimplementedError(
-        'locationFromAddress() has not been implementated.');
+      'locationFromAddress() has not been implementated.',
+    );
   }
 
   /// Returns true if there is a geocoder implementation present that may return results.
@@ -80,7 +78,8 @@ abstract class GeocodingPlatform extends PlatformInterface {
     double longitude,
   ) {
     throw UnimplementedError(
-        'placemarkFromCoordinates() has not been implementated.');
+      'placemarkFromCoordinates() has not been implementated.',
+    );
   }
 
   /// Returns a list of [Placemark] instances found for the supplied address.
@@ -89,10 +88,9 @@ abstract class GeocodingPlatform extends PlatformInterface {
   /// However in some situations where the supplied address could not be
   /// resolved into a single [Placemark], multiple [Placemark] instances may be
   /// returned.
-  Future<List<Placemark>> placemarkFromAddress(
-    String address,
-  ) {
+  Future<List<Placemark>> placemarkFromAddress(String address) {
     throw UnimplementedError(
-        'placemarkFromAddress() has not been implementated.');
+      'placemarkFromAddress() has not been implementated.',
+    );
   }
 }

geocoding_platform_interface/lib/src/errors/no_result_found_exception.dart renamed to geocoding_platform_interface/lib/legacy/src/errors/no_result_found_exception.dart

@@ -56,12 +56,14 @@ class Location {
 
     final Map<dynamic, dynamic> locationMap = message;
     final timestamp = DateTime.fromMillisecondsSinceEpoch(
-        locationMap['timestamp'].toInt(),
-        isUtc: true);
+      locationMap['timestamp'].toInt(),
+      isUtc: true,
+    );
 
     if (locationMap['latitude'] == null || locationMap['longitude'] == null) {
       throw ArgumentError(
-          'The parameters latitude and longitude should not be null.');
+        'The parameters latitude and longitude should not be null.',
+      );
     }
 
     return Location._(
@@ -74,10 +76,10 @@ class Location {
   /// Converts the [Location] instance into a [Map] instance that can be
   /// serialized to JSON.
   Map<String, dynamic> toJson() => {
-        'latitude': latitude,
-        'longitude': longitude,
-        'timestamp': timestamp.millisecondsSinceEpoch,
-      };
+    'latitude': latitude,
+    'longitude': longitude,
+    'timestamp': timestamp.millisecondsSinceEpoch,
+  };
 
   @override
   String toString() {

geocoding_platform_interface/lib/src/geocoding_platform_interface.dart renamed to geocoding_platform_interface/lib/legacy/src/geocoding_platform_interface.dart

@@ -132,18 +132,18 @@ class Placemark {
   /// Converts the [Placemark] instance into a [Map] instance that can be
   /// serialized to JSON.
   Map<String, dynamic> toJson() => {
-        'name': name,
-        'street': street,
-        'isoCountryCode': isoCountryCode,
-        'country': country,
-        'postalCode': postalCode,
-        'administrativeArea': administrativeArea,
-        'subAdministrativeArea': subAdministrativeArea,
-        'locality': locality,
-        'subLocality': subLocality,
-        'thoroughfare': thoroughfare,
-        'subThoroughfare': subThoroughfare,
-      };
+    'name': name,
+    'street': street,
+    'isoCountryCode': isoCountryCode,
+    'country': country,
+    'postalCode': postalCode,
+    'administrativeArea': administrativeArea,
+    'subAdministrativeArea': subAdministrativeArea,
+    'locality': locality,
+    'subLocality': subLocality,
+    'thoroughfare': thoroughfare,
+    'subThoroughfare': subThoroughfare,
+  };
 
   @override
   String toString() {

geocoding_platform_interface/lib/src/models/location.dart renamed to geocoding_platform_interface/lib/legacy/src/models/location.dart

@@ -0,0 +1,97 @@
+import 'package:flutter/widgets.dart';
+import 'package:plugin_platform_interface/plugin_platform_interface.dart';
+
+import 'geocoding_platform_factory.dart';
+import 'types/types.dart';
+
+/// Interface for a platform implementation of a [Geocoding] instance.
+///
+/// Platform implementations should extend this class rather than implement it
+/// as `geocoding` package does not consider newly added methods to be breaking
+/// changes. Extending this class (using `extends`) ensures that the subclass
+/// will get the default implementation, while platform implementations that
+/// `implements` this interface will be broken by newly added
+/// [Geocoding] methods.
+abstract class Geocoding extends PlatformInterface {
+  /// Creates a new [PlatformWebViewController]
+  factory Geocoding(GeocodingCreationParams params) {
+    assert(
+      GeocodingPlatformFactory.instance != null,
+      'A platform implementation for `geocoding` has not been set. Please '
+      'ensure that an implementation of `GeocodingPlatformFactory` has been '
+      'set te `GeocodingPlatformFactory.instance` before use. For unit '
+      'testing, `GeocodingPlatformFactory.instance` can be set with your own '
+      'test implementation.',
+    );
+    final Geocoding geocoding = GeocodingPlatformFactory.instance!
+        .createGeocoding(params);
+    PlatformInterface.verify(geocoding, _token);
+    return geocoding;
+  }
+
+  /// Used by the platform implementation to create a new [Geocoding].
+  ///
+  /// Should only be used by platform implementations because they can't extend
+  /// a class that only contains a factory constructor.
+  @protected
+  Geocoding.implementation(this.params) : super(token: _token);
+
+  static final Object _token = Object();
+
+  /// The parameters used to initialize the [Geocoding] instance.
+  final GeocodingCreationParams params;
+
+  /// Returns a list of [Location] instances found for the supplied address.
+  ///
+  /// In most situations the returned list should only contain one entry.
+  /// However in some situations where the supplied address could not be
+  /// resolved into a single [Location], multiple [Location] instances may be
+  /// returned.
+  Future<List<Location>> locationFromAddress(String address, {Locale? locale}) {
+    throw UnimplementedError(
+      'locationFromAddress() has not been implementated.',
+    );
+  }
+
+  /// Returns true if there is a geocoder implementation present that may return results.
+  /// If true, there is still no guarantee that any individual geocoding attempt will succeed.
+  ///
+  ///
+  /// This method is only implemented on Android, calling this on iOS always
+  /// returns [true].
+  Future<bool> isPresent() {
+    throw UnimplementedError('isPresent() has not been implementated.');
+  }
+
+  /// Returns a list of [Placemark] instances found for the supplied
+  /// coordinates.
+  ///
+  /// In most situations the returned list should only contain one entry.
+  /// However in some situations where the supplied coordinates could not be
+  /// resolved into a single [Placemark], multiple [Placemark] instances may be
+  /// returned.
+  Future<List<Placemark>> placemarkFromCoordinates(
+    double latitude,
+    double longitude, {
+    Locale? locale,
+  }) {
+    throw UnimplementedError(
+      'placemarkFromCoordinates() has not been implementated.',
+    );
+  }
+
+  /// Returns a list of [Placemark] instances found for the supplied address.
+  ///
+  /// In most situations the returned list should only contain one entry.
+  /// However in some situations where the supplied address could not be
+  /// resolved into a single [Placemark], multiple [Placemark] instances may be
+  /// returned.
+  Future<List<Placemark>> placemarkFromAddress(
+    String address, {
+    Locale? locale,
+  }) {
+    throw UnimplementedError(
+      'placemarkFromAddress() has not been implementated.',
+    );
+  }
+}