net.dv8tion.jda.JDABuilder Maven / Gradle / Ivy
Show all versions of JDA Show documentation
/**
* Copyright 2015 Austin Keener & Michael Ritter
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dv8tion.jda;
import net.dv8tion.jda.entities.impl.JDAImpl;
import net.dv8tion.jda.events.ReadyEvent;
import net.dv8tion.jda.hooks.EventListener;
import net.dv8tion.jda.hooks.ListenerAdapter;
import javax.security.auth.login.LoginException;
import java.util.LinkedList;
import java.util.List;
import java.util.concurrent.atomic.AtomicBoolean;
/**
* Used to create a new {@link net.dv8tion.jda.JDA} instance. This is useful for making sure all of
* your {@link net.dv8tion.jda.hooks.EventListener EventListeners} as registered
* before {@link net.dv8tion.jda.JDA} attempts to log in.
*
* A single JDABuilder can be reused multiple times. Each call to
* {@link net.dv8tion.jda.JDABuilder#build() build()} or
* {@link net.dv8tion.jda.JDABuilder#buildBlocking() buildBlocking()}
* creates a new {@link net.dv8tion.jda.JDA} instance using the same information.
* This means that you can have listeners easily registered to multiple {@link net.dv8tion.jda.JDA} instances.
*/
public class JDABuilder
{
List listeners;
String email = null;
String pass = null;
/**
* Creates a completely empty JDABuilder.
* If you use this, you need to set the email and password using
* {@link net.dv8tion.jda.JDABuilder#setEmail(String) setEmail(String)}
* and {@link net.dv8tion.jda.JDABuilder#setPassword(String) setPassword(String)}
* before calling {@link net.dv8tion.jda.JDABuilder#build() build()}
* or {@link net.dv8tion.jda.JDABuilder#buildBlocking() buildBlocking()}
*/
public JDABuilder()
{
this(null, null);
}
/**
* Creates a new JDABuilder using the provided email and password.
*
* @param email
* The email of the account that will be used to log into Discord.
* @param password
* The password of the account that will be used to log into Discord.
*/
public JDABuilder(String email, String password)
{
this.email = email;
this.pass = password;
listeners = new LinkedList();
}
/**
* Sets the email that will be used by the {@link net.dv8tion.jda.JDA} instance to log in when
* {@link net.dv8tion.jda.JDABuilder#build() build()}
* or {@link net.dv8tion.jda.JDABuilder#buildBlocking() buildBlocking()}
* is called.
*
* @param email
* The email of the account that you would like to login with.
* @return
* Returns the {@link net.dv8tion.jda.JDABuilder JDABuilder} instance. Useful for chaining.
*/
public JDABuilder setEmail(String email)
{
this.email = email;
return this;
}
/**
* Sets the password that will be used by the {@link net.dv8tion.jda.JDA} instance to log in when
* {@link net.dv8tion.jda.JDABuilder#build() build()}
* or {@link net.dv8tion.jda.JDABuilder#buildBlocking() buildBlocking()}
* is called.
*
* @param password
* The password of the account that you would like to login with.
* @return
* Returns the {@link net.dv8tion.jda.JDABuilder JDABuilder} instance. Useful for chaining.
*/
public JDABuilder setPassword(String password)
{
this.pass = password;
return this;
}
/**
* Adds a listener to the list of listeners that will be used to populate the {@link net.dv8tion.jda.JDA} object.
*
* @param listener
* The listener to add to the list.
* @return
* Returns the {@link net.dv8tion.jda.JDABuilder JDABuilder} instance. Useful for chaining.
*/
public JDABuilder addListener(EventListener listener)
{
listeners.add(listener);
return this;
}
/**
* Removes a listener from the list of listeners.
*
* @param listener
* The listener to remove from the list.
* @return
* Returns the net.dv8tion.jda.JDABuilder instance. Useful for chaining.
*/
public JDABuilder removeListener(EventListener listener)
{
listeners.remove(listener);
return this;
}
/**
* Builds a new {@link net.dv8tion.jda.JDA} instance and uses the provided email and password to start the login process.
* The login process runs in a different thread, so while this will return immediately, {@link net.dv8tion.jda.JDA} has not
* finished loading, thus many {@link net.dv8tion.jda.JDA} methods have the chance to return incorrect information.
*
* If you wish to be sure that the {@link net.dv8tion.jda.JDA} information is correct, please use
* {@link net.dv8tion.jda.JDABuilder#buildBlocking() buildBlocking()} or register a
* {@link net.dv8tion.jda.events.ReadyEvent ReadyEvent} {@link net.dv8tion.jda.hooks.EventListener EventListener}.
*
* @return
* A {@link net.dv8tion.jda.JDA} instance that has started the login process. It is unknown as to whether or not loading has finished when this returns.
* @throws LoginException
* If the provided email-password combination fails the Discord security authentication.
* @throws IllegalArgumentException
* If either the provided email or password is empty or null.
*/
public JDA build() throws LoginException, IllegalArgumentException
{
JDAImpl jda = new JDAImpl();
listeners.forEach(listener -> jda.addEventListener(listener));
jda.login(email, pass);
return jda;
}
/**
* Builds a new {@link net.dv8tion.jda.JDA} instance and uses the provided email and password to start the login process.
* This method will block until JDA has logged in and finished loading all resources. This is an alternative
* to using {@link net.dv8tion.jda.events.ReadyEvent ReadyEvent}.
*
* @return
* A {@link net.dv8tion.jda.JDA} Object that is guaranteed to be logged in and finished loading.
* @throws LoginException
* If the provided email-password combination fails the Discord security authentication.
* @throws IllegalArgumentException
* If either the provided email or password is empty or null.
* @throws InterruptedException
* If an interrupt request is received while waiting for {@link net.dv8tion.jda.JDA} to finish logging in.
* This would most likely be caused by a JVM shutdown request.
*/
public JDA buildBlocking() throws LoginException, IllegalArgumentException, InterruptedException
{
//Create our ReadyListener and a thread safe Boolean.
AtomicBoolean ready = new AtomicBoolean(false);
ListenerAdapter readyListener = new ListenerAdapter()
{
@Override
public void onReady(ReadyEvent event)
{
ready.set(true);
}
};
//Add it to our list of listeners, start the login process, wait for the ReadyEvent.
listeners.add(readyListener);
JDA jda = build();
while(!ready.get())
{
Thread.sleep(50);
}
//We have logged in. Remove the temp ready listener from our local list and the jda listener list.
listeners.remove(readyListener);
jda.removeEventListener(readyListener);
return jda;
}
}