Merge pull request #10 from u-barnwal/LIB-6

Update README

README.md

@@ -4,28 +4,184 @@ HTTP connection library to consume REST APIs in structured way with automatic su
 
 ## Implementation
 **Step 1:** Add to project level build.gradle
-
- allprojects {
-  repositories {
-  ...
-  maven { url 'https://jitpack.io' }
-  }
+```gradle
+allprojects {
+ repositories {
+ ...
+ maven { url 'https://jitpack.io' }
  }
+}
+```
 
 **Step 2:** Add to app level build.gradle
 
- dependencies {
-  implementation 'com.github.u-barnwal:ConnectionLibrary:VERSION'
+```gradle
+dependencies {
+ implementation 'com.github.u-barnwal:ConnectionLibrary:VERSION'
+}
+```
+
+## How to use?
+
+### Create Helper Class
+You need to create a helper class that configures the **Connection** and provides callbacks for all events.
+<details>
+ <summary>Expand: <kbd>ConnectionHelper.kt</kbd></summary>
+
+```kotlin
+import android.content.Context
+import com.isolpro.library.connection.Connection
+
+class ConnectionHelper<T>(private val ctx: Context, private val classType: Class<T>) : Connection<T>() {
+ override var config: Config = Config("API_BASE_ENDPOINT")
+
+ override fun getContext(): Context {
+ return ctx;
+ }
+
+ override fun showLoader() {
+ TODO("Write your function for showing loader")
+ }
+
+ override fun hideLoader() {
+ TODO("Write your function for hiding loader")
+ }
+
+ override fun handleOnRequestCreated(endpoint: String, data: Any?) {
+ TODO("Access the request endpoint and data")
+ }
+
+ override fun handleOnResponseReceived(data: String?) {
+ TODO("This is triggered everytime your receive a response, implement your logger")
+ }
+
+ override fun handleOnNoResponseError() {
+ TODO("Handle when nothing is received as response")
+ }
+
+ override fun handleOnOfflineDataUnsupported() {
+ TODO("Handle when the request made, doesn't store offline data")
+ }
+
+ override fun handleOnOfflineDataUnavailable() {
+ TODO("Handle when the request made, store offline data but doesn't have anything cache yet")
+ }
+
+ override fun handleOnError(e: Exception) {
+ TODO("Handle all other errors")
+ }
+
+ override fun getClassType(): Class<T> {
+ return classType;
  }
+}
+```
+</details>
+
+### Create Models
+While you are free to structure your requests in any way you like, we suggest to create **model* classes* for all your data.
+
+<details>
+ <summary>Expand Example Model</summary>
+
+```kotlin
+class Post {
+ val userId: Number = 0;
+ val id: Number = 0;
+ val title: String = "";
+ val body: String = "";
+}
+```
+</details>
+
+### Create Services
+We also suggest to create service class with all request functions required for the data model.
+
+<details>
+ <summary>Expand Example Service</summary>
+
+```kotlin
+object PostService {
+
+ fun getPosts(ctx: Context): Connection<Post> {
+ return ConnectionHelper(ctx, Post::class.java)
+ .endpoint("/posts")
+ .loader(false)
+ }
+
+ fun createPost(ctx: Context, post: Post): Connection<Post> {
+ return ConnectionHelper(ctx, Post::class.java)
+ .payload(post)
+ .endpoint("/posts/insert")
+ .loader(false)
+ }
+
+}
+```
+</details>
+
+### Making the Request
+Once you have created your models and services, making a request is a piece of cake
+
+- Simple Request
+ ```kotlin
+ PostService.getPosts(this)
+  .post()
+ ```
+
+- Request with Callbacks
+ ```kotlin
+ PostService.getPosts(this)
+  .success {
+  TODO("Use your data from $it")
+  // use $it.userId to get userId from Post 
+  }
+  .failure {
+  TODO("Let user know that the request has failed")
+  }
+  .post()
+  }
+ ```
+
+And you're done ✅
+
+## Enable Offline Mode
+
+To make a request to start caching data for offline usage, just pass a unique `offlineEndpoint` . **Not to be used with data creation/modification requests**.
+
+### When fetching a list of items
+```kotlin
+ConnectionHelper(ctx, Post::class.java)
+ .payload(post)
+ .endpoint("/posts")
+ .offlineEndpoint("posts")
+ .loader(false)
+```
+
+### When fetching a single item (*pass the unique item it as second parameter*)
+```kotlin
+ConnectionHelper(ctx, Post::class.java)
+ .payload(post)
+ .endpoint("/posts/$postId")
+ .offlineEndpoint("posts", postId)
+ .loader(false)
+```
+
+### Recommended attributes for `offlineEndpoint`
+- should be unique
+- avoid using any symbols
+- cannot be empty (empty indicates that request doesn't support offline mode)
+
 
-## How to use
+And you're done ✅
 
 
-See [sample app]("./app/src/main")
+| **See [sample app]("./app/src/main")**
 
 ## Features
 
  - Easy to use
- - Easy to customize
- - Simple file structure: Create *models* & *structures*
+ - Easy to customize & configure
+ - Automated offline mode
+ - Simple file structure: Create *models* & *services*
  - Syntax similar to modern programming notions

app/src/main/java/com/isolpro/library/connection/MainActivity.kt

@@ -10,14 +10,15 @@ class MainActivity : AppCompatActivity() {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_main)
 
- PostService.getPosts(this)
- .success {
- Log.e("callback", "Success")
- Log.e("Product Id: ", it.id.toString());
- }
- .failure {
- Log.e("callback", "Failure")
- }
- .post()
+PostService.getPosts(this)
+ .success {
+ TODO("Use your data from $it")
+
+ // use $it.userId to get userId from Post
+ }
+ .failure {
+ TODO("Let user know that the request has failed")
+ }
+ .post()
  }
 }

app/src/main/java/com/isolpro/library/connection/helpers/CHelper.kt

@@ -0,0 +1,48 @@
+package com.isolpro.library.connection.helpers
+
+import android.content.Context
+import com.isolpro.library.connection.Connection
+
+class CHelper<T>(private val ctx: Context, private val classType: Class<T>) : Connection<T>() {
+ override var config: Config = Config("API_BASE_ENDPOINT")
+
+ override fun getContext(): Context {
+ return ctx;
+ }
+
+ override fun showLoader() {
+ TODO("Write your function for showing loader")
+ }
+
+ override fun hideLoader() {
+ TODO("Write your function for hiding loader")
+ }
+
+ override fun handleOnRequestCreated(endpoint: String, data: Any?) {
+ TODO("Access the request endpoint and data")
+ }
+
+ override fun handleOnResponseReceived(data: String?) {
+ TODO("This is triggered everytime your receive a response, implement your logger")
+ }
+
+ override fun handleOnNoResponseError() {
+ TODO("Handle when nothing is received as response")
+ }
+
+ override fun handleOnOfflineDataUnsupported() {
+ TODO("Handle when the request made, doesn't store offline data")
+ }
+
+ override fun handleOnOfflineDataUnavailable() {
+ TODO("Handle when the request made, store offline data but doesn't have anything cache yet")
+ }
+
+ override fun handleOnError(e: Exception) {
+ TODO("Handle all other errors")
+ }
+
+ override fun getClassType(): Class<T> {
+ return classType;
+ }
+}

app/src/main/java/com/isolpro/library/connection/services/PostService.kt

@@ -13,4 +13,11 @@ object PostService {
  .loader(false)
  }
 
+ fun createPost(ctx: Context, post: Post): Connection<Post> {
+ return ConnectionHelper(ctx, Post::class.java)
+ .payload(post)
+ .endpoint("/posts")
+ .loader(false)
+ }
+
 }