-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from rommansabbir/dev
Release: v.3.0.0
- Loading branch information
Showing
42 changed files
with
1,370 additions
and
378 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,206 +1,157 @@ | ||
| [](https://jitpack.io/#rommansabbir/StoreX) | ||
| # StoreX | ||
| ✔️ Simplify Caching in Android | ||
|  | ||
|
|
||
| ## Features | ||
| * Notify on Data Changes based on Subscription | ||
| * Lightweight | ||
| * AES Encryption | ||
| * Thread Safe | ||
| [](#getting-started-quick) | ||
|
|
||
| ## How does it work? | ||
| Caching is just a simple key-value pair data saving procedure. StoreX follows the same approach. StoreX uses SharedPreference/Cache Directory (as File) as storage for caching data. Since we really can't just save the original data because of security issues. StoreX uses AES encryption & decryption behind the scene when you are caching data or fetching data from the cache. Also, you can observer cached data in real-time. | ||
| <p align="center"> | ||
| <a href="https://android-arsenal.com/details/1/8362"><img alt="Maintained" src="https://img.shields.io/badge/Android%20Arsenal-NetworkX-green.svg?style=flat" height="20"/></a> | ||
| </p> | ||
|
|
||
| ## Documentation | ||
| <p align="center"> | ||
| <a href="https://github.com/rommansabbir/NetworkX"><img alt="Maintained" src="https://img.shields.io/badge/Maintained_Actively%3F-Yes-green.svg" height="20"/></a> | ||
| </p> | ||
|
|
||
| ### Installation | ||
| <p align="center"> | ||
| <a href="https://jitpack.io/#rommansabbir/NetworkX"><img alt="JitPack" src="https://img.shields.io/badge/JitPack-Yes-green.svg?style=flat" height="20"/></a> | ||
| </p> | ||
|
|
||
| --- | ||
| Step 1. Add the JitPack repository to your build file | ||
| <h1 align="center"> ⚡ Latest Version: 3.0.0 | Change Logs 🔰</h1> | ||
|
|
||
| ```gradle | ||
| allprojects { | ||
| repositories { | ||
| maven { url 'https://jitpack.io' } | ||
| } | ||
| } | ||
| ``` | ||
| - Breaking changes compared to `v2.1.0`. | ||
| - Encryption is not coming with the library itself anymore. It's developer specific now. | ||
| - `SmartStoreX` is now completely storage (`CacheDir/FilesDir/Others`) based, no more `SharedPref` usages. | ||
| - New configuration `StoreXSmartConfig` to work with `SmartStoreX`. | ||
|
|
||
| Step 2. Add the dependency | ||
| [](#getting-started-quick) | ||
|
|
||
| ```gradle | ||
| dependencies { | ||
| implementation 'com.github.rommansabbir:StoreX:Tag' | ||
| } | ||
| ``` | ||
| <h1 align="center">Installation</h1> | ||
|
|
||
| --- | ||
| ## ➤ Step 1: | ||
|
|
||
| ### Version available | ||
| Add the JitPack repository to your build file . | ||
|
|
||
| | Latest Releases | ||
| | ------------- | | ||
| | 2.1.0 | | ||
|
|
||
| --- | ||
|
|
||
| ### What's new in this version? | ||
| - Multiple instance of StoreX with differnet configuration & different storage type support (SharedPref/Cache Storage as File) | ||
| - Added support for custom Coroutine Scopes | ||
|
|
||
| ## Initialize | ||
| ```` | ||
| // Create multiple identifers | ||
| object StoreXIdentifiers { | ||
| val mainConfig : StoreXConfig = StoreXConfig( | ||
| "Something_1", | ||
| "main_pref", | ||
| writeOrGetAsFileUsingCacheDirectory= true) | ||
| val anotherConfig : StoreXConfig = StoreXConfig( | ||
| "Something_2", | ||
| "secondary_pref", | ||
| writeOrGetAsFileUsingCacheDirectory= false) | ||
| } | ||
| ```` | ||
|
|
||
| ```` | ||
| StoreXCore.init(this, mutableListOf( | ||
| StoreXIdentifiers.mainConfig, | ||
| StoreXIdentifiers.anotherConfig, | ||
| )) | ||
| ```` | ||
|
|
||
| ## How To Access | ||
| ```` | ||
| StoreXCore.instance(configs: StoreXConfig) | ||
| ```` | ||
| or else, use the extension function | ||
| ```` | ||
| fun storeXInstance(config: StoreXConfig) | ||
| ```` | ||
| which return an instance of `StoreX` [Note: You must initalize `StoreX` properly before accessing or else it will throw `NotInitializedException`] | ||
|
|
||
| Also, you can set encryption key for your data accross the application by calling this method `StoreXCore.setEncryptionKey(key:String)` which throw `InvalidEncryptionKeyException` if you passed empty `String` | ||
|
|
||
| ---- | ||
|
|
||
| # Usages | ||
|
|
||
| ## How to save an object to StoreX? | ||
|
|
||
| Create any data class that extends `StoreAbleObject` | ||
| Example: | ||
| ````` | ||
| class MyClass:StoreAbleObject() | ||
| ````` | ||
|
|
||
| ```` | ||
| //How to save the object (Main Thread) [Deprecated] | ||
| StoreX.put(key: String, value: StoreAbleObject) | ||
| //How to save the object (Backed by Coroutine) | ||
| StoreX.put(scope: CoroutineScope, key: String, value: StoreAbleObject) | ||
| ```` | ||
|
|
||
| or use Async | ||
| ```` | ||
| //How to save the object with Callback [Deprecated] | ||
| StoreX.put<T : StoreAbleObject>(key: String, value: StoreAbleObject, callback: SaveCallback<T>) | ||
| //How to save the object with Callback (Backed by Coroutine) | ||
| StoreX.put<T : StoreAbleObject>(scope: CoroutineScope, key: String, value: StoreAbleObject, callback: SaveCallback<T>) | ||
| ```` | ||
| ```gradle | ||
| allprojects { | ||
| repositories { | ||
| maven { url 'https://jitpack.io' } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## ➤ Step 2: | ||
|
|
||
| ## How to get an object from StoreX? | ||
| Get an saved object (Main Thread) which may throw `RuntimeException` | ||
| ```` | ||
| StoreX.get<T : StoreAbleObject>(key: String, objectType: Class<T>): T | ||
| ```` | ||
| or use Async | ||
| ```` | ||
| //Deprecated | ||
| StoreX.<T : StoreAbleObject>get(key: String, objectType: Class<T>, callback: GetCallback<T>) | ||
| Add the dependency. | ||
|
|
||
| //Backed by Coroutine | ||
| StoreX.<T : StoreAbleObject>get(scope: CoroutineScope,key: String, objectType: Class<T>, callback: GetCallback<T>) | ||
| ```` | ||
| ```gradle | ||
| dependencies { | ||
| implementation 'com.github.rommansabbir:StoreX:3.0.0' | ||
| } | ||
| ``` | ||
|
|
||
| ## How to get notified on data changes? | ||
| Simple, to get notified on any data changes according to a given key you first need to subscribe to StoreX by calling this method `StoreX.addSubscriber(subscriber: Subscriber)` else if you want to add a list subscriber use `StoreX.addSubscriber(subscribers: ArrayList<Subscriber>)` | ||
| ## ➤ Step 3: | ||
| How to Access `SmartStoreX`. | ||
| - First, create an instance of `StoreXSmartConfig` : | ||
| ```kotlin | ||
| val testConfig = StoreXSmartConfig( | ||
| WeakReference(this), | ||
| "filename", | ||
| StoreAbleObject(), //Object to be saved, must be a instance of StoreAbleObject. | ||
| StoreXCachingStrategy.CacheDir, // Caching directory: CacheDir-FilesDir-Others | ||
| overwriteExistingFile = true | ||
| ) | ||
| ``` | ||
|
|
||
| Example: | ||
| First setup an callback for the data changes | ||
| ```` | ||
| private val callback1 = object : EventCallback{ | ||
| override fun onDataChanges(subscriber: Subscriber, instance: StoreX) { | ||
| // Callback return an instance of StoreX and the specific subscriber | ||
| } | ||
| } | ||
| - To write an object : | ||
| ````kotlin | ||
| val isWriteDone = SmartStoreX.getInstance.write(testConfig) | ||
| Log.d("Write Object", isWriteDone.toString()) | ||
| ```` | ||
| Create a new subscriber. | ||
|
|
||
| Create a new subscriber by providing the `Key`, `Observer ID (Must be unique)` and the `Callback` | ||
| - To get a written object : | ||
| ```kotlin | ||
| val storedObject: StoreAbleObject? = | ||
| SmartStoreX.getInstance.read(testConfig, StoreAbleObject::class.java) | ||
| Log.d("Written Object", "Object ID: " + (storedObject?.objectId ?: "null")) | ||
| ``` | ||
|
|
||
| ```` | ||
| private var subscriber1 = Subscriber(key, OBSERVER_ID_1, callback1) | ||
| ```` | ||
| - To delete a written object : | ||
| ```kotlin | ||
| val isDeleted = SmartStoreX.getInstance.delete(testConfig) | ||
| Log.d("Is Delete Done", isDeleted.toString()) | ||
| ``` | ||
|
|
||
| Now register the subscriber to the `StoreX` by calling this method | ||
| ```` | ||
| StoreX.addSubscriber(subscriber1) | ||
| ```` | ||
| How to manage `Subscription` (`Write/Delete`). | ||
|
|
||
| - To register a subscriber : | ||
| ```kotlin | ||
| SmartStoreX.registerSubscriber( | ||
| testConfig.fileName, | ||
| subscriber = object : StoreXSubscription { | ||
| override fun <T : StoreAbleObject> onCallback(fileName: String, updatedObject: T) { | ||
| Log.d("Write Callback", updatedObject.objectId) | ||
| } | ||
|
|
||
| override fun <T : StoreAbleObject> onDelete(fileName: String, deletedObject: T) { | ||
| Log.d("Delete Callback", deletedObject.objectId) | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| Also, you can remove your subscription any time by calling this method | ||
| `StoreX.removeSubscriber(subscriber: Subscriber)` or list of subscriber `StoreX.removeSubscriber(subscribers: ArrayList<Subscriber>)` | ||
| ```` | ||
| storeXInstance().removeSubscriber(subscriber1) | ||
| ```` | ||
| - To remove a subscriber : | ||
| ```kotlin | ||
| SmartStoreX.removeSubscriber(testConfig.fileName) | ||
| ``` | ||
|
|
||
| ## How to remove any saved data? | ||
| ```` | ||
| StoreX.remove(key: String) | ||
| ```` | ||
| - To remove all subscribers : | ||
| ```kotlin | ||
| SmartStoreX.removeAllSubscriber() | ||
| ``` | ||
|
|
||
| ## How to remove all data when you are crazy | ||
| ```` | ||
| StoreX.removeAll() | ||
| ```` | ||
| - `Objects` that are extended from `StoreAbleObject` : | ||
| ``` | ||
| StoreAbleString("Value") | ||
| StoreAbleInt(1) | ||
| StoreAbleDouble(1.0) | ||
| StoreAbleLong(1234567890879) | ||
| StoreAbleByte(Byte) | ||
| StoreAbleChar(Char) | ||
| StoreAbleShort(Short | ||
| StoreAbleArrayList(Arraylist) | ||
| StoreAbleMutableList(MutableList) | ||
| StoreAbleSet(Set) | ||
| StoreAbleMutableSet(MutableSet) | ||
| StoreAbleHashMap(HashMap) | ||
| StoreAbleHashSet(HashSet) | ||
| ``` | ||
|
|
||
| ##### Need more information regarding the solid implementation? - Check out the sample application. | ||
| [Looking for old version documentation? Click here to see.](https://github.com/rommansabbir/StoreX/master/README_OLD.md) | ||
|
|
||
| --- | ||
| [](#getting-started-quick) | ||
|
|
||
| ## Contact me | ||
|
|
||
| ### How does StoreX work? | ||
| ✔ [LinkedIn](https://www.linkedin.com/in/rommansabbir/) | ||
|
|
||
| <img src='https://github.com/rommansabbir/StoreX/blob/master/art/how-storex-works.png'/> | ||
| ✔ [Website](https://rommansabbir.com) | ||
|
|
||
| ---- | ||
|
|
||
| ### Contact me | ||
| [Portfolio](https://www.rommansabbir.com/) | [LinkedIn](https://www.linkedin.com/in/rommansabbir/) | [Twitter](https://www.twitter.com/itzrommansabbir/) | [Facebook](https://www.facebook.com/itzrommansabbir/) | ||
| [](#getting-started-quick) | ||
|
|
||
| ### License | ||
|
|
||
| --- | ||
| [Apache Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) | ||
|
|
||
| ```` | ||
| Copyright (C) 2021 Romman Sabbir | ||
| ````html | ||
| Copyright (C) 2023 Romman Sabbir | ||
|
|
||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
|
|
||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| See the License for the specific language governing permissions and | ||
| limitations under the License. | ||
| ```` | ||
|
|
||
|
|
Oops, something went wrong.