Akavache: An Asynchronous Key-Value Store for Native Applications

Where can I use it?

What does that mean?

Contents

Getting Started

Choose a location

The magic

Platform-specific notes

Handling Xamarin/Maui Linker

1) Add a file to reference the types

publicstaticclassLinkerPreserve{staticLinkerPreserve(){varpersistentName=typeof(SQLitePersistentBlobCache).FullName;varencryptedName=typeof(SQLiteEncryptedBlobCache).FullName;}}

2) Use the following initializer in your cross platform library or in your head project

Akavache.Registrations.Start("ApplicationName")

Using Akavache

usingSystem.Reactive.Linq;// IMPORTANT - this makes await work!// Make sure you set the application name before doing any inserts or getsAkavache.Registrations.Start("AkavacheExperiment")varmyToaster=newToaster();awaitBlobCache.UserAccount.InsertObject("toaster",myToaster);//// ...later, in another part of town...//// Using async/awaitvartoaster=awaitBlobCache.UserAccount.GetObject<Toaster>("toaster");// or without async/awaitToastertoaster;BlobCache.UserAccount.GetObject<Toaster>("toaster").Subscribe(x=>toaster=x, ex=>Console.WriteLine("No Key!"));

Handling Errors

Toastertoaster;try{toaster=awaitBlobCache.UserAccount.GetObject("toaster");}catch(KeyNotFoundExceptionex){toaster=newToaster();}// Or without async/await:toaster=awaitBlobCache.UserAccount.GetObject<Toaster>("toaster").Catch(Observable.Return(newToaster()));

Shutting Down

BlobCache.Shutdown().Wait();

Using a different SQLitePCL.raw bundle

<PackageReferenceInclude="akavache.sqlite3"Version="6.0.40-g7e90c572c6" /><PackageReferenceInclude="SQLitePCLRaw.bundle_green"Version="1.1.11" />

Akavache.Sqlite3.Registrations.Start("ApplicationName",()=>SQLitePCL.Batteries_V2.Init());

Examining Akavache caches

What's this Global Variable nonsense?

DateTime/DateTimeOffset Considerations

// Sets the reader to return DateTime/DateTimeOffset in Local.BlobCache.ForcedDateTimeKind=DateTimeKind.Local;

Basic Method Documentation

/* * Get items from the store */// Get a single itemIObservable<byte[]>Get(stringkey);// Get a list of itemsIObservable<IDictionary<string,byte[]>>Get(IEnumerable<string>keys);// Get an object serialized via InsertObjectIObservable<T>GetObject<T>(stringkey);// Get all objects of type TIObservable<IEnumerable<T>>GetAllObjects<T>();// Get a list of objects given a list of keysIObservable<IDictionary<string,T>>GetObjects<T>(IEnumerable<string>keys);/* * Save items to the store */// Insert a single itemIObservable<Unit>Insert(stringkey,byte[]data,DateTimeOffset?absoluteExpiration=null);// Insert a set of itemsIObservable<Unit>Insert(IDictionary<string,byte[]>keyValuePairs,DateTimeOffset?absoluteExpiration=null);// Insert a single objectIObservable<Unit>InsertObject<T>(stringkey,Tvalue,DateTimeOffset?absoluteExpiration=null);// Insert a group of objectsIObservable<Unit>InsertObjects<T>(IDictionary<string,T>keyValuePairs,DateTimeOffset?absoluteExpiration=null);/* * Remove items from the store */// Delete a single itemIObservable<Unit>Invalidate(stringkey);// Delete a list of itemsIObservable<Unit>Invalidate(IEnumerable<string>keys);// Delete a single object (do *not* use Invalidate for items inserted with InsertObject!)IObservable<Unit>InvalidateObject<T>(stringkey);// Deletes a list of objectsIObservable<Unit>InvalidateObjects<T>(IEnumerable<string>keys);// Deletes all items (regardless if they are objects or not)IObservable<Unit>InvalidateAll();// Deletes all objects of type TIObservable<Unit>InvalidateAllObjects<T>();/* * Get Metadata about items */// Return a list of all keys. Use for debugging purposes only.IObservable<IEnumerable<string>>GetAllKeys();// Return the time which an item was createdIObservable<DateTimeOffset?>GetCreatedAt(stringkey);// Return the time which an object of type T was createdIObservable<DateTimeOffset?>GetObjectCreatedAt<T>(stringkey);// Return the time which a list of keys were createdIObservable<IDictionary<string,DateTimeOffset?>>GetCreatedAt(IEnumerable<string>keys);/* * Utility methods */// Attempt to ensure all outstanding operations are written to diskIObservable<Unit>Flush();// Preemptively drop all expired keys and run SQLite's VACUUM method on the// underlying databaseIObservable<Unit>Vacuum();

Extension Method Documentation

/* * Username / Login Methods (only available on ISecureBlobCache) */// Save login information for the given hostIObservable<Unit>SaveLogin(stringuser,stringpassword,stringhost="default",DateTimeOffset?absoluteExpiration=null);// Load information for the given hostIObservable<LoginInfo>GetLoginAsync(stringhost="default");// Erase information for the given hostIObservable<Unit>EraseLogin(stringhost="default");/* * Downloading and caching URLs and Images */// Download a file as a byte arrayIObservable<byte[]>DownloadUrl(stringurl,IDictionary<string,string>headers=null,boolfetchAlways=false,DateTimeOffset?absoluteExpiration=null);// Load a given key as an imageIObservable<IBitmap>LoadImage(stringkey,float?desiredWidth=null,float?desiredHeight=null);// Download an image from the network and load itIObservable<IBitmap>LoadImageFromUrl(stringurl,boolfetchAlways=false,float?desiredWidth=null,float?desiredHeight=null,DateTimeOffset?absoluteExpiration=null);/* * Composite operations */// Attempt to return an object from the cache. If the item doesn't// exist or returns an error, call a Func to return the latest// version of an object and insert the result in the cache.IObservable<T>GetOrFetchObject<T>(stringkey,Func<Task<T>>fetchFunc,DateTimeOffset?absoluteExpiration=null);// Like GetOrFetchObject, but isn't asyncIObservable<T>GetOrCreateObject<T>(stringkey,Func<T>fetchFunc,DateTimeOffset?absoluteExpiration=null);// Immediately return a cached version of an object if available, but *always*// also execute fetchFunc to retrieve the latest version of an object.IObservable<T>GetAndFetchLatest<T>(thisIBlobCacheThis,stringkey,Func<IObservable<T>>fetchFunc,Func<DateTimeOffset,bool>fetchPredicate=null,DateTimeOffset?absoluteExpiration=null,boolshouldInvalidateOnError=false,Func<T,bool>cacheValidationPredicate=null)