Kotlin - Here Maps - Get address out of callback function

Question

I am attempting to get the address out of the callback function. I have been reading the documentation for CallBacks and some posts but still don't get why this is not working, as at the moment of returning the 'address' variable the callback has already finished.

    private fun getAddressForCoordinates(geoCoordinates: GeoCoordinates):String {
    address = "unchanged"
    val maxItems = 1
    val reverseGeocodingOptions = SearchOptions(LanguageCode.EN_GB, maxItems)
    searchEngine.search(geoCoordinates, reverseGeocodingOptions, addressSearchCallback)

    return address

}

private val addressSearchCallback =
    SearchCallback { searchError, list ->
        if (searchError != null) {
            //showDialog("Reverse geocoding", "Error: $searchError")
            Toast.makeText(context, "Error: $searchError", Toast.LENGTH_LONG).show()
            return@SearchCallback
        }

        Toast.makeText(
            context,
            "Reverse geocoded address:" + list!![0].address.addressText,
            Toast.LENGTH_LONG
        ).show()

        address = list[0].address.addressText
    }

Answer 1

From your code and comment I assume you are not familiar with the concept of asynchronous execution. That concept was well described here. I'll quote the main point:

When you execute something synchronously, you wait for it to finish before moving on to another task. When you execute something asynchronously, you can move on to another task before it finishes.

The fact that search() requires providing a callback and it doesn't simply return search results, is a good indication that it is most probably asynchronous. Invoking it is like saying: "Search for the data in the background and let me know when you have it. This is my email address - please send me my results there". Where email address is your callback. Invoking search() method does not block execution of your code, it does not wait for results - it only schedules searching and returns almost immediately.

Asynchronous processing is usually more tricky than a regular, synchronous code, but in many cases it is more efficient. In your case you can either try to "convert" original async API of the library to sync API that your code expects - but this is not recommended approach. Or you can redesign your code, so it will work asynchronously. For example, instead of doing this:

fun yourMethodThatNeedsAddress() {
    val address = getAddressForCoordinates()
    doSomethingWithAddress(address)
}

You need to do this:

fun yourMethodThatNeedsAddress() {
    scheduleGetAddressForCoordinates() // renamed getAddressForCoordinates()
}

fun addressSearchCallback() {
    ...
    doSomethingWithAddress(address)
}

So, whatever you planned to do with the acquired address, you can't do this straight after you started searching. You need to wait for a callback and then continue with processing of your address from there.

Answer 2

The SearchEngine from the 4.x HERE SDK needs an online connection as it is fetching results from a remote backend. This may take a few milliseconds, depending on your network connection. So, whenever you perform a search request, you need to wait until the callback is called:

searchEngine.search(geoCoordinates, reverseGeocodingOptions, addressSearchCallback)

When you call this, you pass addressSearchCallback as parameter. The implementation for addressSearchCallback can look like in your example. It will be called whenever the operation has finished. If the device is offline, then an error will be shown.

Note that the search() method is not returning any results immediately. These are passed to the callback, which happens asynchronously on a background thread. Thus, your application can continue to work without blocking any UI.

Once results are retrieved, the callback will be executed by the HERE SDK on the main thread.

So, if your code needs to do something with the address result, you have to do it inside the onSearchCompleted() method defined by the SearchCallback. If you write it in plain Java without lambda notation, it is more visible: You create a new SearchCallback object and pass it as parameter to the SearchEngine. The SearchEngine stores the object and executes the object's onSearchCompleted() whenever it thinks it's the right time:

private SearchCallback addressSearchCallback = new SearchCallback() {
    @Override
    public void onSearchCompleted(@Nullable SearchError searchError, @Nullable List<Place> list) {
        if (searchError != null) {
            showDialog("Reverse geocoding", "Error: " + searchError.toString());
            return;
        }

        // If error is null, list is guaranteed to be not empty.
        showDialog("Reverse geocoded address:", list.get(0).getAddress().addressText);

        // Here is the place to do something more useful with the Address object ...!
    }
};

I took this from this GitHub code snippet. Note that there is also an OfflineSearchEngine, that works without an internet connection, but for some reason it follows the same pattern and executes the task asynchronously.

Answer 3

private void getAddressForCoordinates(GeoCoordinates geoCoordinates) {
    int maxItems = 1;
    SearchOptions reverseGeocodingOptions = new SearchOptions(LanguageCode.EN_GB, maxItems);

    searchEngine.search(geoCoordinates, reverseGeocodingOptions, new SearchCallback() {
        @Override
        public void onSearchCompleted(@Nullable SearchError searchError, @Nullable List<Place> list) {
            if (searchError != null) {
                showDialog("Reverse geocoding", "Error: " + searchError.toString());
                return;
            }

            // If error is null, list is guaranteed to be not empty.
            showDialog("Reverse geocoded address:", list.get(0).getAddress().addressText);
        }
    });
}

SearchEngine, a SearchOptions instance needs to be provided to set the desired LanguageCode. It determines the language of the resulting address. Then we can make a call to the engine's search()-method to search online for the address of the passed coordinates. In case of errors, such as when the device is offline, SearchError holds the error cause.

The reverse geocoding response contains either an error or a result: SearchError and the result list can never be null at the same time - or non-null at the same time.

The Address object contained inside each Place instance is a data class that contains multiple String fields describing the address of the raw location, such as country, city, street name, and many more. Consult the API Reference for more details. If you are only interested in receiving a readable address representation, you can access addressText, as shown in the above example. This is a String containing the most relevant address details, including the place's title.

Please refer to following link for detailed documentation on search() function and parameters associated with it.

https://developer.here.com/documentation/android-sdk-explore/4.4.0.2/dev_guide/topics/search.html