SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
paper-api/src/main/java/org/bukkit/conversations/BooleanPrompt.java
View File

@@ -4,7 +4,8 @@ import org.apache.commons.lang.ArrayUtils;
import org.apache.commons.lang.BooleanUtils;
/**
* BooleanPrompt is the base class for any prompt that requires a boolean response from the user.
* BooleanPrompt is the base class for any prompt that requires a boolean
* response from the user.
*/
public abstract class BooleanPrompt extends ValidatingPrompt{
@@ -24,7 +25,8 @@ public abstract class BooleanPrompt extends ValidatingPrompt{
}
/**
* Override this method to perform some action with the user's boolean response.
* Override this method to perform some action with the user's boolean
* response.
*
* @param context Context information about the conversation.
* @param input The user's boolean response.

13
paper-api/src/main/java/org/bukkit/conversations/Conversable.java
View File

@@ -3,20 +3,22 @@ package org.bukkit.conversations;
import org.bukkit.command.CommandSender;
/**
* The Conversable interface is used to indicate objects that can have conversations.
* The Conversable interface is used to indicate objects that can have
* conversations.
*/
public interface Conversable {
/**
* Tests to see of a Conversable object is actively engaged in a conversation.
* Tests to see of a Conversable object is actively engaged in a
* conversation.
*
* @return True if a conversation is in progress
*/
public boolean isConversing();
/**
* Accepts input into the active conversation. If no conversation is in progress,
* this method does nothing.
* Accepts input into the active conversation. If no conversation is in
* progress, this method does nothing.
*
* @param input The input message into the conversation
*/
@@ -26,7 +28,8 @@ public interface Conversable {
* Enters into a dialog with a Conversation object.
*
* @param conversation The conversation to begin
* @return True if the conversation should proceed, false if it has been enqueued
* @return True if the conversation should proceed, false if it has been
* enqueued
*/
public boolean beginConversation(Conversation conversation);

82
paper-api/src/main/java/org/bukkit/conversations/Conversation.java
View File

@@ -8,23 +8,29 @@ import java.util.List;
import java.util.Map;
/**
* The Conversation class is responsible for tracking the current state of a conversation, displaying prompts to
* the user, and dispatching the user's response to the appropriate place. Conversation objects are not typically
* instantiated directly. Instead a {@link ConversationFactory} is used to construct identical conversations on demand.
* The Conversation class is responsible for tracking the current state of a
* conversation, displaying prompts to the user, and dispatching the user's
* response to the appropriate place. Conversation objects are not typically
* instantiated directly. Instead a {@link ConversationFactory} is used to
* construct identical conversations on demand.
* <p>
* Conversation flow consists of a directed graph of {@link Prompt} objects. Each time a prompt gets input from the
* user, it must return the next prompt in the graph. Since each Prompt chooses the next Prompt, complex conversation
* trees can be implemented where the nature of the player's response directs the flow of the conversation.
* Conversation flow consists of a directed graph of {@link Prompt} objects.
* Each time a prompt gets input from the user, it must return the next prompt
* in the graph. Since each Prompt chooses the next Prompt, complex
* conversation trees can be implemented where the nature of the player's
* response directs the flow of the conversation.
* <p>
* Each conversation has a {@link ConversationPrefix} that prepends all output from the conversation to the player.
* The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves.
* Each conversation has a {@link ConversationPrefix} that prepends all output
* from the conversation to the player. The ConversationPrefix can be used to
* display the plugin name or conversation status as the conversation evolves.
* <p>
* Each conversation has a timeout measured in the number of inactive seconds to wait before abandoning the conversation.
* If the inactivity timeout is reached, the conversation is abandoned and the user's incoming and outgoing chat is
* returned to normal.
* Each conversation has a timeout measured in the number of inactive seconds
* to wait before abandoning the conversation. If the inactivity timeout is
* reached, the conversation is abandoned and the user's incoming and outgoing
* chat is returned to normal.
* <p>
* You should not construct a conversation manually. Instead, use the {@link ConversationFactory} for access to all
* available options.
* You should not construct a conversation manually. Instead, use the {@link
* ConversationFactory} for access to all available options.
*/
public class Conversation {
@@ -55,7 +61,8 @@ public class Conversation {
* @param plugin The plugin that owns this conversation.
* @param forWhom The entity for whom this conversation is mediating.
* @param firstPrompt The first prompt in the conversation graph.
* @param initialSessionData Any initial values to put in the conversation context sessionData map.
* @param initialSessionData Any initial values to put in the conversation
* context sessionData map.
*/
public Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt, Map<Object, Object> initialSessionData) {
this.firstPrompt = firstPrompt;
@@ -77,8 +84,9 @@ public class Conversation {
}
/**
* Gets the modality of this conversation. If a conversation is modal, all messages directed to the player
* are suppressed for the duration of the conversation.
* Gets the modality of this conversation. If a conversation is modal, all
* messages directed to the player are suppressed for the duration of the
* conversation.
*
* @return The conversation modality.
*/
@@ -87,8 +95,9 @@ public class Conversation {
}
/**
* Sets the modality of this conversation. If a conversation is modal, all messages directed to the player
* are suppressed for the duration of the conversation.
* Sets the modality of this conversation. If a conversation is modal,
* all messages directed to the player are suppressed for the duration of
* the conversation.
*
* @param modal The new conversation modality.
*/
@@ -97,8 +106,9 @@ public class Conversation {
}
/**
* Gets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation
* gets echoed back into the submitter's chat window.
* Gets the status of local echo for this conversation. If local echo is
* enabled, any text submitted to a conversation gets echoed back into the
* submitter's chat window.
*
* @return The status of local echo.
*/
@@ -107,8 +117,9 @@ public class Conversation {
}
/**
* Sets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation
* gets echoed back into the submitter's chat window.
* Sets the status of local echo for this conversation. If local echo is
* enabled, any text submitted to a conversation gets echoed back into the
* submitter's chat window.
*
* @param localEchoEnabled The status of local echo.
*/
@@ -117,7 +128,8 @@ public class Conversation {
}
/**
* Gets the {@link ConversationPrefix} that prepends all output from this conversation.
* Gets the {@link ConversationPrefix} that prepends all output from this
* conversation.
*
* @return The ConversationPrefix in use.
*/
@@ -126,7 +138,8 @@ public class Conversation {
}
/**
* Sets the {@link ConversationPrefix} that prepends all output from this conversation.
* Sets the {@link ConversationPrefix} that prepends all output from this
* conversation.
*
* @param prefix The ConversationPrefix to use.
*/
@@ -163,7 +176,8 @@ public class Conversation {
}
/**
* Displays the first prompt of this conversation and begins redirecting the user's chat responses.
* Displays the first prompt of this conversation and begins redirecting
* the user's chat responses.
*/
public void begin() {
if (currentPrompt == null) {
@@ -175,6 +189,7 @@ public class Conversation {
/**
* Returns Returns the current state of the conversation.
*
* @return The current state of the conversation.
*/
public ConversationState getState() {
@@ -188,8 +203,9 @@ public class Conversation {
}
/**
* Passes player input into the current prompt. The next prompt (as determined by the current prompt) is then
* displayed to the user.
* Passes player input into the current prompt. The next prompt (as
* determined by the current prompt) is then displayed to the user.
*
* @param input The user's chat text.
*/
public void acceptInput(String input) {
@@ -216,6 +232,7 @@ public class Conversation {
/**
* Adds a {@link ConversationAbandonedListener}.
*
* @param listener The listener to add.
*/
public synchronized void addConversationAbandonedListener(ConversationAbandonedListener listener) {
@@ -224,6 +241,7 @@ public class Conversation {
/**
* Removes a {@link ConversationAbandonedListener}.
*
* @param listener The listener to remove.
*/
public synchronized void removeConversationAbandonedListener(ConversationAbandonedListener listener) {
@@ -231,14 +249,17 @@ public class Conversation {
}
/**
* Abandons and resets the current conversation. Restores the user's normal chat behavior.
* Abandons and resets the current conversation. Restores the user's
* normal chat behavior.
*/
public void abandon() {
abandon(new ConversationAbandonedEvent(this, new ManuallyAbandonedConversationCanceller()));
}
/**
* Abandons and resets the current conversation. Restores the user's normal chat behavior.
* Abandons and resets the current conversation. Restores the user's
* normal chat behavior.
*
* @param details Details about why the conversation was abandoned
*/
public synchronized void abandon(ConversationAbandonedEvent details) {
@@ -253,7 +274,8 @@ public class Conversation {
}
/**
* Displays the next user prompt and abandons the conversation if the next prompt is null.
* Displays the next user prompt and abandons the conversation if the next
* prompt is null.
*/
public void outputNextPrompt() {
if (currentPrompt == null) {

12
paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.conversations;
import java.util.EventObject;
/**
* ConversationAbandonedEvent contains information about an abandoned conversation.
* ConversationAbandonedEvent contains information about an abandoned
* conversation.
*/
public class ConversationAbandonedEvent extends EventObject {
@@ -39,11 +40,12 @@ public class ConversationAbandonedEvent extends EventObject {
}
/**
* Indicates how the conversation was abandoned - naturally as part of the prompt chain or prematurely via a
* {@link ConversationCanceller}.
* Indicates how the conversation was abandoned - naturally as part of the
* prompt chain or prematurely via a {@link ConversationCanceller}.
*
* @return True if the conversation is abandoned gracefully by a {@link Prompt} returning null
* or the next prompt. False of the conversations is abandoned prematurely by a ConversationCanceller.
* @return True if the conversation is abandoned gracefully by a {@link
* Prompt} returning null or the next prompt. False of the
* conversations is abandoned prematurely by a ConversationCanceller.
*/
public boolean gracefulExit() {
return canceller == null;

3
paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java
View File

@@ -8,7 +8,8 @@ public interface ConversationAbandonedListener extends EventListener {
/**
* Called whenever a {@link Conversation} is abandoned.
*
* @param abandonedEvent Contains details about the abandoned conversation.
* @param abandonedEvent Contains details about the abandoned
* conversation.
*/
public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent);
}

7
paper-api/src/main/java/org/bukkit/conversations/ConversationCanceller.java
View File

@@ -1,8 +1,8 @@
package org.bukkit.conversations;
/**
* A ConversationCanceller is a class that cancels an active {@link Conversation}. A Conversation can have more
* than one ConversationCanceller.
* A ConversationCanceller is a class that cancels an active {@link
* Conversation}. A Conversation can have more than one ConversationCanceller.
*/
public interface ConversationCanceller extends Cloneable {
@@ -23,7 +23,8 @@ public interface ConversationCanceller extends Cloneable {
public boolean cancelBasedOnInput(ConversationContext context, String input);
/**
* Allows the {@link ConversationFactory} to duplicate this ConversationCanceller when creating a new {@link Conversation}.
* Allows the {@link ConversationFactory} to duplicate this
* ConversationCanceller when creating a new {@link Conversation}.
* <p>
* Implementing this method should reset any internal object state.
*

18
paper-api/src/main/java/org/bukkit/conversations/ConversationContext.java
View File

@@ -5,8 +5,9 @@ import org.bukkit.plugin.Plugin;
import java.util.Map;
/**
* A ConversationContext provides continuity between nodes in the prompt graph by giving the developer access to the
* subject of the conversation and a generic map for storing values that are shared between all {@link Prompt}
* A ConversationContext provides continuity between nodes in the prompt graph
* by giving the developer access to the subject of the conversation and a
* generic map for storing values that are shared between all {@link Prompt}
* invocations.
*/
public class ConversationContext {
@@ -17,7 +18,8 @@ public class ConversationContext {
/**
* @param plugin The owning plugin.
* @param forWhom The subject of the conversation.
* @param initialSessionData Any initial values to put in the sessionData map.
* @param initialSessionData Any initial values to put in the sessionData
* map.
*/
public ConversationContext(Plugin plugin, Conversable forWhom, Map<Object, Object> initialSessionData) {
this.plugin = plugin;
@@ -44,8 +46,9 @@ public class ConversationContext {
}
/**
* Gets session data shared between all {@link Prompt} invocations. Use this as a way
* to pass data through each Prompt as the conversation develops.
* Gets session data shared between all {@link Prompt} invocations. Use
* this as a way to pass data through each Prompt as the conversation
* develops.
*
* @param key The session data key.
* @return The requested session data.
@@ -55,8 +58,9 @@ public class ConversationContext {
}
/**
* Sets session data shared between all {@link Prompt} invocations. Use this as a way to pass
* data through each prompt as the conversation develops.
* Sets session data shared between all {@link Prompt} invocations. Use
* this as a way to pass data through each prompt as the conversation
* develops.
*
* @param key The session data key.
* @param value The session data value.

48
paper-api/src/main/java/org/bukkit/conversations/ConversationFactory.java
View File

@@ -9,11 +9,14 @@ import java.util.List;
import java.util.Map;
/**
* A ConversationFactory is responsible for creating a {@link Conversation} from a predefined template. A ConversationFactory
* is typically created when a plugin is instantiated and builds a Conversation each time a user initiates a conversation
* with the plugin. Each Conversation maintains its own state and calls back as needed into the plugin.
* A ConversationFactory is responsible for creating a {@link Conversation}
* from a predefined template. A ConversationFactory is typically created when
* a plugin is instantiated and builds a Conversation each time a user
* initiates a conversation with the plugin. Each Conversation maintains its
* own state and calls back as needed into the plugin.
* <p>
* The ConversationFactory implements a fluid API, allowing parameters to be set as an extension to the constructor.
* The ConversationFactory implements a fluid API, allowing parameters to be
* set as an extension to the constructor.
*/
public class ConversationFactory {
@@ -46,8 +49,9 @@ public class ConversationFactory {
}
/**
* Sets the modality of all {@link Conversation}s created by this factory. If a conversation is modal, all messages
* directed to the player are suppressed for the duration of the conversation.
* Sets the modality of all {@link Conversation}s created by this factory.
* If a conversation is modal, all messages directed to the player are
* suppressed for the duration of the conversation.
* <p>
* The default is True.
*
@@ -61,8 +65,9 @@ public class ConversationFactory {
}
/**
* Sets the local echo status for all {@link Conversation}s created by this factory. If local echo is enabled,
* any text submitted to a conversation gets echoed back into the submitter's chat window.
* Sets the local echo status for all {@link Conversation}s created by
* this factory. If local echo is enabled, any text submitted to a
* conversation gets echoed back into the submitter's chat window.
*
* @param localEchoEnabled The status of local echo.
* @return This object.
@@ -73,7 +78,8 @@ public class ConversationFactory {
}
/**
* Sets the {@link ConversationPrefix} that prepends all output from all generated conversations.
* Sets the {@link ConversationPrefix} that prepends all output from all
* generated conversations.
* <p>
* The default is a {@link NullConversationPrefix};
*
@@ -86,7 +92,8 @@ public class ConversationFactory {
}
/**
* Sets the number of inactive seconds to wait before automatically abandoning all generated conversations.
* Sets the number of inactive seconds to wait before automatically
* abandoning all generated conversations.
* <p>
* The default is 600 seconds (5 minutes).
*
@@ -111,9 +118,11 @@ public class ConversationFactory {
}
/**
* Sets any initial data with which to populate the conversation context sessionData map.
* Sets any initial data with which to populate the conversation context
* sessionData map.
*
* @param initialSessionData The conversation context's initial sessionData.
* @param initialSessionData The conversation context's initial
* sessionData.
* @return This object.
*/
public ConversationFactory withInitialSessionData(Map<Object, Object> initialSessionData) {
@@ -122,7 +131,8 @@ public class ConversationFactory {
}
/**
* Sets the player input that, when received, will immediately terminate the conversation.
* Sets the player input that, when received, will immediately terminate
* the conversation.
*
* @param escapeSequence Input to terminate the conversation.
* @return This object.
@@ -144,9 +154,11 @@ public class ConversationFactory {
}
/**
* Prevents this factory from creating a conversation for non-player {@link Conversable} objects.
* Prevents this factory from creating a conversation for non-player
* {@link Conversable} objects.
*
* @param playerOnlyMessage The message to return to a non-play in lieu of starting a conversation.
* @param playerOnlyMessage The message to return to a non-play in lieu of
* starting a conversation.
* @return This object.
*/
public ConversationFactory thatExcludesNonPlayersWithMessage(String playerOnlyMessage) {
@@ -155,7 +167,8 @@ public class ConversationFactory {
}
/**
* Adds a {@link ConversationAbandonedListener} to all conversations constructed by this factory.
* Adds a {@link ConversationAbandonedListener} to all conversations
* constructed by this factory.
*
* @param listener The listener to add.
* @return This object.
@@ -166,7 +179,8 @@ public class ConversationFactory {
}
/**
* Constructs a {@link Conversation} in accordance with the defaults set for this factory.
* Constructs a {@link Conversation} in accordance with the defaults set
* for this factory.
*
* @param forWhom The entity for whom the new conversation is mediating.
* @return A new conversation.

5
paper-api/src/main/java/org/bukkit/conversations/ConversationPrefix.java
View File

@@ -3,8 +3,9 @@ package org.bukkit.conversations;
import org.bukkit.command.CommandSender;
/**
* A ConversationPrefix implementation prepends all output from the conversation to the player.
* The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves.
* A ConversationPrefix implementation prepends all output from the
* conversation to the player. The ConversationPrefix can be used to display
* the plugin name or conversation status as the conversation evolves.
*/
public interface ConversationPrefix {

6
paper-api/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java
View File

@@ -1,7 +1,8 @@
package org.bukkit.conversations;
/**
* An ExactMatchConversationCanceller cancels a conversation if the user enters an exact input string
* An ExactMatchConversationCanceller cancels a conversation if the user
* enters an exact input string
*/
public class ExactMatchConversationCanceller implements ConversationCanceller {
private String escapeSequence;
@@ -9,7 +10,8 @@ public class ExactMatchConversationCanceller implements ConversationCanceller {
/**
* Builds an ExactMatchConversationCanceller.
*
* @param escapeSequence The string that, if entered by the user, will cancel the conversation.
* @param escapeSequence The string that, if entered by the user, will
* cancel the conversation.
*/
public ExactMatchConversationCanceller(String escapeSequence) {
this.escapeSequence = escapeSequence;

13
paper-api/src/main/java/org/bukkit/conversations/FixedSetPrompt.java
View File

@@ -6,7 +6,8 @@ import java.util.Arrays;
import java.util.List;
/**
* FixedSetPrompt is the base class for any prompt that requires a fixed set response from the user.
* FixedSetPrompt is the base class for any prompt that requires a fixed set
* response from the user.
*/
public abstract class FixedSetPrompt extends ValidatingPrompt {
@@ -14,9 +15,11 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
/**
* Creates a FixedSetPrompt from a set of strings.
* <p>
* foo = new FixedSetPrompt("bar", "cheese", "panda");
*
* @param fixedSet A fixed set of strings, one of which the user must type.
* @param fixedSet A fixed set of strings, one of which the user must
* type.
*/
public FixedSetPrompt(String... fixedSet) {
super();
@@ -31,9 +34,11 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
}
/**
* Utility function to create a formatted string containing all the options declared in the constructor.
* Utility function to create a formatted string containing all the
* options declared in the constructor.
*
* @return the options formatted like "[bar, cheese, panda]" if bar, cheese, and panda were the options used
* @return the options formatted like "[bar, cheese, panda]" if bar,
* cheese, and panda were the options used
*/
protected String formatFixedSet() {
return "[" + StringUtils.join(fixedSet, ", ") + "]";

8
paper-api/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java
View File

@@ -4,7 +4,8 @@ import org.bukkit.Server;
import org.bukkit.plugin.Plugin;
/**
* An InactivityConversationCanceller will cancel a {@link Conversation} after a period of inactivity by the user.
* An InactivityConversationCanceller will cancel a {@link Conversation} after
* a period of inactivity by the user.
*/
public class InactivityConversationCanceller implements ConversationCanceller {
protected Plugin plugin;
@@ -66,8 +67,9 @@ public class InactivityConversationCanceller implements ConversationCanceller {
}
/**
* Subclasses of InactivityConversationCanceller can override this method to take additional actions when the
* inactivity timer abandons the conversation.
* Subclasses of InactivityConversationCanceller can override this method
* to take additional actions when the inactivity timer abandons the
* conversation.
*
* @param conversation The conversation being abandoned.
*/

5
paper-api/src/main/java/org/bukkit/conversations/ManuallyAbandonedConversationCanceller.java
View File

@@ -1,8 +1,9 @@
package org.bukkit.conversations;
/**
* The ManuallyAbandonedConversationCanceller is only used as part of a {@link ConversationAbandonedEvent} to indicate
* that the conversation was manually abandoned by programatically calling the abandon() method on it.
* The ManuallyAbandonedConversationCanceller is only used as part of a {@link
* ConversationAbandonedEvent} to indicate that the conversation was manually
* abandoned by programmatically calling the abandon() method on it.
*/
public class ManuallyAbandonedConversationCanceller implements ConversationCanceller{
public void setConversation(Conversation conversation) {

6
paper-api/src/main/java/org/bukkit/conversations/MessagePrompt.java
View File

@@ -1,7 +1,8 @@
package org.bukkit.conversations;
/**
* MessagePrompt is the base class for any prompt that only displays a message to the user and requires no input.
* MessagePrompt is the base class for any prompt that only displays a message
* to the user and requires no input.
*/
public abstract class MessagePrompt implements Prompt{
@@ -20,7 +21,8 @@ public abstract class MessagePrompt implements Prompt{
}
/**
* Accepts and ignores any user input, returning the next prompt in the prompt graph instead.
* Accepts and ignores any user input, returning the next prompt in the
* prompt graph instead.
*
* @param context Context information about the conversation.
* @param input Ignored.

4
paper-api/src/main/java/org/bukkit/conversations/NullConversationPrefix.java
View File

@@ -3,8 +3,8 @@ package org.bukkit.conversations;
import org.bukkit.command.CommandSender;
/**
* NullConversationPrefix is a {@link ConversationPrefix} implementation that displays nothing in front of
* conversation output.
* NullConversationPrefix is a {@link ConversationPrefix} implementation that
* displays nothing in front of conversation output.
*/
public class NullConversationPrefix implements ConversationPrefix{

16
paper-api/src/main/java/org/bukkit/conversations/NumericPrompt.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.conversations;
import org.apache.commons.lang.math.NumberUtils;
/**
* NumericPrompt is the base class for any prompt that requires a {@link Number} response from the user.
* NumericPrompt is the base class for any prompt that requires a {@link
* Number} response from the user.
*/
public abstract class NumericPrompt extends ValidatingPrompt{
public NumericPrompt() {
@@ -16,8 +17,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
}
/**
* Override this method to do further validation on the numeric player input after the input has been determined
* to actually be a number.
* Override this method to do further validation on the numeric player
* input after the input has been determined to actually be a number.
*
* @param context Context information about the conversation.
* @param input The number the player provided.
@@ -38,7 +39,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
}
/**
* Override this method to perform some action with the user's integer response.
* Override this method to perform some action with the user's integer
* response.
*
* @param context Context information about the conversation.
* @param input The user's response as a {@link Number}.
@@ -56,7 +58,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
}
/**
* Optionally override this method to display an additional message if the user enters an invalid number.
* Optionally override this method to display an additional message if the
* user enters an invalid number.
*
* @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user.
@@ -67,7 +70,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
}
/**
* Optionally override this method to display an additional message if the user enters an invalid numeric input.
* Optionally override this method to display an additional message if the
* user enters an invalid numeric input.
*
* @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user.

6
paper-api/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java
View File

@@ -4,7 +4,8 @@ import org.bukkit.entity.Player;
import org.bukkit.plugin.Plugin;
/**
* PlayerNamePrompt is the base class for any prompt that requires the player to enter another player's name.
* PlayerNamePrompt is the base class for any prompt that requires the player
* to enter another player's name.
*/
public abstract class PlayerNamePrompt extends ValidatingPrompt{
private Plugin plugin;
@@ -26,7 +27,8 @@ public abstract class PlayerNamePrompt extends ValidatingPrompt{
}
/**
* Override this method to perform some action with the user's player name response.
* Override this method to perform some action with the user's player name
* response.
*
* @param context Context information about the conversation.
* @param input The user's player name response.

4
paper-api/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java
View File

@@ -5,8 +5,8 @@ import org.bukkit.command.CommandSender;
import org.bukkit.plugin.Plugin;
/**
* PluginNameConversationPrefix is a {@link ConversationPrefix} implementation that displays the plugin name in front of
* conversation output.
* PluginNameConversationPrefix is a {@link ConversationPrefix} implementation
* that displays the plugin name in front of conversation output.
*/
public class PluginNameConversationPrefix implements ConversationPrefix {

20
paper-api/src/main/java/org/bukkit/conversations/Prompt.java
View File

@@ -1,9 +1,11 @@
package org.bukkit.conversations;
/**
* A Prompt is the main constituent of a {@link Conversation}. Each prompt displays text to the user and optionally
* waits for a user's response. Prompts are chained together into a directed graph that represents the conversation
* flow. To halt a conversation, END_OF_CONVERSATION is returned in liu of another Prompt object.
* A Prompt is the main constituent of a {@link Conversation}. Each prompt
* displays text to the user and optionally waits for a user's response.
* Prompts are chained together into a directed graph that represents the
* conversation flow. To halt a conversation, END_OF_CONVERSATION is returned
* in liu of another Prompt object.
*/
public interface Prompt extends Cloneable {
@@ -13,7 +15,8 @@ public interface Prompt extends Cloneable {
static final Prompt END_OF_CONVERSATION = null;
/**
* Gets the text to display to the user when this prompt is first presented.
* Gets the text to display to the user when this prompt is first
* presented.
*
* @param context Context information about the conversation.
* @return The text to display.
@@ -21,15 +24,18 @@ public interface Prompt extends Cloneable {
String getPromptText(ConversationContext context);
/**
* Checks to see if this prompt implementation should wait for user input or immediately display the next prompt.
* Checks to see if this prompt implementation should wait for user input
* or immediately display the next prompt.
*
* @param context Context information about the conversation.
* @return If true, the {@link Conversation} will wait for input before continuing.
* @return If true, the {@link Conversation} will wait for input before
* continuing.
*/
boolean blocksForInput(ConversationContext context);
/**
* Accepts and processes input from the user. Using the input, the next Prompt in the prompt graph is returned.
* Accepts and processes input from the user. Using the input, the next
* Prompt in the prompt graph is returned.
*
* @param context Context information about the conversation.
* @param input The input text from the user.

3
paper-api/src/main/java/org/bukkit/conversations/RegexPrompt.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.conversations;
import java.util.regex.Pattern;
/**
* RegexPrompt is the base class for any prompt that requires an input validated by a regular expression.
* RegexPrompt is the base class for any prompt that requires an input
* validated by a regular expression.
*/
public abstract class RegexPrompt extends ValidatingPrompt {

3
paper-api/src/main/java/org/bukkit/conversations/StringPrompt.java
View File

@@ -1,7 +1,8 @@
package org.bukkit.conversations;
/**
* StringPrompt is the base class for any prompt that accepts an arbitrary string from the user.
* StringPrompt is the base class for any prompt that accepts an arbitrary
* string from the user.
*/
public abstract class StringPrompt implements Prompt{

18
paper-api/src/main/java/org/bukkit/conversations/ValidatingPrompt.java
View File

@@ -3,8 +3,9 @@ package org.bukkit.conversations;
import org.bukkit.ChatColor;
/**
* ValidatingPrompt is the base class for any prompt that requires validation. ValidatingPrompt will keep replaying
* the prompt text until the user enters a valid response.
* ValidatingPrompt is the base class for any prompt that requires validation.
* ValidatingPrompt will keep replaying the prompt text until the user enters
* a valid response.
*/
public abstract class ValidatingPrompt implements Prompt {
public ValidatingPrompt() {
@@ -12,8 +13,9 @@ public abstract class ValidatingPrompt implements Prompt {
}
/**
* Accepts and processes input from the user and validates it. If validation fails, this prompt is returned for
* re-execution, otherwise the next Prompt in the prompt graph is returned.
* Accepts and processes input from the user and validates it. If
* validation fails, this prompt is returned for re-execution, otherwise
* the next Prompt in the prompt graph is returned.
*
* @param context Context information about the conversation.
* @param input The input text from the user.
@@ -52,8 +54,9 @@ public abstract class ValidatingPrompt implements Prompt {
protected abstract boolean isInputValid(ConversationContext context, String input);
/**
* Override this method to accept and processes the validated input from the user. Using the input, the next Prompt
* in the prompt graph should be returned.
* Override this method to accept and processes the validated input from
* the user. Using the input, the next Prompt in the prompt graph should
* be returned.
*
* @param context Context information about the conversation.
* @param input The validated input text from the user.
@@ -62,7 +65,8 @@ public abstract class ValidatingPrompt implements Prompt {
protected abstract Prompt acceptValidatedInput(ConversationContext context, String input);
/**
* Optionally override this method to display an additional message if the user enters an invalid input.
* Optionally override this method to display an additional message if the
* user enters an invalid input.
*
* @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user.