org.telegram.abilitybots.api.bot

Class AbilityBot

java.lang.Object

org.telegram.telegrambots.bots.AbsSender

org.telegram.telegrambots.bots.DefaultAbsSender

org.telegram.telegrambots.bots.TelegramLongPollingBot

org.telegram.abilitybots.api.bot.AbilityBot

All Implemented Interfaces:

org.telegram.telegrambots.generics.LongPollingBot

public abstract class AbilityBot
extends TelegramLongPollingBot

The father of all ability bots. Bots that need to utilize abilities need to extend this bot.

It's important to note that this bot strictly extends TelegramLongPollingBot.

All bots extending the AbilityBot get implicit abilities:

• /claim - Claims this bot
• Sets the user as the Privacy.CREATOR of the bot
• Only the user with the ID returned by creatorId() can genuinely claim the bot
• /commands - reports all user-defined commands (abilities)
• The same format acceptable by BotFather
• /backup - returns a backup of the bot database
• /recover - recovers the database
• /promote @username - promotes user to bot admin
• /demote @username - demotes bot admin to user
• /ban @username - bans the user from accessing your bot commands and features
• /unban @username - lifts the ban from the user

Additional information of the implicit abilities are present in the methods that declare them.

The two most important handles in the AbilityBot are the DBContext db and the MessageSender sender. All bots extending AbilityBot can use both handles in their update consumers.

Author:

Abbas Abou Daya

Field Summary

Fields

Modifier and Type	Field and Description
static String	ADMINS
protected static String	BACKUP
protected static String	BAN
static String	BLACKLIST
protected static String	CLAIM
protected static String	COMMANDS
protected DBContext	db
protected static String	DEFAULT
protected static String	DEMOTE
protected static String	PROMOTE
protected static String	RECOVER
protected static String	RECOVER_SUCCESS
protected static String	RECOVERY_MESSAGE
protected MessageSender	sender
protected static String	UNBAN
static String	USER_ID
static String	USERS

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbilityBot(String botToken, String botUsername)
protected	AbilityBot(String botToken, String botUsername, DBContext db)
protected	AbilityBot(String botToken, String botUsername, DBContext db, DefaultBotOptions botOptions)
protected	AbilityBot(String botToken, String botUsername, DefaultBotOptions botOptions)

Method Summary

Modifier and Type	Method and Description
protected Set<Integer>	admins()
Ability	backupDB() This backup ability returns the object defined by DBContext.backup() as a message document.
Ability	banUser() Banned users are accumulated in the blacklist.
protected Set<Integer>	blacklist()
protected boolean	checkGlobalFlags(org.telegram.telegrambots.api.objects.Update update) Test the update against the provided global flags.
Ability	claimCreator() Regular users and admins who try to claim the bot will get banned.
abstract int	creatorId()
Ability	demoteAdmin()
String	getBotToken()
String	getBotUsername()
protected EndUser	getUser(int id) Gets the user with the specified ID.
protected EndUser	getUser(String username) Gets the user with the specified username.
protected int	getUserIdSendError(String username, long chatId) Gets the user with the specified username.
void	onUpdateReceived(org.telegram.telegrambots.api.objects.Update update) This method contains the stream of actions that are applied on any update.
Ability	promoteAdmin()
Ability	recoverDB() Recovers the bot database using DBContext.recover(Object).
Ability	reportCommands() Format of the report:
Ability	unbanUser() Usage: /unban @username
protected Map<String,Integer>	userIds()
protected Map<Integer,EndUser>	users()

Methods inherited from class org.telegram.telegrambots.bots.TelegramLongPollingBot

clearWebhook

Methods inherited from class org.telegram.telegrambots.bots.DefaultAbsSender

addStickerToSet, createNewStickerSet, downloadFile, downloadFile, downloadFileAsync, downloadFileAsync, getBaseUrl, sendApiMethod, sendApiMethodAsync, sendAudio, sendDocument, sendPhoto, sendSticker, sendVideo, sendVideoNote, sendVoice, setChatPhoto, uploadStickerFile

Methods inherited from class org.telegram.telegrambots.bots.AbsSender

answerCallbackQuery, answerCallbackQueryAsync, answerInlineQuery, answerInlineQueryAsync, answerPreCheckoutQuery, answerPreCheckoutQuery, answerShippingQuery, answerShippingQuery, deleteChatPhoto, deleteChatPhoto, deleteMessage, deleteMessage, deleteWebhook, deleteWebhook, editMessageCaption, editMessageCaptionAsync, editMessageReplyMarkup, editMessageReplyMarkup, editMessageText, editMessageTextAsync, execute, executeAsync, exportChatInviteLink, exportChatInviteLinkAsync, forwardMessage, forwardMessageAsync, getChat, getChatAdministrators, getChatAdministratorsAsync, getChatAsync, getChatMember, getChatMemberAsync, getChatMemberCount, getChatMemberCountAsync, getFile, getFileAsync, getGameHighScores, getGameHighScoresAsync, getMe, getMeAsync, getUserProfilePhotos, getUserProfilePhotosAsync, getWebhookInfo, getWebhookInfoAsync, kickMember, kickMemberAsync, leaveChat, leaveChatAsync, pinChatMessage, pinChatMessage, promoteChatMember, promoteChatMember, restrictChatMember, restrictChatMember, sendChatAction, sendChatActionAsync, sendContact, sendContactAsync, sendGame, sendGameAsync, sendInvoice, sendInvoice, sendLocation, sendLocationAsync, sendMessage, sendMessageAsync, sendVenue, sendVenueAsync, setChatDescription, setChatDescription, setChatTitle, setChatTitle, setGameScore, setGameScoreAsync, unbanMember, unbanMemberAsync, unpinChatMessage, unpinChatMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.telegram.telegrambots.generics.LongPollingBot

onClosing, onUpdatesReceived

Field Detail

ADMINS

public static final String ADMINS

See Also:

Constant Field Values

USERS

public static final String USERS

See Also:

Constant Field Values

USER_ID

public static final String USER_ID

See Also:

Constant Field Values

BLACKLIST

public static final String BLACKLIST

See Also:

Constant Field Values

DEFAULT

protected static final String DEFAULT

See Also:

Constant Field Values

CLAIM

protected static final String CLAIM

See Also:

Constant Field Values

BAN

protected static final String BAN

See Also:

Constant Field Values

PROMOTE

protected static final String PROMOTE

See Also:

Constant Field Values

DEMOTE

protected static final String DEMOTE

See Also:

Constant Field Values

UNBAN

protected static final String UNBAN

See Also:

Constant Field Values

BACKUP

protected static final String BACKUP

See Also:

Constant Field Values

RECOVER

protected static final String RECOVER

See Also:

Constant Field Values

COMMANDS

protected static final String COMMANDS

See Also:

Constant Field Values

RECOVERY_MESSAGE

protected static final String RECOVERY_MESSAGE

See Also:

Constant Field Values

RECOVER_SUCCESS

protected static final String RECOVER_SUCCESS

See Also:

Constant Field Values

db

protected final DBContext db

sender

protected MessageSender sender

Constructor Detail

AbilityBot

protected AbilityBot(String botToken,
                     String botUsername,
                     DBContext db,
                     DefaultBotOptions botOptions)

AbilityBot

protected AbilityBot(String botToken,
                     String botUsername,
                     DBContext db)

AbilityBot

protected AbilityBot(String botToken,
                     String botUsername,
                     DefaultBotOptions botOptions)

AbilityBot

protected AbilityBot(String botToken,
                     String botUsername)

Method Detail

creatorId

public abstract int creatorId()

users

protected Map<Integer,EndUser> users()

Returns:

the map of ID -> EndUser

userIds

protected Map<String,Integer> userIds()

Returns:

the map of Username -> ID

blacklist

protected Set<Integer> blacklist()

Returns:

a blacklist containing all the IDs of the banned users

admins

protected Set<Integer> admins()

Returns:

an admin set of all the IDs of bot administrators

onUpdateReceived

public void onUpdateReceived(org.telegram.telegrambots.api.objects.Update update)

This method contains the stream of actions that are applied on any update.

It will correctly handle addition of users into the DB and the execution of abilities and replies.

Parameters:

update - the update received by Telegram's API

getBotToken

public String getBotToken()

Specified by:

getBotToken in interface org.telegram.telegrambots.generics.LongPollingBot

Specified by:

getBotToken in class DefaultAbsSender

getBotUsername

public String getBotUsername()

checkGlobalFlags

protected boolean checkGlobalFlags(org.telegram.telegrambots.api.objects.Update update)

Test the update against the provided global flags. The default implementation requires a Flag.MESSAGE.

This method should be overridden if the user wants updates that don't require a MESSAGE to pass through.

Parameters:

update - a Telegram Update

Returns:

true if the update satisfies the global flags

getUser

protected EndUser getUser(String username)

Gets the user with the specified username.

Parameters:

username - the username of the required user

Returns:

the user

getUser

protected EndUser getUser(int id)

Gets the user with the specified ID.

Parameters:

id - the id of the required user

Returns:

the user

getUserIdSendError

protected int getUserIdSendError(String username,
                                 long chatId)

Gets the user with the specified username. If user was not found, the bot will send a message on Telegram.

Parameters:

username - the username of the required user

Returns:

the id of the user

reportCommands

public Ability reportCommands()

Format of the report:

[command1] - [description1]

[command2] - [description2]

...

Once you invoke it, the bot will send the available commands to the chat. This is a public ability so anyone can invoke it.

Usage: /commands

Returns:

the ability to report commands defined by the child bot.

backupDB

public Ability backupDB()

This backup ability returns the object defined by DBContext.backup() as a message document.

This is a high-profile ability and is restricted to the CREATOR only.

Usage: /backup

Returns:

the ability to back-up the database of the bot

recoverDB

public Ability recoverDB()

Recovers the bot database using DBContext.recover(Object).

The bot recovery process hugely depends on the implementation of the recovery method of DBContext.

Usage: /recover

Returns:

the ability to recover the database of the bot

banUser

public Ability banUser()

Banned users are accumulated in the blacklist. Use DBContext.getSet(String) with name specified by BLACKLIST.

Usage: /ban @username

Note that admins who try to ban the creator, get banned.

Returns:

the ability to ban the user from any kind of bot interaction

unbanUser

public Ability unbanUser()

Usage: /unban @username

Returns:

the ability to unban a user

promoteAdmin

public Ability promoteAdmin()

Returns:

the ability to promote a user to a bot admin

demoteAdmin

public Ability demoteAdmin()

Returns:

the ability to demote an admin to a user

claimCreator

public Ability claimCreator()

Regular users and admins who try to claim the bot will get banned.

Returns:

the ability to claim yourself as the master and creator of the bot