Bukkit-API  1.7.9-R0.2
The inofficial Bukkit-API
ConversationFactory.java
1 package org.bukkit.conversations;
2 
3 import org.bukkit.entity.Player;
4 import org.bukkit.plugin.Plugin;
5 
6 import java.util.ArrayList;
7 import java.util.HashMap;
8 import java.util.List;
9 import java.util.Map;
10 
11 /**
12  * A ConversationFactory is responsible for creating a {@link Conversation}
13  * from a predefined template. A ConversationFactory is typically created when
14  * a plugin is instantiated and builds a Conversation each time a user
15  * initiates a conversation with the plugin. Each Conversation maintains its
16  * own state and calls back as needed into the plugin.
17  * <p>
18  * The ConversationFactory implements a fluid API, allowing parameters to be
19  * set as an extension to the constructor.
20  */
21 public class ConversationFactory {
22 
23  protected Plugin plugin;
24  protected boolean isModal;
25  protected boolean localEchoEnabled;
26  protected ConversationPrefix prefix;
27  protected Prompt firstPrompt;
28  protected Map<Object, Object> initialSessionData;
29  protected String playerOnlyMessage;
30  protected List<ConversationCanceller> cancellers;
31  protected List<ConversationAbandonedListener> abandonedListeners;
32 
33  /**
34  * Constructs a ConversationFactory.
35  *
36  * @param plugin The plugin that owns the factory.
37  */
38  public ConversationFactory(Plugin plugin)
39  {
40  this.plugin = plugin;
41  isModal = true;
42  localEchoEnabled = true;
43  prefix = new NullConversationPrefix();
44  firstPrompt = Prompt.END_OF_CONVERSATION;
45  initialSessionData = new HashMap<Object, Object>();
46  playerOnlyMessage = null;
47  cancellers = new ArrayList<ConversationCanceller>();
48  abandonedListeners = new ArrayList<ConversationAbandonedListener>();
49  }
50 
51  /**
52  * Sets the modality of all {@link Conversation}s created by this factory.
53  * If a conversation is modal, all messages directed to the player are
54  * suppressed for the duration of the conversation.
55  * <p>
56  * The default is True.
57  *
58  * @param modal The modality of all conversations to be created.
59  * @return This object.
60  */
61  public ConversationFactory withModality(boolean modal)
62  {
63  isModal = modal;
64  return this;
65  }
66 
67  /**
68  * Sets the local echo status for all {@link Conversation}s created by
69  * this factory. If local echo is enabled, any text submitted to a
70  * conversation gets echoed back into the submitter's chat window.
71  *
72  * @param localEchoEnabled The status of local echo.
73  * @return This object.
74  */
75  public ConversationFactory withLocalEcho(boolean localEchoEnabled) {
76  this.localEchoEnabled = localEchoEnabled;
77  return this;
78  }
79 
80  /**
81  * Sets the {@link ConversationPrefix} that prepends all output from all
82  * generated conversations.
83  * <p>
84  * The default is a {@link NullConversationPrefix};
85  *
86  * @param prefix The ConversationPrefix to use.
87  * @return This object.
88  */
90  this.prefix = prefix;
91  return this;
92  }
93 
94  /**
95  * Sets the number of inactive seconds to wait before automatically
96  * abandoning all generated conversations.
97  * <p>
98  * The default is 600 seconds (5 minutes).
99  *
100  * @param timeoutSeconds The number of seconds to wait.
101  * @return This object.
102  */
103  public ConversationFactory withTimeout(int timeoutSeconds) {
104  return withConversationCanceller(new InactivityConversationCanceller(plugin, timeoutSeconds));
105  }
106 
107  /**
108  * Sets the first prompt to use in all generated conversations.
109  * <p>
110  * The default is Prompt.END_OF_CONVERSATION.
111  *
112  * @param firstPrompt The first prompt.
113  * @return This object.
114  */
116  this.firstPrompt = firstPrompt;
117  return this;
118  }
119 
120  /**
121  * Sets any initial data with which to populate the conversation context
122  * sessionData map.
123  *
124  * @param initialSessionData The conversation context's initial
125  * sessionData.
126  * @return This object.
127  */
128  public ConversationFactory withInitialSessionData(Map<Object, Object> initialSessionData) {
129  this.initialSessionData = initialSessionData;
130  return this;
131  }
132 
133  /**
134  * Sets the player input that, when received, will immediately terminate
135  * the conversation.
136  *
137  * @param escapeSequence Input to terminate the conversation.
138  * @return This object.
139  */
140  public ConversationFactory withEscapeSequence(String escapeSequence) {
142  }
143 
144 
145  /**
146  * Adds a {@link ConversationCanceller} to constructed conversations.
147  *
148  * @param canceller The {@link ConversationCanceller} to add.
149  * @return This object.
150  */
152  cancellers.add(canceller);
153  return this;
154  }
155 
156  /**
157  * Prevents this factory from creating a conversation for non-player
158  * {@link Conversable} objects.
159  *
160  * @param playerOnlyMessage The message to return to a non-play in lieu of
161  * starting a conversation.
162  * @return This object.
163  */
164  public ConversationFactory thatExcludesNonPlayersWithMessage(String playerOnlyMessage) {
165  this.playerOnlyMessage = playerOnlyMessage;
166  return this;
167  }
168 
169  /**
170  * Adds a {@link ConversationAbandonedListener} to all conversations
171  * constructed by this factory.
172  *
173  * @param listener The listener to add.
174  * @return This object.
175  */
177  abandonedListeners.add(listener);
178  return this;
179  }
180 
181  /**
182  * Constructs a {@link Conversation} in accordance with the defaults set
183  * for this factory.
184  *
185  * @param forWhom The entity for whom the new conversation is mediating.
186  * @return A new conversation.
187  */
189  //Abort conversation construction if we aren't supposed to talk to non-players
190  if (playerOnlyMessage != null && !(forWhom instanceof Player)) {
191  return new Conversation(plugin, forWhom, new NotPlayerMessagePrompt());
192  }
193 
194  //Clone any initial session data
195  Map<Object, Object> copiedInitialSessionData = new HashMap<Object, Object>();
196  copiedInitialSessionData.putAll(initialSessionData);
197 
198  //Build and return a conversation
199  Conversation conversation = new Conversation(plugin, forWhom, firstPrompt, copiedInitialSessionData);
200  conversation.setModal(isModal);
201  conversation.setLocalEchoEnabled(localEchoEnabled);
202  conversation.setPrefix(prefix);
203 
204  //Clone the conversation cancellers
205  for (ConversationCanceller canceller : cancellers) {
206  conversation.addConversationCanceller(canceller.clone());
207  }
208 
209  //Add the ConversationAbandonedListeners
210  for (ConversationAbandonedListener listener : abandonedListeners) {
211  conversation.addConversationAbandonedListener(listener);
212  }
213 
214  return conversation;
215  }
216 
217  private class NotPlayerMessagePrompt extends MessagePrompt {
218 
219  public String getPromptText(ConversationContext context) {
220  return playerOnlyMessage;
221  }
222 
223  @Override
224  protected Prompt getNextPrompt(ConversationContext context) {
225  return Prompt.END_OF_CONVERSATION;
226  }
227  }
228 }
Conversation buildConversation(Conversable forWhom)
static final Prompt END_OF_CONVERSATION
Definition: Prompt.java:15
ConversationFactory withEscapeSequence(String escapeSequence)
ConversationFactory withConversationCanceller(ConversationCanceller canceller)
ConversationFactory withPrefix(ConversationPrefix prefix)
void setLocalEchoEnabled(boolean localEchoEnabled)
ConversationFactory addConversationAbandonedListener(ConversationAbandonedListener listener)
ConversationFactory thatExcludesNonPlayersWithMessage(String playerOnlyMessage)
synchronized void addConversationAbandonedListener(ConversationAbandonedListener listener)
ConversationFactory withTimeout(int timeoutSeconds)
ConversationFactory withModality(boolean modal)
ConversationFactory withLocalEcho(boolean localEchoEnabled)
ConversationFactory withFirstPrompt(Prompt firstPrompt)
ConversationFactory withInitialSessionData(Map< Object, Object > initialSessionData)