Skip to content

Commit 738fe99

Browse files
Andre601Andre601
committed
Updating readme
0 parents  commit 738fe99

14 files changed

+1865
-0
lines changed

‎.github/ISSUE_TEMPLATE.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: Repor Bug
3+
about: Use this template to report bugs
4+
5+
---
6+
7+
## Issue template
8+
Please make sure you've checked the following things first:
9+
- [ ] You made sure, you're using the latest version.
10+
Note that versions AFTER 1.0.5 are only for JDA V4!
11+
- [ ] You checked the wiki for additional information.
12+
- [ ] No other issue with the same problem is open.
13+
14+
## Problem
15+
> Please summarice what issue you encountered
16+
<!-- Type below this line -->
17+
18+
19+
## Steps to reproduce
20+
> What steps do we need to make to encounter this problem?
21+
<!-- Type below this line -->
22+
23+
24+
## Additional information
25+
> Any additional information like JDK version, JDA version, etc.
26+
> Images can also be added
27+
<!-- Type below this line -->

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Andre_601
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+213
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
[BotBlock]: https://botblock.org
2+
[API]: https://botblock.org/api/docs
3+
4+
[BotBlock4J]: https://github.com/Nathan-webb/BotBlock4J
5+
6+
[Wiki]: https://github.com/Andre601/JavaBotBlockAPI/wiki
7+
[Javadocs]: https://Andre601.github.io/jbba-doc
8+
9+
[BadgeDownload]: https://api.bintray.com/packages/andre601/maven/JavaBotBlockAPI/images/download.svg
10+
[Download]: https://bintray.com/andre601/maven/JavaBotBlockAPI/_latestVersion
11+
12+
JavaBotBlockAPI is a continued and updated Java Wrapper for [BotBlock], a website that makes it possible to update guild counts on multiple lists with one API.
13+
This wrapper is a fork of [BotBlock4J] and was updated and improved to make it as userfriendly as possible.
14+
15+
# Installation
16+
[![BadgeDownload]][Download]
17+
18+
You can install JavaBotBlockAPI through the following methods.
19+
Make sure to replace `{version}` with the above shown version.
20+
21+
## Gradle
22+
Put this code into your `build.gradle`:
23+
```gradle
24+
repositories{
25+
jcenter()
26+
}
27+
28+
dependencies{
29+
compile group: 'com.andre601', name: 'JavaBotBlockAPI', version: '{version}'
30+
}
31+
```
32+
33+
## Maven
34+
For maven use this code snipped:
35+
```xml
36+
<dependencies>
37+
<dependency>
38+
<groupId>com.andre601</groupId>
39+
<artifactId>JavaBotBlockAPI</artifactId>
40+
<version>{version}</version>
41+
</dependency>
42+
</dependencies>
43+
```
44+
45+
# Usage
46+
To use the Wrapper you have to follow these steps.
47+
48+
## Notes
49+
In the below examples do I use a JDA instance called `jda`.
50+
This will also work with ShardManager.
51+
52+
## POST methods
53+
You can post you guild counts to the different Botlists using the BotBlock API.
54+
55+
### Creating an instance of BotBlockAPI
56+
For posting your guild counts towards the BotBlock API you first need to create an instance of the BotBlockAPI class.
57+
To do this it's recommended to use `BotBlockAPI.Builder()`.
58+
59+
Here is an example of how it could look like.
60+
```java
61+
BotBlockAPI api = new BotBlockAPI.Builder()
62+
.addAuthToken("lbots.org", "MySecretToken123")
63+
.addAuthToken("botlist.space", "MySecretToken456")
64+
.build();
65+
```
66+
Remember to use `.build();` at the end to create the class.
67+
68+
### Auto Posting
69+
JavaBotBlockAPI allows you to post the guild counts automatically every X minutes.
70+
To do this, you first need to get an instance of the RequestHandler and then call `.startAutoPosting(...)`.
71+
72+
Here is an example:
73+
```java
74+
RequestHandler handler = new RequestHandler();
75+
76+
// api is the instance of the BotBlockAPI
77+
handler.startAutoPosting(jda, api);
78+
```
79+
The delay in which you post the guild counts is set through the `.setUpdateInterval(int)` method in the BotBlockAPI.Builder().
80+
81+
### Cancel auto posting
82+
To cancel the auto posting just call `.stopAutoPosting();` in the RequestHandler and it should cancel the scheduler.
83+
84+
### Manually posting
85+
There are methods that allow you to post the guild counts manually.
86+
To Post your guild counts, just call the `.postGuilds(..., ...)` method in the RequestHandler.
87+
88+
```java
89+
RequestHandler handler = new RequestHandler();
90+
91+
// api is the instance of the BotBlockAPI
92+
handler.postGuilds(jda, api);
93+
```
94+
95+
## GET methods
96+
Since version 2.0.0 of JavaBotBlockAPI can you get certain informations of a bot or the available Botlists on the BotBlock API.
97+
98+
### All available Botlists
99+
You can call `.getBotlists()` to receive a JSONObject with all available Botlists in the BotBlockAPI.
100+
101+
The returned JSONObject could look like this:
102+
```json
103+
{
104+
"botlist.space": {
105+
"api_docs": "https://docs.botlist.space",
106+
"api_post": "https://api.botlist.space/v1/bots/:id",
107+
"api_field": "server_count",
108+
"api_shard_id": null,
109+
"api_shard_count": null,
110+
"api_shards": "shards",
111+
"api_get": "https://api.botlist.space/v1/bots/:id"
112+
},
113+
"lbots.org": {
114+
"api_docs": "https://lbots.org/api/docs",
115+
"api_post": "https://lbots.org/api/v1/bots/:id/stats",
116+
"api_field": "guild_count",
117+
"api_shard_id": "shard_id",
118+
"api_shard_count": "shard_count",
119+
"api_shards": null,
120+
"api_get": null
121+
}
122+
}
123+
```
124+
125+
### Single Botlist
126+
Calling `.getBotlist(String)` returns a specific Botlist as JSONObject.
127+
For example does `.getBotlist("lbots.org")` return the following JSONObject:
128+
```json
129+
{
130+
"api_docs": "https://lbots.org/api/docs",
131+
"api_post": "https://lbots.org/api/v1/bots/:id/stats",
132+
"api_field": "guild_count",
133+
"api_shard_id": "shard_id",
134+
"api_shard_count": "shard_count",
135+
"api_shards": null,
136+
"api_get": null
137+
}
138+
```
139+
140+
### Complete Botinfo
141+
Calling `.getAll(...)` returns a JSONObject from all the botlists and with some general information.
142+
143+
The JSONObject can look like this:
144+
```json
145+
{
146+
"id": "123456789012345678",
147+
"name": "MyBot",
148+
"discriminator": "1234",
149+
"owners": [
150+
"234567890123456789"
151+
],
152+
"server_count": 100,
153+
"invite": "https://discordapp.com/oauth2/authorize?client_id=123456789012345678&scope=bot",
154+
"list_data": {
155+
"botlist.space": [
156+
<data>,
157+
200
158+
],
159+
"lbots.org": [
160+
<data>,
161+
404
162+
]
163+
}
164+
}
165+
```
166+
167+
`<data>` is the JSON that is returned by the provided Botlist meaning it's different for each site.
168+
`name`, `owners`, `server_count` and `invite` is based on the most common appearances of the data.
169+
170+
### Botinfo from all Botlists
171+
You can call `.getBotInfos(...)` to only receive the bot info from all the Botlists.
172+
173+
The returned JSONObject can look like this:
174+
```json
175+
{
176+
"botlist.space": [
177+
<data>,
178+
200
179+
],
180+
"lbots.org": [
181+
<data>,
182+
404
183+
]
184+
}
185+
```
186+
`<data>` is the JSON that is returned by the provided Botlist meaning it's different for each site.
187+
188+
### Botinfo of a single site
189+
With `.getBotInfo(..., String)` can you receive the info of a specific site.
190+
The returned data depends on the selected site and can be different for each one.
191+
192+
### Owners
193+
You can call `.getOwners(...)` to get the owners of a Bot from all the Botlists.
194+
The info is returned as JSONArray and is based on how often the info is provided by the botlists.
195+
196+
## Exceptions
197+
When you post the guild counts you could encounter certain Exceptions.
198+
You can receive the following exceptions:
199+
- `IOException`
200+
The Request couldn't be performed properly. This can be f.e. the case when BotBlock.org denies access (403).
201+
- `RatelimitedException`
202+
When we exceed the ratelimit of BotBlock.org
203+
This shouldn't be the case with auto-posting since it has a minimum delay of 1 minute.
204+
- `NullPointerException`
205+
Thrown when BotBlock.org sends an empty response, meaning something got messed up on their side.
206+
207+
# Links
208+
Here are some useful links:
209+
- [BotBlock.org][BotBlock] Site for which this wrapper was made.
210+
- [API] API documentation.
211+
- [Wiki] Contains additional information on how you can use JavaBotBlockAPI.
212+
- [Javadocs] Java documentation of the Wrapper.
213+
- [BotBlock4J] Original Wrapper from which this one originates.

‎build.gradle

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
plugins{
2+
id 'com.jfrog.bintray' version '1.8.4'
3+
id 'java-library'
4+
id 'idea'
5+
id 'maven-publish'
6+
id 'maven'
7+
}
8+
9+
group = 'com.andre601'
10+
version = '1.1.0'
11+
12+
sourceCompatibility = 1.8
13+
14+
jar{
15+
baseName = 'JavaBotBlockAPI'
16+
}
17+
18+
repositories{
19+
mavenCentral()
20+
jcenter()
21+
}
22+
23+
dependencies{
24+
api group: 'com.squareup.okhttp3', name: 'okhttp', version: '3.11.0'
25+
api group: 'org.json', name: 'json', version: '20180813'
26+
api group: 'org.jetbrains', name: 'annotations', version: '16.0.2'
27+
api(group: 'net.dv8tion', name: 'JDA', version: '4.BETA.0_23'){
28+
exclude(module: 'opus-java')
29+
}
30+
}
31+
32+
task sourcesJar(type: Jar, dependsOn: classes){
33+
classifier = 'sources'
34+
from sourceSets.main.allSource
35+
}
36+
37+
task javadocJar(type: Jar, dependsOn: javadoc){
38+
classifier = 'javadoc'
39+
from javadoc.destinationDir
40+
}
41+
42+
artifacts{
43+
archives sourcesJar
44+
archives javadocJar
45+
}
46+
47+
bintray{
48+
user = bintrayUser
49+
key = bintrayApiKey
50+
publications = ['JavaBotBlockAPIRelease']
51+
pkg{
52+
repo = 'maven'
53+
name = 'JavaBotBlockAPI'
54+
licenses = ['MIT']
55+
vcsUrl = 'https://github.com/Andre601/JavaBotBlockAPI'
56+
version{
57+
name = project.version
58+
released = new Date()
59+
}
60+
}
61+
}
62+
63+
publishing{
64+
publications{
65+
JavaBotBlockAPIRelease(MavenPublication){
66+
from components.java
67+
groupId group
68+
artifactId archivesBaseName
69+
version version
70+
artifact javadocJar
71+
artifact sourcesJar
72+
}
73+
}
74+
}

‎gradle/wrapper/gradle-wrapper.jar

53.1 KB
Binary file not shown.

‎gradle/wrapper/gradle-wrapper.properties

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#Sat Jun 22 13:52:50 CEST 2019
2+
distributionBase=GRADLE_USER_HOME
3+
distributionPath=wrapper/dists
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists
6+
distributionUrl=https\://services.gradle.org/distributions/gradle-4.4-all.zip

0 commit comments

Comments
 (0)