Skip to content

Commit 4ec02d1

Browse files
utsavdotproutsavdotpro
authored
Merge pull request #10 from u-barnwal/LIB-6
Update README
2 parents acc8479 + 68499b8 commit 4ec02d1

4 files changed

Lines changed: 233 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 168 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,184 @@ HTTP connection library to consume REST APIs in structured way with automatic su
44

55
## Implementation
66
**Step 1:** Add to project level build.gradle
7-
8-
allprojects {
9-
repositories {
10-
...
11-
maven { url 'https://jitpack.io' }
12-
}
7+
```gradle
8+
allprojects {
9+
repositories {
10+
...
11+
maven { url 'https://jitpack.io' }
1312
}
13+
}
14+
```
1415

1516
**Step 2:** Add to app level build.gradle
1617

17-
dependencies {
18-
implementation 'com.github.u-barnwal:ConnectionLibrary:VERSION'
18+
```gradle
19+
dependencies {
20+
implementation 'com.github.u-barnwal:ConnectionLibrary:VERSION'
21+
}
22+
```
23+
24+
## How to use?
25+
26+
### Create Helper Class
27+
You need to create a helper class that configures the **Connection** and provides callbacks for all events.
28+
<details>
29+
<summary>Expand: <kbd>ConnectionHelper.kt</kbd></summary>
30+
31+
```kotlin
32+
import android.content.Context
33+
import com.isolpro.library.connection.Connection
34+
35+
class ConnectionHelper<T>(private val ctx: Context, private val classType: Class<T>) : Connection<T>() {
36+
override var config: Config = Config("API_BASE_ENDPOINT")
37+
38+
override fun getContext(): Context {
39+
return ctx;
40+
}
41+
42+
override fun showLoader() {
43+
TODO("Write your function for showing loader")
44+
}
45+
46+
override fun hideLoader() {
47+
TODO("Write your function for hiding loader")
48+
}
49+
50+
override fun handleOnRequestCreated(endpoint: String, data: Any?) {
51+
TODO("Access the request endpoint and data")
52+
}
53+
54+
override fun handleOnResponseReceived(data: String?) {
55+
TODO("This is triggered everytime your receive a response, implement your logger")
56+
}
57+
58+
override fun handleOnNoResponseError() {
59+
TODO("Handle when nothing is received as response")
60+
}
61+
62+
override fun handleOnOfflineDataUnsupported() {
63+
TODO("Handle when the request made, doesn't store offline data")
64+
}
65+
66+
override fun handleOnOfflineDataUnavailable() {
67+
TODO("Handle when the request made, store offline data but doesn't have anything cache yet")
68+
}
69+
70+
override fun handleOnError(e: Exception) {
71+
TODO("Handle all other errors")
72+
}
73+
74+
override fun getClassType(): Class<T> {
75+
return classType;
1976
}
77+
}
78+
```
79+
</details>
80+
81+
### Create Models
82+
While you are free to structure your requests in any way you like, we suggest to create **model* classes* for all your data.
83+
84+
<details>
85+
<summary>Expand Example Model</summary>
86+
87+
```kotlin
88+
class Post {
89+
val userId: Number = 0;
90+
val id: Number = 0;
91+
val title: String = "";
92+
val body: String = "";
93+
}
94+
```
95+
</details>
96+
97+
### Create Services
98+
We also suggest to create service class with all request functions required for the data model.
99+
100+
<details>
101+
<summary>Expand Example Service</summary>
102+
103+
```kotlin
104+
object PostService {
105+
106+
fun getPosts(ctx: Context): Connection<Post> {
107+
return ConnectionHelper(ctx, Post::class.java)
108+
.endpoint("/posts")
109+
.loader(false)
110+
}
111+
112+
fun createPost(ctx: Context, post: Post): Connection<Post> {
113+
return ConnectionHelper(ctx, Post::class.java)
114+
.payload(post)
115+
.endpoint("/posts/insert")
116+
.loader(false)
117+
}
118+
119+
}
120+
```
121+
</details>
122+
123+
### Making the Request
124+
Once you have created your models and services, making a request is a piece of cake
125+
126+
- Simple Request
127+
```kotlin
128+
PostService.getPosts(this)
129+
.post()
130+
```
131+
132+
- Request with Callbacks
133+
```kotlin
134+
PostService.getPosts(this)
135+
.success {
136+
TODO("Use your data from $it")
137+
// use $it.userId to get userId from Post
138+
}
139+
.failure {
140+
TODO("Let user know that the request has failed")
141+
}
142+
.post()
143+
}
144+
```
145+
146+
And you're done ✅
147+
148+
## Enable Offline Mode
149+
150+
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**.
151+
152+
### When fetching a list of items
153+
```kotlin
154+
ConnectionHelper(ctx, Post::class.java)
155+
.payload(post)
156+
.endpoint("/posts")
157+
.offlineEndpoint("posts")
158+
.loader(false)
159+
```
160+
161+
### When fetching a single item (*pass the unique item it as second parameter*)
162+
```kotlin
163+
ConnectionHelper(ctx, Post::class.java)
164+
.payload(post)
165+
.endpoint("/posts/$postId")
166+
.offlineEndpoint("posts", postId)
167+
.loader(false)
168+
```
169+
170+
### Recommended attributes for `offlineEndpoint`
171+
- should be unique
172+
- avoid using any symbols
173+
- cannot be empty (empty indicates that request doesn't support offline mode)
174+
20175

21-
## How to use
176+
And you're done ✅
22177

23178

24-
See [sample app]("./app/src/main")
179+
| **See [sample app]("./app/src/main")**
25180

26181
## Features
27182

28183
- Easy to use
29-
- Easy to customize
30-
- Simple file structure: Create *models* & *structures*
184+
- Easy to customize & configure
185+
- Automated offline mode
186+
- Simple file structure: Create *models* & *services*
31187
- Syntax similar to modern programming notions

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

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,15 @@ class MainActivity : AppCompatActivity() {
1010
super.onCreate(savedInstanceState)
1111
setContentView(R.layout.activity_main)
1212

13-
PostService.getPosts(this)
14-
.success {
15-
Log.e("callback", "Success")
16-
Log.e("Product Id: ", it.id.toString());
17-
}
18-
.failure {
19-
Log.e("callback", "Failure")
20-
}
21-
.post()
13+
PostService.getPosts(this)
14+
.success {
15+
TODO("Use your data from $it")
16+
17+
// use $it.userId to get userId from Post
18+
}
19+
.failure {
20+
TODO("Let user know that the request has failed")
21+
}
22+
.post()
2223
}
2324
}

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
package com.isolpro.library.connection.helpers
2+
3+
import android.content.Context
4+
import com.isolpro.library.connection.Connection
5+
6+
class CHelper<T>(private val ctx: Context, private val classType: Class<T>) : Connection<T>() {
7+
override var config: Config = Config("API_BASE_ENDPOINT")
8+
9+
override fun getContext(): Context {
10+
return ctx;
11+
}
12+
13+
override fun showLoader() {
14+
TODO("Write your function for showing loader")
15+
}
16+
17+
override fun hideLoader() {
18+
TODO("Write your function for hiding loader")
19+
}
20+
21+
override fun handleOnRequestCreated(endpoint: String, data: Any?) {
22+
TODO("Access the request endpoint and data")
23+
}
24+
25+
override fun handleOnResponseReceived(data: String?) {
26+
TODO("This is triggered everytime your receive a response, implement your logger")
27+
}
28+
29+
override fun handleOnNoResponseError() {
30+
TODO("Handle when nothing is received as response")
31+
}
32+
33+
override fun handleOnOfflineDataUnsupported() {
34+
TODO("Handle when the request made, doesn't store offline data")
35+
}
36+
37+
override fun handleOnOfflineDataUnavailable() {
38+
TODO("Handle when the request made, store offline data but doesn't have anything cache yet")
39+
}
40+
41+
override fun handleOnError(e: Exception) {
42+
TODO("Handle all other errors")
43+
}
44+
45+
override fun getClassType(): Class<T> {
46+
return classType;
47+
}
48+
}

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,11 @@ object PostService {
1313
.loader(false)
1414
}
1515

16+
fun createPost(ctx: Context, post: Post): Connection<Post> {
17+
return ConnectionHelper(ctx, Post::class.java)
18+
.payload(post)
19+
.endpoint("/posts")
20+
.loader(false)
21+
}
22+
1623
}

0 commit comments

Comments
 (0)