Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Applies to Roots and Stores
recursive
is only available in Roots. If true
(default false
), then the resulting Stream
merges in the sub-Stores' watchChanges
methods.
debounce
defaults to 200ms, and is useful to remove small consecutive changes to prevent spam to your interface.
fileSystemEvents
defaults to FileSystemEvent.all
, and is useful to remove only some types of change from the resulting Stream
.
Returns a Stream<void>
, useful to trigger UI updates with other statistics.
Many statistics are cached for better performance, as some take a long time to calculate.
If this causes problems, chain noCache
before the below API getters/methods, like this: stats.noCache.storeSize
.
Alternatively, clear the currently cached statistics using invalidateCachedStatistics()
. This is automatically called when new tiles are added to the store.
API Member | Structure | Explanation |
---|---|---|
Both
Use a filesystem watcher to watch for changes, useful for a StreamBuilder
Both
Remove any cached statistic information
storesAvailable
Roots
List all the currently ready stores under the root
rootSize
Roots
Get the current root size in KiB including all sub-stores
rootLength
Roots
Get the number of tiles currently cached in all sub-stores
storeSize
Stores
Get the current store size in KiB
storeLength
Stores
Get the number of tiles currently cached
cacheHits
Stores
Get the number of tiles retrieved from the store during browsing
cacheMisses
Stores
Get the number of tiles not retrieved from the store during browsing
Applies only to Roots
To migrate from older versions with different, incompatible, file structures, migration methods have been provided.
After using the snippet above, use the appropriate method(s) to reach the package version in use. These automatically check for the the structure of a previous version, and migrate it to the correct structure for one version newer. If they successfully migrated a structure, they will return true
; otherwise (if it wasn't successful, or one wasn't found), they will return false
.
For example, to automatically check for and migrate v4 structures to v5, use fromV4
. It is safe to call this every time the application is loaded, and the example application demonstrates this.
Applies only to Stores
This library provides a very simple persistent key-value pair storage system, designed to store any custom information about the store. For example, your application may use one store per urlTemplate
, in which case, the URL can be stored in the metadata.
Remember that metadata
does not have any effect on internal logic: it is simply an auxiliary method of storing any data that might need to be kept alongside a store.
Keys are used as the name of a file. Therefore, keys must be safe, as they are not sanitized by this library.
Add a new key-value pair to the store. For example:
Read all the key-value pairs from the store, and return them in a Map<String, String>
. For example:
Remove a key-value pair from the store. For example:
Remove all the key-value pairs from the store. For example:
Once you can access FMTC.instance
, you can chain on other methods to use the majority of this library's functionality. These are the base chains you will need:
To get the Root and it's associated information, just chain on rootDirectory
, as so:
To use a Store without automatically creating it (recommended for performance), use ()
(call()
). Place the store name inside the parenthesis. For example:
All examples in this documentation will use this method of accessing Stores, assuming that they are already ready.
To use a Store and automatically synchronously create it if it doesn't exist, use []
. Place the store name inside the parenthesis. For example:
This is not recommended, as it uses synchronous IO operations on every get, which can block your application's main thread.
Only use this if you cannot use asynchronous techniques in your current context, or the slight blocking doesn't matter.
After this, you can chain any of the following members/accessors (each will be accessible on a Root, a Store, or both):
Many of the symbols one level beneath the ones listed here, for example those under manage
, have asynchronous versions which are recommended for performance.
To use them, if available, just add 'Async' to the end of the symbol. For example, manage.ready
and manage.readyAsync
.
If you receive warnings in your IDE about using internal members outside its package, you should use the chains listed above instead of directly using the indicated object.
Applies to Roots and Stores
This package relies on a carefully constructed structure that can be easily damaged to the point where it may not be able to be repaired without being completely recreated.
Avoid using access
. If you choose to use it within your application, I may be unable to offer support.
Applies only to Roots
The recovery system is designed to rescue failed bulk downloads, in the event of an unexpected error - such as a fatal crash or other external event.
You should not rely on the recovery system to be 100% reliable, even though it is built to be as close to that as possible.
Recoverable regions are identified internally by an int
ID number. All the methods above make use of this ID number, and so (to ensure continuity) the RootRecovery
object returned is internally a singleton.
This number is generated using the following algorithm, which hopefully ensures a unique number:
Applies to Roots and Stores
The StoreDirectory
used to run this method will remain valid but not ready. Therefore, if you have a variable with it, you should replace it.
Using the normal FMTC.instance('newStoreName')
will work afterwards.
randomRange
controls the randomness of the tile chosen (defaults to null
):
null
: no randomness - the first tile is chosen
<= 0: any tile may be chosen
>= store length: any tile may be chosen
< store length: any tile up to this range may be chosen, enforcing an iteration limit internally
Tiles are not necessarily ordered chronologically. They are usually ordered alphabetically, which may affect your expectations of your chosen range.
Returns null
if there are no cached tiles in this store, otherwise an Image
with size
height and width.
API Member | Explanation |
---|---|
API Member | Structure | Explanation |
---|---|---|
recoverableRegions
Get a list of all recoverable regions, not just those that have failed
failedRegions
Get a list of recoverable regions that have failed
getRecoverableRegion()
Get a specific region from the recoverable list
getFailedRegion()
Get a specific region from the failed list
cancel()
Safely cancel/remove a recoverable region
ready
Both
Check if the necessary directory structure exists
create()
Both
Create the necessary directory structure, or do nothing if it already exists
delete()
Both
Delete the directory structure, fail if it doesn't exist
reset()
Roots
Reset the directory structure (delete and recreate)
reset()
Stores
Reset the tiles directory structure (delete and recreate)
Stores
Safely rename the store and the necessary directories
Stores
Retrieve a tile and extract it's Image
asynchronously