Android tile cache folder option, closes #913

docs/Changelog.md

@@ -2,6 +2,7 @@
 
 ## New since 0.7.0
 
+- Android tile cache folder option [#913](https://github.com/mapsforge/mapsforge/issues/913)
 - Desktop tile cache creation utility [#915](https://github.com/mapsforge/mapsforge/issues/915)
 - Many other minor improvements and bug fixes
 - [Solved issues](https://github.com/mapsforge/mapsforge/issues?q=is%3Aissue+is%3Aclosed+milestone%3A0.8.0)

mapsforge-map-android/src/main/java/org/mapsforge/map/android/util/AndroidUtil.java

@@ -1,7 +1,7 @@
 /*
  * Copyright 2010, 2011, 2012, 2013 mapsforge.org
  * Copyright 2014-2015 Ludwig M Brinckmann
- * Copyright 2014-2016 devemux86
+ * Copyright 2014-2017 devemux86
  *
  * This program is free software: you can redistribute it and/or modify it under the
  * terms of the GNU Lesser General Public License as published by the Free Software
@@ -78,14 +78,27 @@ public static TileCache createExternalStorageTileCache(Context c, String id, int
      */
     public static TileCache createExternalStorageTileCache(Context c,
                                                            String id, int firstLevelSize, int tileSize, boolean persistent) {
+        return createExternalStorageTileCache(c.getExternalCacheDir(), id, firstLevelSize, tileSize, persistent);
+    }
+
+    /**
+     * Utility function to create a two-level tile cache along with its backends.
+     *
+     * @param cacheDir       the cache directory
+     * @param id             name for the directory, which will be created as a subdirectory of the cache directory
+     * @param firstLevelSize size of the first level cache (tiles number)
+     * @param tileSize       tile size
+     * @param persistent     whether the second level tile cache should be persistent
+     * @return a new cache created on the external storage
+     */
+    public static TileCache createExternalStorageTileCache(File cacheDir,
+                                                           String id, int firstLevelSize, int tileSize, boolean persistent) {
         LOGGER.info("TILECACHE INMEMORY SIZE: " + Integer.toString(firstLevelSize));
         TileCache firstLevelTileCache = new InMemoryTileCache(firstLevelSize);
-        File cacheDir = c.getExternalCacheDir();
         if (cacheDir != null) {
-            // cacheDir will be null if full
             String cacheDirectoryName = cacheDir.getAbsolutePath() + File.separator + id;
             File cacheDirectory = new File(cacheDirectoryName);
-            if (cacheDirectory.exists() || cacheDirectory.mkdir()) {
+            if (cacheDirectory.exists() || cacheDirectory.mkdirs()) {
                 int tileCacheFiles = estimateSizeOfFileSystemCache(cacheDirectoryName, firstLevelSize, tileSize);
                 if (cacheDirectory.canWrite() && tileCacheFiles > 0) {
                     try {
@@ -103,6 +116,25 @@ public static TileCache createExternalStorageTileCache(Context c,
         return firstLevelTileCache;
     }
 
+    /**
+     * Utility function to create a two-level tile cache with the right size. When the cache is created we do not
+     * actually know the size of the mapview, so the screenRatio is an approximation of the required size.
+     *
+     * @param c           the Android context
+     * @param cacheDir    the cache directory
+     * @param id          name for the storage directory
+     * @param tileSize    tile size
+     * @param screenRatio part of the screen the view takes up
+     * @param overdraw    overdraw allowance
+     * @param persistent  whether the second level tile cache should be persistent
+     * @return a new cache created on the external storage
+     */
+    public static TileCache createTileCache(Context c, File cacheDir, String id, int tileSize,
+                                            float screenRatio, double overdraw, boolean persistent) {
+        int cacheSize = getMinimumCacheSize(c, tileSize, overdraw, screenRatio);
+        return createExternalStorageTileCache(cacheDir, id, cacheSize, tileSize, persistent);
+    }
+
     /**
      * Utility function to create a two-level tile cache with the right size. When the cache is created we do not
      * actually know the size of the mapview, so the screenRatio is an approximation of the required size.
@@ -137,6 +169,24 @@ public static TileCache createTileCache(Context c, String id, int tileSize, floa
         return createTileCache(c, id, tileSize, screenRatio, overdraw, false);
     }
 
+    /**
+     * Utility function to create a two-level tile cache with the right size, using the size of the map view.
+     *
+     * @param cacheDir   the cache directory
+     * @param id         name for the storage directory
+     * @param tileSize   tile size
+     * @param width      the width of the map view
+     * @param height     the height of the map view
+     * @param overdraw   overdraw allowance
+     * @param persistent whether the cache should be persistent
+     * @return a new cache created on the external storage
+     */
+    public static TileCache createTileCache(File cacheDir, String id, int tileSize,
+                                            int width, int height, double overdraw, boolean persistent) {
+        int cacheSize = getMinimumCacheSize(tileSize, overdraw, width, height);
+        return createExternalStorageTileCache(cacheDir, id, cacheSize, tileSize, persistent);
+    }
+
     /**
      * Utility function to create a two-level tile cache with the right size, using the size of the map view.
      *

mapsforge-map-awt/src/main/java/org/mapsforge/map/awt/util/AwtUtil.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 devemux86
+ * Copyright 2016-2017 devemux86
  *
  * This program is free software: you can redistribute it and/or modify it under the
  * terms of the GNU Lesser General Public License as published by the Free Software
@@ -30,6 +30,12 @@ public final class AwtUtil {
      * Utility function to create a two-level tile cache with the right size, using the size of the screen.
      * <p>
      * Combine with <code>FrameBufferController.setUseSquareFrameBuffer(false);</code>
+     *
+     * @param tileSize       the tile size
+     * @param overdrawFactor the overdraw factor applied to the map view
+     * @param capacity       the maximum number of entries in file cache
+     * @param cacheDirectory the directory where cached tiles will be stored
+     * @return a new cache created on the file system
      */
     public static TileCache createTileCache(int tileSize, double overdrawFactor, int capacity, File cacheDirectory) {
         int cacheSize = getMinimumCacheSize(tileSize, overdrawFactor);
@@ -42,6 +48,10 @@ public static TileCache createTileCache(int tileSize, double overdrawFactor, int
      * Compute the minimum cache size for a view, using the size of the screen.
      * <p>
      * Combine with <code>FrameBufferController.setUseSquareFrameBuffer(false);</code>
+     *
+     * @param tileSize       the tile size
+     * @param overdrawFactor the overdraw factor applied to the map view
+     * @return the minimum cache size for the view
      */
     public static int getMinimumCacheSize(int tileSize, double overdrawFactor) {
         Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();