org.elite.jdcbot.framework
Class jDCBot

java.lang.Object
  org.elite.jdcbot.framework.DCIO
      org.elite.jdcbot.framework.InputThreadTarget
          org.elite.jdcbot.framework.jDCBot

Direct Known Subclasses:

DownloadBot, ExampleBot, SheriffBot

public abstract class jDCBot
extends InputThreadTarget

jDCBot is a Java framework for writing DC (direct connect) bots easily.

It provides an event-driven architecture to handle common DC events.

Methods of the jDCBot class can be called to send events to the DC hub that it connects to. For example, calling the SendPublicMessage method will send a public message.

To perform an action when the jDCBot receives a normal message from the hub, you would override the onPubicMessage method defined in the jDCBot class. All onXYZ methods in the PircBot class are automatically called when the event XYZ happens, so you would override these if you wish to do something when it does happen.

Since:

0.5

Version:

0.7.1

Author:

Kokanovic Branko, AppleGrew

Field Summary

private java.lang.String	_botIP
protected java.lang.String	_botname
private java.lang.String	_clientproto_supports
protected java.lang.String	_conn_type
protected java.lang.String	_description
protected java.lang.String	_email
protected java.lang.String	_hubname
private java.lang.String	_hubproto_supports
private java.lang.String	_hubSupports
private InputThread	_inputThread
protected java.net.InetAddress	_ip
private int	_listenPort
private int	_maxDownloadSlots
private int	_maxUploadSlots
private boolean	_op
protected boolean	_passive
protected java.lang.String	_password
protected int	_port
private static java.lang.String	_protoVersion
protected java.lang.String	_sharesize
private BotEventDispatchThread	dispatchThread
protected DownloadManager	downloadManager
(package private) java.io.InputStream	input
protected java.io.PrintStream	log
(package private) java.io.OutputStream	output
protected ShareManager	shareManager
protected java.net.Socket	socket
protected java.net.ServerSocket	socketServer
protected UserManager	um
protected UploadManager	uploadManager
static java.lang.String	VERSION The definitive version number of this release of jDCBot.

Constructor Summary

jDCBot(java.lang.String botIP)
Constructs a jDCBot with the default settings.

jDCBot(java.lang.String botname, java.lang.String botIP, int listenPort, java.lang.String password, java.lang.String description, java.lang.String conn_type, java.lang.String email, java.lang.String sharesize, int uploadSlots, int downloadSlots, boolean passive, java.io.PrintStream outputLog)
Constructs a jDCBot with your settings.

Method Summary

java.lang.String	botname()
void	connect(java.lang.String hostname, int port) Attempt to connect to the specified DC hub.
User[]	GetAllUsers()
java.lang.String	getBotClientProtoSupports()
java.lang.String	getBotHubProtoSupports()
BotEventDispatchThread	getDispatchThread()
int	getMaxDownloadSlots()
int	getMaxUploadSlots()
User	GetRandomUser()
ShareManager	getShareManager()
User	getUser(java.lang.String user) Gets all of user info
UserManager	getUserManager()
void	handleCommand(java.lang.String rawCommand) Handles all commands from InputThread all passes it to different methods.
java.lang.String	hubname()
java.net.Socket	initConnectToMe(java.lang.String user, java.lang.String direction)
boolean	isBotClientProtoSupports(java.lang.String feature) Checks if the bot's client-client protocol implementation supports that protocol feature.
boolean	isBotHubProtoSupports(java.lang.String feature) Checks if the bot's client-hub protocol implementation supports that protocol feature.
boolean	isConnected() Returns whether or not the jDCBot is currently connected to a hub.
boolean	isHubSupports(java.lang.String feature) Checks if the hub supports that protocol feature.
boolean	isOp()
boolean	isPassive()
void	KickUser(java.lang.String user) Kicks specified user.
void	KickUser(User user) Kicks specified user.
private java.lang.String	lock2key(java.lang.String lock) Generates key from lock needed to connect to hub.
protected void	onActiveSearch(java.lang.String IP, int port, boolean isSizeRestricted, boolean isMinimumSize, long size, int dataType, java.lang.String searchPattern) Called when user in passive mode is searching for something.
void	onBotQuit() It is called when the bot quits.
protected void	onChannelMessage(java.lang.String user, java.lang.String channel, java.lang.String message) Called when channel message in channel where bot is present is received.
protected void	onConnect() Called upon succesfully connecting to hub.
protected void	onConnect2Client()
protected void	onDisconnect() Called upon disconnecting from hub.
protected void	onDownloadComplete(User user, DUEntity due, boolean success, BotException e) Called when download is complete. Note: This method is called by DownloadHandler using jDCBot-EventDispatchThread thread.
protected void	onJoin(java.lang.String user) Called when user enter the hub.
protected void	onPassiveSearch(java.lang.String user, boolean isSizeRestricted, boolean isMinimumSize, long size, int dataType, java.lang.String searchPattern) Called when user in passive mode is searching for something.
protected void	onPrivateMessage(java.lang.String user, java.lang.String message) Called when bot receives private message.
protected void	onPublicMessage(java.lang.String user, java.lang.String message) Called when public message is received.
protected void	onQuit(java.lang.String user) Called when user quits hub.
protected void	onUpdateMyInfo(java.lang.String user) Called when some new info about the user is found.
protected void	onUploadComplete(User user, DUEntity due, boolean success, BotException e) Called when upload is complete. Note: This method is called by DownloadHandler using jDCBot-EventDispatchThread thread.
protected void	onUploadStart(User user, DUEntity due) Called when upload is starting. Note: This method is called by DownloadHandler using jDCBot-EventDispatchThread thread.
void	quit() Attemps to nicely close connection with the hub.
private java.lang.String	ReadCommand() Reading command before InputThread is started (only for connecting).
private void	replyConnectToMe(java.lang.String user, java.lang.String ip, int port)
void	SendActiveSearchReturn(java.lang.String IP, int port, boolean isDir, java.lang.String name, long size, int free_slots) Method for returning search results to active clients.
void	SendAll(java.lang.String message, long timeout) This method serves to send message to all users on the hub.
void	SendCommand(java.lang.String buffer) Sends raw command to hub.
void	SendPassiveSearchReturn(java.lang.String user, boolean isDir, java.lang.String name, long size, int free_slots) Method for returning search results to passive clients.
void	SendPrivateMessage(java.lang.String user, java.lang.String message) Sends private message to specified user.
void	SendPublicMessage(java.lang.String message) Sends public message on main chat.
void	setMaxDownloadSlots(int slots)
void	setMaxUploadSlots(int slots)
(package private) void	setOp(boolean flag) Sets if the bot is operator or not.
void	setShareManager(ShareManager sm)
void	terminate() Call this when you want to shut down framework completely.
boolean	UserExist(java.lang.String user) Checks if user is present on hub

Methods inherited from class org.elite.jdcbot.framework.DCIO

parseCmdArgs, parseCmdName, parseRawCmd, ReadCommand, ReadCommand, SendCommand, SendCommand, set_IOExceptionMsg

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final java.lang.String VERSION

The definitive version number of this release of jDCBot.

See Also:

Constant Field Values

_protoVersion

private static final java.lang.String _protoVersion

See Also:

Constant Field Values

_inputThread

private InputThread _inputThread

dispatchThread

private BotEventDispatchThread dispatchThread

socket

protected java.net.Socket socket

socketServer

protected java.net.ServerSocket socketServer

log

protected java.io.PrintStream log

input

java.io.InputStream input

output

java.io.OutputStream output

um

protected UserManager um

downloadManager

protected DownloadManager downloadManager

uploadManager

protected UploadManager uploadManager

shareManager

protected ShareManager shareManager

_botname

protected java.lang.String _botname

_password

protected java.lang.String _password

_description

protected java.lang.String _description

_conn_type

protected java.lang.String _conn_type

_email

protected java.lang.String _email

_sharesize

protected java.lang.String _sharesize

_hubname

protected java.lang.String _hubname

_passive

protected boolean _passive

_ip

protected java.net.InetAddress _ip

_port

protected int _port

_hubproto_supports

private final java.lang.String _hubproto_supports

See Also:

Constant Field Values

_clientproto_supports

private final java.lang.String _clientproto_supports

See Also:

Constant Field Values

_maxUploadSlots

private int _maxUploadSlots

_maxDownloadSlots

private int _maxDownloadSlots

_hubSupports

private java.lang.String _hubSupports

_op

private boolean _op

_botIP

private java.lang.String _botIP

_listenPort

private int _listenPort

Constructor Detail

jDCBot

public jDCBot(java.lang.String botname,
              java.lang.String botIP,
              int listenPort,
              java.lang.String password,
              java.lang.String description,
              java.lang.String conn_type,
              java.lang.String email,
              java.lang.String sharesize,
              int uploadSlots,
              int downloadSlots,
              boolean passive,
              java.io.PrintStream outputLog)

Constructs a jDCBot with your settings.

Most setting here depends on your hub. You might have to fake your share size and/or slots for hub to accept you... For details, look at DCPP wiki page of $MyINFO command

Parameters:

botname - Name of the bot as it will appear in the list of users.

botIP - Your IP.

listenPort - The port on your computer where jdcbot should listen for incoming connections from clients.

password - Passsword if required, you could put anything if no password is needed.

description - Description of your bot as it will appear in the list of users. On your description is appended standard description.

conn_type - Your connection type, for details look here

email - Your e-mail address as it will appear in the list of users.

sharesize - Size of your share in bytes.

uploadSlots - Number of upload slots for other user to connect to you.

downloadSlots - Number of download slots. This has nothing to do with DC++ protocol. This has been given to put an upper cap on no. of simultaneous downloads.

passive - Set this to fals if you are not behind a firewall.

outputLog - Almost all debug messages will be printed in this.

jDCBot

public jDCBot(java.lang.String botIP)

Constructs a jDCBot with the default settings. Your own constructors in classes which extend the jDCBot abstract class should be responsible for changing the default settings if required.

Method Detail

botname

public final java.lang.String botname()

Returns:

Name of the bot

isPassive

public final boolean isPassive()

Returns:

true if the bot/client is in Passive mode. false if it is in Active mode.

isOp

public final boolean isOp()

Returns:

Returns if the bot is Operator or not.

hubname

public final java.lang.String hubname()

Returns:

Name of the hub we're connected on

getBotHubProtoSupports

public java.lang.String getBotHubProtoSupports()

getBotClientProtoSupports

public java.lang.String getBotClientProtoSupports()

getShareManager

public ShareManager getShareManager()

getDispatchThread

public BotEventDispatchThread getDispatchThread()

getUserManager

public UserManager getUserManager()

isConnected

public boolean isConnected()

Returns whether or not the jDCBot is currently connected to a hub. The result of this method should only act as a rough guide, as the result may not be valid by the time you act upon it.

Returns:

True if and only if the jDCBot is currently connected to a hub.

isHubSupports

public boolean isHubSupports(java.lang.String feature)

Checks if the hub supports that protocol feature.

Parameters:

feature -

Returns:

isBotHubProtoSupports

public boolean isBotHubProtoSupports(java.lang.String feature)

Checks if the bot's client-hub protocol implementation supports that protocol feature.

Parameters:

feature -

Returns:

isBotClientProtoSupports

public boolean isBotClientProtoSupports(java.lang.String feature)

Checks if the bot's client-client protocol implementation supports that protocol feature.

Parameters:

feature -

Returns:

getMaxUploadSlots

public int getMaxUploadSlots()

getMaxDownloadSlots

public int getMaxDownloadSlots()

UserExist

public boolean UserExist(java.lang.String user)

Checks if user is present on hub

Parameters:

user - Nick of a user

Returns:

true if user exist on this hub, false otherwise

getUser

public User getUser(java.lang.String user)

Gets all of user info

Parameters:

user - Nick of the user

Returns:

User class that holds everything about specified user if he exist, null otherwise

GetRandomUser

public User GetRandomUser()

Returns:

Random user from the hub

GetAllUsers

public final User[] GetAllUsers()

connect

public final void connect(java.lang.String hostname,
                          int port)
                   throws java.lang.Exception

Attempt to connect to the specified DC hub. The OnConnect method is called upon success.

Parameters:

hostname - The hostname of the server to connect to.

Throws:

java.lang.Exception - if it was not possible to connect to the server.

BotException - if the server would not let us join it because of bad password or if there exist user with the same name.

initConnectToMe

public final java.net.Socket initConnectToMe(java.lang.String user,
                                             java.lang.String direction)
                                      throws java.lang.Exception

Throws:

java.lang.Exception

replyConnectToMe

private void replyConnectToMe(java.lang.String user,
                              java.lang.String ip,
                              int port)
                       throws java.lang.Exception

Throws:

java.lang.Exception

quit

public void quit()

Attemps to nicely close connection with the hub. You can call connect again to connect to the hub.

terminate

public void terminate()

Call this when you want to shut down framework completely. Unlike quit, connect is not supposed to be called after calling this method.

setOp

void setOp(boolean flag)

Sets if the bot is operator or not.

Parameters:

flag -

setShareManager

public void setShareManager(ShareManager sm)

setMaxUploadSlots

public void setMaxUploadSlots(int slots)

setMaxDownloadSlots

public void setMaxDownloadSlots(int slots)

handleCommand

public void handleCommand(java.lang.String rawCommand)

Handles all commands from InputThread all passes it to different methods.

Overrides:

handleCommand in class InputThreadTarget

Parameters:

rawCommand - Raw command sent from hub

lock2key

private final java.lang.String lock2key(java.lang.String lock)

Generates key from lock needed to connect to hub.

Parameters:

lock - Lock sent from hub

Returns:

Key which is sent back to hub to validate we know algorithm:-/

SendCommand

public final void SendCommand(java.lang.String buffer)
                       throws java.lang.Exception

Sends raw command to hub.

Parameters:

buffer - Line which needs to be send. This method won't append "|" on the end on the string if it doesn't exist, so it is up to make sure buffer ends with "|" if you calling this method.

Throws:

java.lang.Exception

ReadCommand

private final java.lang.String ReadCommand()
                                    throws java.lang.Exception

Reading command before InputThread is started (only for connecting).

Returns:

Command from hub

Throws:

java.lang.Exception

SendPublicMessage

public final void SendPublicMessage(java.lang.String message)
                             throws java.lang.Exception

Sends public message on main chat.

Parameters:

message - Message to be sent. It shouldn't end with "|".

Throws:

java.lang.Exception

SendPrivateMessage

public final void SendPrivateMessage(java.lang.String user,
                                     java.lang.String message)
                              throws java.lang.Exception

Sends private message to specified user.

Parameters:

user - User who will get message.

message - Message to be sent. It shouldn't end with "|".

Throws:

java.lang.Exception

KickUser

public final void KickUser(User user)

Kicks specified user. note that bot has to have permission to do this

Parameters:

user - User to be kicked

KickUser

public final void KickUser(java.lang.String user)

Kicks specified user. note that bot has to have permission to do this

Parameters:

user - User to be kicked

SendAll

public final void SendAll(java.lang.String message,
                          long timeout)

This method serves to send message to all users on the hub. Note that most of the hubs have a flood detection system, so you will want to set timeout interval between two message sendings, or we will get warn and/or kicked!

Parameters:

message - Message to be send to all users

timeout - Timeout interval in milliseconds between sending to two consecutive user

SendActiveSearchReturn

public final void SendActiveSearchReturn(java.lang.String IP,
                                         int port,
                                         boolean isDir,
                                         java.lang.String name,
                                         long size,
                                         int free_slots)

Method for returning search results to active clients. You hould use it carefully if you're not owner/super user of the hub 'cause this can gets you banned/kicked. Search result you will return here are imaginary (same as your sharesize).

Parameters:

IP - IP address that gave us user who was searching for returning results

port - Port that gave us user who was searching for returning results

isDir - Set true if you're returning directory, false if it is a file

name - Name of the file/dir you're returning. Note that some clients reject names that are note like the one they were searching for. This means that if someone were searching for 'firefox', and we're returned 'opera', his client won't display our result.

size - Size of the file in bytes we're returning

free_slots - How many slots we have opened/unused

SendPassiveSearchReturn

public final void SendPassiveSearchReturn(java.lang.String user,
                                          boolean isDir,
                                          java.lang.String name,
                                          long size,
                                          int free_slots)

Method for returning search results to passive clients. You hould use it carefully if you're not owner/super user of the hub 'cause this can gets you banned/kicked. Search result you will return here are imaginary (same as your sharesize).

Parameters:

user - User who was searching. Since he is in passive mode, we return result to hub

isDir - Set true if you're returning directory, false if it is a file

name - Name of the file/dir you're returning. Note that some clients reject names that are note like the one they were searching for. This means that if someone were searching for 'firefox', and we're returned 'opera', his client won't display our result.

size - Size of the file in bytes we're returning

free_slots - How many slots we have opened/unused

onConnect

protected void onConnect()

Called upon succesfully connecting to hub.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.

onConnect2Client

protected void onConnect2Client()

onBotQuit

public void onBotQuit()

It is called when the bot quits. Just after it quits, as a side-effect of closing the socket, the onDisconnect() too is called.

onDisconnect

protected void onDisconnect()

Called upon disconnecting from hub.

The implementation of this method in the jDCBot abstract class resets the _inputThread to null hence when overridden super.onDisconnect() must be called first.

Overrides:

onDisconnect in class InputThreadTarget

onPublicMessage

protected void onPublicMessage(java.lang.String user,
                               java.lang.String message)

Called when public message is received.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.

Parameters:

user - User who sent message.

message - Contents of the message.

onJoin

protected void onJoin(java.lang.String user)

Called when user enter the hub.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.

Parameters:

user - Nema of the user who entered hub.

onQuit

protected void onQuit(java.lang.String user)

Called when user quits hub.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.

Parameters:

user - of user quited hub.

onUpdateMyInfo

protected void onUpdateMyInfo(java.lang.String user)

Called when some new info about the user is found. Like his IP, Passive/Active state, etc.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.
Note: This method is called by User and UserManager using jDCBot-EventDispatchThread thread.

Parameters:

user - The user from the hub.

onPrivateMessage

protected void onPrivateMessage(java.lang.String user,
                                java.lang.String message)

Called when bot receives private message.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.

Parameters:

user - Name of user who sent us private message.

message - Contents of private message.

onChannelMessage

protected void onChannelMessage(java.lang.String user,
                                java.lang.String channel,
                                java.lang.String message)

Called when channel message in channel where bot is present is received.

The implementation of this method in the jDCBot abstract class performs no actions and may be overridden as required.

Parameters:

user - Name of the user who sent message.

channel - Channel on which message is sent.

message - Contents of the channel message.

onPassiveSearch

protected void onPassiveSearch(java.lang.String user,
                               boolean isSizeRestricted,
                               boolean isMinimumSize,
                               long size,
                               int dataType,
                               java.lang.String searchPattern)

Called when user in passive mode is searching for something. For specific details, (like meaning of dataType field and syntax of searchPattern) you should consult direct connect protocol documentation like: http://dc.selwerd.nl/doc/Command_Types_(client_to_server).html

Parameters:

user - User who is searching

isSizeRestricted - true if user restricted search result for minimum/maximum file size. If false, isMinimumSize and size should not be used and has no meaning

isMinimumSize - true if user restricted his search to file that has minimum size, false if user restricted search result to maximum size. Used only if isSizeRestricted=true

size - Size that user restricted his search. Is it minimum od maximum size is contained in isMimimumSizeUsed only if isSizeRestricted=true

dataType - Type of the data user is searching for.

searchPattern - Pattern user is searching for.

onActiveSearch

protected void onActiveSearch(java.lang.String IP,
                              int port,
                              boolean isSizeRestricted,
                              boolean isMinimumSize,
                              long size,
                              int dataType,
                              java.lang.String searchPattern)

Called when user in passive mode is searching for something. For specific details, (like meaning of dataType field and syntax of searchPattern) you should consult direct connect protocol documentation like: http://dc.selwerd.nl/doc/Command_Types_(client_to_server).html

Parameters:

IP - IP address user who was searching gave to deliver search results

port - Port user who was searching gave to deliver search results

isSizeRestricted - true if user restricted search result for minimum/maximum file size. If false, isMinimumSize and size should not be used and has no meaning

isMinimumSize - true if user restricted his search to file that has minimum size, false if user restricted search result to maximum size. Used only if isSizeRestricted=true

size - Size that user restricted his search. Is it minimum od maximum size is contained in isMimimumSizeUsed only if isSizeRestricted=true

dataType - Type of the data user is searching for.

searchPattern - Pattern user is searching for.

onDownloadComplete

protected void onDownloadComplete(User user,
                                  DUEntity due,
                                  boolean success,
                                  BotException e)

Called when download is complete.
Note: This method is called by DownloadHandler using jDCBot-EventDispatchThread thread.

Parameters:

user - The user from whom the file was downloaded.

due - The informations about the file downloaded is in this.

success - It is true if download was successful else false.

e - The exception that occured when sucess is false else it is null.

onUploadComplete

protected void onUploadComplete(User user,
                                DUEntity due,
                                boolean success,
                                BotException e)

Called when upload is complete.
Note: This method is called by DownloadHandler using jDCBot-EventDispatchThread thread.

Parameters:

user - The user to whom the file was uploaded.

due - The informations about the file uploaded is in this.

success - It is true if upload was successful else false.

e - The exception that occured when sucess is false else it is null.

onUploadStart

protected void onUploadStart(User user,
                             DUEntity due)

Called when upload is starting.
Note: This method is called by DownloadHandler using jDCBot-EventDispatchThread thread.

Parameters:

user - The user to whom the file is being uploaded.

due - The informations about the file downloaded is in this.