Tactical Technical Strike

Musings, Thoughts, Notes, & a brain dump of what I come across

Looking at bad API decisions: Openlayers toString & fromString

Posted on | January 9, 2010 | No Comments

From time to time, I come across little “bits of aggravation” from various websites, libraries, or technology vendors that make me want to pull my hair out. I’ll spend days or weeks working my way through them, only to realize at the end “If someone had just published this little nuance in bold letters before I started, I would have saved all that time.” This is my attempt to save all that time for someone else.

OpenLayers, if you didn’t know, is a rather large javascript library that provides not only the ability to connect to the Google, Yahoo, and Microsoft mapping apis, but also to common to geospatial servers that implement the open geospatial consortium (ogc) standard protocols for delivering information (this includes ArcGIS and Geoserver).   However, because Openlayers is such a large codebase attempting to provide so much functionality, I often run up against situations where it seems the project has neglected much of their existing functionality in a rush to add new features.

Not that I don’t understand OL’s reasoning.  As the web and the geospatial community continue to advance at breathtaking speeds, the OpenLayers library is tasked to keep up with the latest and greatest functionality, or risk being the library that “Won’t do what I need” and eventually leave users looking for alternatives.  But after working with the library for the better part of 6 months, I’ve been generally surprised at how many broken controls, methods, and inadequate error checking I’ve found within.  Before you implore me to submit patches and help fix the code base myself, I’m writing this in an attempt to provide a public voice to some of these concerns, not to criticize the OpenLayers community for their design decisions.

The issue at hand:

The OpenLayers.Bounds object attempts to describe the current viewport of a map object.  It lists the coordinates of the map corners, making it easy to zoom to a specific view or perform “map math” to change the perspective.  Along with a constructor, it also provides methods to serialize & deserialize the object to an Array, String, or Size object.  However, most likely due to an API that has evolved over time without going back to reconcile prior design decisions to newer techniques and best practices, the toString and fromString methods use data in entirely different formats.  An example of these formats are shown below.

String toString(): return string is of format: “left-bottom=($left,$bottom) right-top=($top,$right)”
void fromString(input): input string is of format ” $left,$bottom,$right,$top”

From the above code example, you can see that you could not directly reuse the fromString format as input for the toString format. It is very elementary to convert these formats, but isn’t that the point of an API? By proper naming, documentation, and working examples, an API should make it down right idiot proof for it’s users to proprly employ it. This is a situation where OpenLayers API did not make that happen, and caused me numerous hours of banging my head. Hopefully, this will save you that trouble.

References:
[Define] OpenLayers: An open source javascript library providing geospatial client functionality for use within the browser. Displays map tiles and data by implementing most common geospatial sources and protocols.

[1] Openlayers

[2] Openlayers.Bounds API Documentation

[3] A bug documenting this issue from 2008

Comments

  • Links, feeds, and all the other info that I need to be fully self-indulgent, shared, and organized. These links and widgets are subject to change.