Add method for retrieving ol.Overlay by id

src/ol/map.js

@@ -342,6 +342,13 @@ ol.Map = function(options) {
    */
   this.overlays_ = optionsInternal.overlays;
 
+  /**
+   * A lookup of overlays by id.
+   * @private
+   * @type {Object.<string, ol.Overlay>}
+   */
+  this.overlayIdIndex_ = {};
+
   /**
    * @type {ol.renderer.Map}
    * @private
@@ -466,7 +473,7 @@ ol.Map = function(options) {
        * @this {ol.Map}
        */
       function(overlay) {
-        overlay.setMap(this);
+        this.addOverlayInternal(overlay);
       }, this);
 
   goog.events.listen(this.overlays_, ol.CollectionEventType.ADD,
@@ -474,7 +481,7 @@ ol.Map = function(options) {
        * @param {ol.CollectionEvent} event Collection event.
        */
       function(event) {
-        event.element.setMap(this);
+        this.addOverlayInternal(/** @type {ol.Overlay} */ (event.element));
       }, false, this);
 
   goog.events.listen(this.overlays_, ol.CollectionEventType.REMOVE,
@@ -482,7 +489,7 @@ ol.Map = function(options) {
        * @param {ol.CollectionEvent} event Collection event.
        */
       function(event) {
-        event.element.setMap(null);
+        this.removeOverlayInternal(/** @type {ol.Overlay} */ (event.element));
       }, false, this);
 
 };
@@ -539,6 +546,23 @@ ol.Map.prototype.addOverlay = function(overlay) {
 };
 
 
+/**
+ * This deals with map's overlay collection changes.
+ * @param {ol.Overlay} overlay Overlay.
+ * @protected
+ */
+ol.Map.prototype.addOverlayInternal = function(overlay) {
+  var id = overlay.getId();
+  if (id !== undefined) {
+    this.overlayIdIndex_[id.toString()] = overlay;
+  }
+  overlay.setMap(this);
+  goog.events.listen(
+      overlay, ol.Object.getChangeEventType(overlay.getOverlayIdProperty()),
+      this.handleOverlayIdChange_, false, this);
+};
+
+
 /**
  * Add functions to be called before rendering. This can be used for attaching
  * animations before updating the map's view.  The {@link ol.animation}
@@ -767,6 +791,20 @@ ol.Map.prototype.getOverlays = function() {
 };
 
 
+/**
+ * Get an overlay by its identifier (the value returned by overlay.getId()).
+ * Note that the index treats string and numeric identifiers as the same. So
+ * `map.getOverlayById(2)` will return an overlay with id `'2'` or `2`.
+ * @param {string|number} id Overlay identifier.
+ * @return {ol.Overlay} Overlay.
+ * @api
+ */
+ol.Map.prototype.getOverlayById = function(id) {
+  var overlay = this.overlayIdIndex_[id.toString()];
+  return overlay !== undefined ? overlay : null;
+};
+
+
 /**
  * Get the map interactions. Modifying this collection changes the interactions
  * associated with the map.
@@ -1065,6 +1103,28 @@ ol.Map.prototype.handleTileChange_ = function() {
 };
 
 
+/**
+ * @param {goog.events.Event} event Event.
+ * @private
+ */
+ol.Map.prototype.handleOverlayIdChange_ = function(event) {
+  var overlay = /** @type {ol.Overlay} */ (event.target);
+  var id = overlay.getId().toString();
+  var oldId = event.oldValue;
+  if (oldId && oldId != id) {
+    delete this.overlayIdIndex_[oldId];
+  }
+  if (id in this.overlayIdIndex_) {
+    if (this.overlayIdIndex_[id] !== overlay) {
+      delete this.overlayIdIndex_[id];
+      this.overlayIdIndex_[id] = overlay;
+    }
+  } else {
+    this.overlayIdIndex_[id] = overlay;
+  }
+};
+
+
 /**
  * @private
  */
@@ -1245,6 +1305,20 @@ ol.Map.prototype.removeOverlay = function(overlay) {
 };
 
 
+/**
+ * This deals with map's overlay collection changes.
+ * @param {ol.Overlay} overlay Overlay.
+ * @protected
+ */
+ol.Map.prototype.removeOverlayInternal = function(overlay) {
+  var id = overlay.getId();
+  if (id !== undefined) {
+    delete this.overlayIdIndex_[id.toString()];
+  }
+  overlay.setMap(null);
+};
+
+
 /**
  * @param {number} time Time.
  * @private

src/ol/overlay.js

@@ -19,6 +19,7 @@ goog.require('ol.extent');
  * @enum {string}
  */
 ol.OverlayProperty = {
+  ID: 'id',
   ELEMENT: 'element',
   MAP: 'map',
   OFFSET: 'offset',
@@ -73,6 +74,12 @@ ol.Overlay = function(options) {
 
   goog.base(this);
 
+  /**
+   * @private
+   * @type {number|string|undefined}
+   */
+  this.id_ = undefined;
+
   /**
    * @private
    * @type {boolean}
@@ -187,6 +194,17 @@ ol.Overlay.prototype.getElement = function() {
 };
 
 
+/**
+ * Get the feature identifier.  This is an identifier for the overlay and
+ * is set explicitly by calling {@link ol.Overlay#setId}.
+ * @return {number|string|undefined} Id.
+ * @api
+ */
+ol.Overlay.prototype.getId = function() {
+  return this.id_;
+};
+
+
 /**
  * Get the map associated with this overlay.
  * @return {ol.Map|undefined} The map that the overlay is part of.
@@ -211,6 +229,15 @@ ol.Overlay.prototype.getOffset = function() {
 };
 
 
+/**
+ * Workaround to overcome circular dependency.
+ * @return {ol.OverlayProperty}
+ */
+ol.Overlay.prototype.getOverlayIdProperty = function() {
+  return ol.OverlayProperty.ID;
+};
+
+
 /**
  * Get the current position of this overlay.
  * @return {ol.Coordinate|undefined} The spatial point that the overlay is
@@ -321,6 +348,22 @@ ol.Overlay.prototype.setElement = function(element) {
 };
 
 
+/**
+ * Set the feature id. The feature id can be used with the
+ * {@link ol.Map#getOverlayById} method.
+ * @param {number|string} id The feature id.
+ * @observable
+ * @api
+ */
+ol.Overlay.prototype.setId = function(id) {
+  goog.asserts.assert(id !== undefined, 'overlay id should be defined');
+  if (id != this.id_) {
+    this.id_ = id;
+    this.set(ol.OverlayProperty.ID, id);
+  }
+};
+
+
 /**
  * Set the map to be associated with this overlay.
  * @param {ol.Map|undefined} map The map that the overlay is part of.