com.zion.jbuddy.bots
Class BotActionTask

java.lang.Object
  extended by com.zion.jbuddy.bots.BotActionTask

public abstract class BotActionTask
extends Object

An external task that can be called from bot actions.

To use a BotActionTask, an implementation class must be created that extends this class. The class can then be referenced using actions in a Bot Definition File. Alternatively, a BotAction can be created, of type JAVA, and having a path set to the implementation's fully-qualified class name.

The following example creates a BotActionTask that returns the current system time to the user:

public class TimeActionTask extends com.zion.jbuddy.bots.BotActionTask { public Object execute() { return "The current time is: " + new java.util.Date(); } }

An XML target can then be placed in the Bot Definition File:

<target command="time"> <action type="java" path="TimeActionTask"/> </target>

A BotActionTask can also be used to retrieve BotParameter values. The following example retrieves a STRING parameter's value (name) and an INT parameter's value (age):

public class PersonalInfoActionTask extends com.zion.jbuddy.bots.BotActionTask { public Object execute() { String name = getStringValue("name"); int age = getIntValue("age"); return "You said your name is " + name + " and you are " + age + " years old."; } }

See Also:
BotAction, BotParameter

Field Summary
protected  String command
          The command the user entered, or null.
protected  String commandValue
          The command value the user entered, or null.
protected  BotEngine engine
          The bot engine associated with the action.
protected  BotMessage message
          The message the user entered, or null.
protected  Map parameters
          The parameter values submitted to this action task, mapped by the associated parameter names (key = String, value = Object).
protected  BotUser user
          The user associated with the action.
 
Constructor Summary
protected BotActionTask()
           
 
Method Summary
abstract  Object execute()
          Executes this task.
 boolean getBooleanValue(String name)
          Returns a boolean parameter value.
 BotParameter getBotParameter(String name)
          Returns the specified parameter.
 Map getBotParameters()
          Returns the parameters submitted to this action task, mapped by their associated names (key = String, value = BotParameter).
 String getCommand()
          Returns the command the user entered, or null.
 String getCommandValue()
          Returns the command value the user entered, or null.
 Number getCurrencyValue(String name)
          Returns a currency parameter value.
 Date getDateTimeValue(String name)
          Returns a date-time parameter value.
 Date getDateValue(String name)
          Returns a date parameter value.
 double getDoubleValue(String name)
          Returns a double parameter value.
 BotEngine getEngine()
          Returns the bot engine associated with the action.
 int getIntValue(String name)
          Returns an int parameter value.
 long getLongValue(String name)
          Returns a long parameter value.
 BotMessage getMessage()
          Returns the message the user entered, or null.
 Number getNumberValue(String name)
          Returns a number parameter value.
 Object getParameter(String name)
          Returns the specified parameter value.
 Map getParameters()
          Returns the parameter values submitted to this action task, mapped by the associated parameter names (key = String, value = Object).
 Number getPercentValue(String name)
          Returns a percent parameter value.
 String getStringValue(String name)
          Returns a string parameter value.
 Date getTimeValue(String name)
          Returns a time parameter value.
 BotUser getUser()
          Returns the user associated with the action.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

engine

protected BotEngine engine
The bot engine associated with the action.


user

protected BotUser user
The user associated with the action.


message

protected BotMessage message
The message the user entered, or null.


command

protected String command
The command the user entered, or null.


commandValue

protected String commandValue
The command value the user entered, or null. The command value is everything entered after the command name.


parameters

protected Map parameters
The parameter values submitted to this action task, mapped by the associated parameter names (key = String, value = Object).

Constructor Detail

BotActionTask

protected BotActionTask()
Method Detail

getEngine

public BotEngine getEngine()
Returns the bot engine associated with the action.


getUser

public BotUser getUser()
Returns the user associated with the action.


getMessage

public BotMessage getMessage()
Returns the message the user entered, or null.


getCommand

public String getCommand()
Returns the command the user entered, or null.


getCommandValue

public String getCommandValue()
Returns the command value the user entered, or null. The command value is everything entered after the command name.


getParameter

public Object getParameter(String name)
Returns the specified parameter value.

Parameters:
name - the parameter's name
Returns:
the value, or null if the parameter does not exist
See Also:
getParameters()

getParameters

public Map getParameters()
Returns the parameter values submitted to this action task, mapped by the associated parameter names (key = String, value = Object).


getBotParameter

public BotParameter getBotParameter(String name)
Returns the specified parameter.

A BotParameter does not hold a user's entered values. It exists only as metadata to describe the type of value expected from the user, and/or how to process that value. To retrieve parameter values, use getParameter(java.lang.String), getParameters(), or one of the various getValue methods.

Parameters:
name - the parameter's name
Returns:
the parameter, or null if the parameter does not exist
See Also:
getBotParameters()

getBotParameters

public Map getBotParameters()
Returns the parameters submitted to this action task, mapped by their associated names (key = String, value = BotParameter).

A BotParameter does not hold a user's entered values. It exists only as metadata to describe the type of value expected from the user, and/or how to process that value. To retrieve parameter values, use getParameter(java.lang.String), getParameters(), or one of the various getValue methods.


execute

public abstract Object execute()
                        throws Exception
Executes this task. This is called by the BotEngine, and must be overridden to do something useful.

The returned value is processed according to its type and the action's result type.

A task can take any amount of time to complete, depending on the associated action's timeout value. If a timeout is specified, and expires before the task has finished execution, its calling Thread will be interrupted. Long-running tasks can query isInterrupted on the current thread, or catch InterruptedException from a waiting object, to handle this.

Returns:
the value to process and/or send to the user
Throws:
Exception

getStringValue

public String getStringValue(String name)
                      throws IllegalArgumentException
Returns a string parameter value.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist
See Also:
BotParameterType.STRING

getBooleanValue

public boolean getBooleanValue(String name)
                        throws IllegalArgumentException
Returns a boolean parameter value.

If the specified parameter value is a Boolean, it is converted directly to a boolean and returned. Otherwise, the String value is parsed into a boolean (as described in BotParameterType.BOOLEAN) and returned.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.BOOLEAN

getIntValue

public int getIntValue(String name)
                throws IllegalArgumentException
Returns an int parameter value.

If the specified parameter value is a Number, it is casted to an int and returned. Otherwise, the String value is parsed into a Number, then processed as above.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.INT, getNumberValue(java.lang.String)

getLongValue

public long getLongValue(String name)
                  throws IllegalArgumentException
Returns a long parameter value.

If the specified parameter value is a Number, it is casted to a long and returned. Otherwise, the String value is parsed into a Number, then processed as above.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.LONG, getNumberValue(java.lang.String)

getDoubleValue

public double getDoubleValue(String name)
                      throws IllegalArgumentException
Returns a double parameter value.

If the specified parameter value is a Number, it is casted to a double and returned. Otherwise, the String value is parsed into a Number, then processed as above.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.DOUBLE, getNumberValue(java.lang.String)

getNumberValue

public Number getNumberValue(String name)
                      throws IllegalArgumentException
Returns a number parameter value.

If the specified parameter value is a Number, it is returned directly. Otherwise, the String value is parsed into a Number and returned.

Simple number values (such 1 and 3.14) are accepted, as well as locale-specific complex number formats (such as 1,234,567). Related BotParameter settings (such as locale and numberFormat) are used to parse the value, if available.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.NUMBER, BotParameter

getCurrencyValue

public Number getCurrencyValue(String name)
Returns a currency parameter value.

If the specified parameter value is a Number, and the parameter type is currency, the value is returned directly. Otherwise, the String value is parsed into a Number and returned.

Locale-specific currency values (such as $1.50 and $1,000,000) are accepted. Related BotParameter settings (such as locale and numberFormat) are used to parse the value, if available.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.CURRENCY, BotParameter

getPercentValue

public Number getPercentValue(String name)
Returns a percent parameter value.

If the specified parameter value is a Number, and the parameter type is percent, the value is returned directly. Otherwise, the String value is parsed into a Number and returned.

Locale-specific percentage values (such as 100% and 5.25%) are accepted. Related BotParameter settings (such as locale and numberFormat) are used to parse the value, if available.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.PERCENT, BotParameter

getDateValue

public Date getDateValue(String name)
Returns a date parameter value.

If the specified parameter value is a Date, it is returned directly. Otherwise, the String value is parsed into a Date and returned.

Locale-specific date values (such as 12/22/92) are accepted. Related BotParameter properties (such as locale and dateFormat) are used to parse the value, if available.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.DATE, BotDateTimeStyle, BotParameter

getTimeValue

public Date getTimeValue(String name)
Returns a time parameter value.

If the specified parameter value is a Date, it is returned directly. Otherwise, the String value is parsed into a Date and returned.

Locale-specific time values (such as 2:30 pm) are accepted. Related BotParameter properties (such as locale and dateFormat) are used to parse the value, if available.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.TIME, BotDateTimeStyle, BotParameter

getDateTimeValue

public Date getDateTimeValue(String name)
Returns a date-time parameter value.

If the specified parameter value is a Date, it is returned directly. Otherwise, the String value is parsed into a Date and returned.

Locale-specific date/time values (such as 12/22/92 2:30 pm) are accepted. Related BotParameter properties (such as locale and dateFormat) are used to parse the value, if available.

Parameters:
name - the parameter's name
Returns:
the value
Throws:
IllegalArgumentException - if the specified parameter does not exist, or has an invalid value
See Also:
BotParameterType.DATE_TIME, BotDateTimeStyle, BotParameter


JBuddy is a trademark of Zion Software, LLC in the US and other countries.
Copyright 2000-2008 Zion Software, LLC All Rights Reserved.