When providing a library like a parser for location-based information one of the most important points is to not create any kind of dependency into the application which later uses the library.
But what does this mean? Here is a small example:
The application ApplA wants to get the location for a certain GPS position and store it into an ApplA.LocationObject, so a request to the library would look like this:
1: ApplA.LocationObject o= locationLib.getLocationFor(longitude,latitude);
And here is the problem why this is not the right way to do it: If someone else wants to use the library in another application B, this application would need the ApplA.LocationObject which it will not have access to. So the developer of application B would need to change the library code to return a ApplB.LocationObject and this would have to be done every time the library is imported into a new application. Often it not even possible to change the library code because it’s wrapped in a non editable jar-file so another solution has to be found.
The most obvious solution would be to move the LocationObject class into the library and return a Library.LocationObj for the request. Then a developer would need to use this LocationObj in his or her application or the information would have to be extracted from the Library.LocationObj and stored in a ApplA.LocationObj. This solution is not very flexible and will force the developer to be dependant on the objects it gets from the library or convert them at least. He has to determine what is stored in the Library.LocationObj and how to get access to this information.
Lets take a step back to what the developer would really want to get. It is information about the location at a certain GPS position so how do we return this information and not a static object where the developer has to figure out how to use it and get to the information inside. The answer to this question is the listener concept and here is how it works:
The user will pass an additional object (the listener) when requesting the location for the GPS position, so it will look like this:
1: Library.LocationListener l = new ApplA.MyLocationObject();
2: locationLib.getLocationFor(longitude,latitude, l);And the ApplA.MyLocationObject would have to look like this:
3: class ApplA.MyLocationObject implements Library.LocationListener{
4: ...
5: public void onRecieveLocationInformation(String locName, String address, ...){
6: //store the received information
7: }
8: }
The library then has to call the onRecieveLocationInformation-method when the information is parsed. This way the ApplA.MyLocationObject now only has to implement the LocationListener interface and it will be notified by the library when the location information is received. It will get all the information about the location and can store these in its custom way.
The listener concept is a very powerful way to remove dependencies and this is only one of many scenarios where it can be used. There are a lot more benefits when using this concept, for example this way the request to the server could be done in a separate thread much easier because the code is no longer structured in a linear way.
Here is one more example how your code could look like, when using the listener concept:
1: final MyLocationObject o = new MyLocationObject();
2: locationLib.getLocationFor(longitude,latitude, new Library.LocationListener(){
3: public void onRecieveLocationInformation(String locName, String address, ...){
4: //store the received information:
5: o.setName(locName);
6: o.setAddress(address);
7: addLocationToLocationList(o);
8: }
9: });
10:
11: ...
12:
13: void addLocationToLocationList(o){
14: ...
15: }
So what do you think about this? Feel free to add some comments 
