Allow to refresh a source and reload its data.

Provide an API to refresh a source and reload its data in an associated
layer, as for example already loaded tiles in a ol.source.Tile source
are not refreshed. Additionally a test for the new
ol.source.Source.refresh() function is provided.

Currently internal state is not cleaned up, e.g. already loaded tiles
in a `ol.source.Tile` source are still cached and not reloaded at all.

github issue #4867 (https://github.com/openlayers/ol3/issues/4867)

src/ol/source/source.js

@@ -150,6 +150,15 @@ ol.source.Source.prototype.getWrapX = function() {
 };
 
 
+/**
+ * Refreshes the source and finally dispatches a 'change' event.
+ * @api
+ */
+ol.source.Source.prototype.refresh = function() {
+  this.changed();
+};
+
+
 /**
  * Set the attributions of the source.
  * @param {Array.<ol.Attribution>} attributions Attributions.

src/ol/source/tilesource.js

@@ -290,6 +290,15 @@ ol.source.Tile.prototype.getTileCoordForTileUrlFunction = function(tileCoord, op
 };
 
 
+/**
+ * @inheritDoc
+ */
+ol.source.Tile.prototype.refresh = function() {
+  this.tileCache.clear();
+  this.changed();
+};
+
+
 /**
  * Marks a tile coord as being used, without triggering a load.
  * @param {number} z Tile coordinate z.

test/spec/ol/source/source.test.js

@@ -0,0 +1,29 @@
+goog.provide('ol.test.source.Source');
+
+describe('ol.source.Source', function() {
+
+  describe('constructor', function() {
+    it('returns a source', function() {
+      var source = new ol.source.Source({
+        projection: ol.proj.get('EPSG:4326')
+      });
+      expect(source).to.be.a(ol.source.Source);
+    });
+  });
+
+  describe('#refresh()', function() {
+    it('dispatches the change event', function() {
+      var source = new ol.source.Source({
+        projection: ol.proj.get('EPSG:4326')
+      });
+      var changedSpy = sinon.spy();
+      source.on('change', changedSpy);
+      source.refresh();
+      expect(changedSpy.called).to.be.ok();
+    });
+  });
+
+});
+
+goog.require('ol.proj');
+goog.require('ol.source.Source');

test/spec/ol/source/tilesource.test.js

@@ -170,6 +170,24 @@ describe('ol.source.Tile', function() {
     });
   });
 
+  describe('#refresh()', function() {
+    it('checks clearing of internal state', function() {
+      // create a source with one loaded tile
+      var source = new ol.test.source.TileMock({
+        '1/0/0': ol.TileState.LOADED
+      });
+      // check the loaded tile is there
+      var tile = source.getTile(1, 0, 0);
+      expect(tile).to.be.a(ol.Tile);
+      // check tile cache is filled
+      expect(source.tileCache.getCount()).to.eql(1);
+      // refresh the source
+      source.refresh();
+      // check tile cache after refresh (should be empty)
+      expect(source.tileCache.getCount()).to.eql(0);
+    });
+  });
+
 });