com.echomine.jabber.msg
Class DataXField

java.lang.Object
  extended by com.echomine.jabber.msg.DataXField

public class DataXField
extends java.lang.Object

Represents the field in the jabber:x:data schema. This field will contain the data to work properly with all the different types of fields as defined by JEP-0004. Note that this is the base class. Every field type extends from this class to provide the proper convenience methods to work with each individual type.

Since:
0.8a4
See Also:
DataXMessage, DataXOption

Field Summary
static java.lang.String TYPE_BOOLEAN
           
static java.lang.String TYPE_FIXED
           
static java.lang.String TYPE_HIDDEN
           
static java.lang.String TYPE_JID_MULTI
           
static java.lang.String TYPE_JID_SINGLE
           
static java.lang.String TYPE_LIST_MULTI
           
static java.lang.String TYPE_LIST_SINGLE
           
static java.lang.String TYPE_TEXT_MULTI
           
static java.lang.String TYPE_TEXT_PRIVATE
           
static java.lang.String TYPE_TEXT_SINGLE
           
 
Constructor Summary
DataXField()
          default constructor to use for parsing incoming messages
DataXField(java.lang.String fieldType)
          constructor that requires only a field type.
DataXField(java.lang.String fieldType, java.lang.String variableName, java.lang.String label)
          constructs a field with the parameters.
 
Method Summary
 void addJIDValue(JID jid)
          Adds a jid to the list of field values.
protected  void addOption(DataXOption option)
          An internal method that adds an option into the options list without doing any validation checks.
 void addTextValue(java.lang.String text)
          adds the text to the list of field values.
protected  void addValue(java.lang.String value)
          An internal method that simply adds the string value without doing any validation checks.
 Element encode()
          encodes the data in this field into an XML Element contained within the designated namespace
 boolean getBooleanValue()
          Retrieves the first value as a boolean value.
 java.lang.String getDescription()
           
 java.lang.String getFieldType()
          retrieves the field type (ie.
 JID getJIDValue()
          retrieves the first value as a JID object.
 java.util.List getJIDValues()
          retrieves all the values as a list of JID objects.
 java.lang.String getLabel()
           
 java.util.List getOptions()
          gets the options list.
 java.lang.String getStringValue()
          retrieves the first value as a String type.
 java.util.List getStringValues()
          retrieves the values sets in the field.
 java.lang.String getVariableName()
           
 boolean isRequired()
          whether this field is a required field for input.
 void parse(Element fieldElem)
          parses the data out of the XML DOM elements
 void setBooleanValue(boolean value)
          Adds a boolean value to the field.
 void setDescription(java.lang.String description)
          sets the description
 void setFieldType(java.lang.String fieldType)
          sets the field type for this field.
 void setJIDValue(JID jid)
          Adds a jid to the field.
 void setLabel(java.lang.String label)
          sets the label
 void setOptions(java.util.List ops)
          sets the list of options to display.
 void setRequired(boolean required)
          sets the required attribute for this field
 void setTextValue(java.lang.String text)
          sets the field value to the text specified.
protected  void setValues(java.util.List values)
          sets the values to a list of values you want added.
 void setVariableName(java.lang.String variableName)
          sets the variable name
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TYPE_BOOLEAN

public static final java.lang.String TYPE_BOOLEAN
See Also:
Constant Field Values

TYPE_FIXED

public static final java.lang.String TYPE_FIXED
See Also:
Constant Field Values

TYPE_HIDDEN

public static final java.lang.String TYPE_HIDDEN
See Also:
Constant Field Values

TYPE_JID_MULTI

public static final java.lang.String TYPE_JID_MULTI
See Also:
Constant Field Values

TYPE_JID_SINGLE

public static final java.lang.String TYPE_JID_SINGLE
See Also:
Constant Field Values

TYPE_LIST_MULTI

public static final java.lang.String TYPE_LIST_MULTI
See Also:
Constant Field Values

TYPE_LIST_SINGLE

public static final java.lang.String TYPE_LIST_SINGLE
See Also:
Constant Field Values

TYPE_TEXT_MULTI

public static final java.lang.String TYPE_TEXT_MULTI
See Also:
Constant Field Values

TYPE_TEXT_PRIVATE

public static final java.lang.String TYPE_TEXT_PRIVATE
See Also:
Constant Field Values

TYPE_TEXT_SINGLE

public static final java.lang.String TYPE_TEXT_SINGLE
See Also:
Constant Field Values
Constructor Detail

DataXField

public DataXField()
default constructor to use for parsing incoming messages


DataXField

public DataXField(java.lang.String fieldType)
constructor that requires only a field type.


DataXField

public DataXField(java.lang.String fieldType,
                  java.lang.String variableName,
                  java.lang.String label)
constructs a field with the parameters. Only field type is required. The rest are optional and can be null if not used

Parameters:
fieldType - the field type
variableName - the variable name, or null if not used
label - the optional label name, or null if not used
Method Detail

isRequired

public boolean isRequired()
whether this field is a required field for input. Defaults to false


setRequired

public void setRequired(boolean required)
sets the required attribute for this field


getDescription

public java.lang.String getDescription()
Returns:
the description of the field, or empty string if none exists

setDescription

public void setDescription(java.lang.String description)
sets the description


getFieldType

public java.lang.String getFieldType()
retrieves the field type (ie. list-multi, list-single, boolean, text, hidden, etc). The return value can be null if the field type did not exist. The client should assume that the type is text-single if the return type is null.


setFieldType

public void setFieldType(java.lang.String fieldType)
sets the field type for this field. If the field type specified is not supported or if the field type is null, then text-single will be used as the fallback field type.

Throws:
java.lang.IllegalArgumentException - if the field type is not supported

getLabel

public java.lang.String getLabel()
Returns:
the label associated with this field, or null if none exists

setLabel

public void setLabel(java.lang.String label)
sets the label


getVariableName

public java.lang.String getVariableName()
Returns:
the variable name associated with this field, or null if none exists

setVariableName

public void setVariableName(java.lang.String variableName)
sets the variable name


setBooleanValue

public void setBooleanValue(boolean value)
Adds a boolean value to the field. This is used only when you are using the boolean type field. If the field type is set to anything other than boolean type, then this method will throw an IllegalArgumentException. If there are already other values set in this field, then all the values are removed before setting the boolean value.

Parameters:
value - the boolean value to add
Throws:
java.lang.IllegalArgumentException - when the field type is not a boolean type.

setJIDValue

public void setJIDValue(JID jid)
Adds a jid to the field. This method can only be used when the field type is jid-single. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If there are already other values set in this field, then all the values are removed and will effectively be replaced by the JID that is passed in the parameter.

Parameters:
jid - the JID to add
Throws:
java.lang.IllegalArgumentException - when the field type is not a jid-multi type

addJIDValue

public void addJIDValue(JID jid)
Adds a jid to the list of field values. This method can only be used when the field type is jid-multi. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If you have a jid-single type, then you should use the setJIDValue() method instead.

Parameters:
jid - the JID to add
Throws:
java.lang.IllegalArgumentException - when the field type is not a jid-multi type

addTextValue

public void addTextValue(java.lang.String text)
adds the text to the list of field values. This method can only be used when the field type is text-multi or fixed. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If you have a text-single type, then you should use the setTextValue() method instead.

Parameters:
text - the text to add
Throws:
java.lang.IllegalArgumentException - when the field type is not a text-multi type

setTextValue

public void setTextValue(java.lang.String text)
sets the field value to the text specified. This is used only when you are using text-single, text-private, or hidden type field. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If there are already other values set in this field, all the values will be removed and replaced by the new value.

Parameters:
text - the text to store, cannot be null
Throws:
java.lang.IllegalArgumentException - when the field type is not a text-single type

getStringValue

public java.lang.String getStringValue()
retrieves the first value as a String type. This method can be called for any field type. The returned type will be string. If there are multiple values associated with this field, the first value will be returned.

Returns:
the first value as String, or null if there are no values to retrieves

getBooleanValue

public boolean getBooleanValue()
Retrieves the first value as a boolean value. The accepted value is "1" for true and any other string for false ("0", "false", "true" will all return false). This method will work for any field types, but it is normally used to retrieve boolean types.

Returns:
the first value of boolean, or false if there are no values to retrieve

getJIDValue

public JID getJIDValue()
                throws ParseException
retrieves the first value as a JID object. This method will work for any field types, but it is normally used to retrieve JID types. If there is a problem parsing the JID, an exception will be thrown.

Returns:
the JID object or null if there is no value to retrieve
Throws:
ParseException - if there is any problem parsing JID out of a string

getJIDValues

public java.util.List getJIDValues()
                            throws ParseException
retrieves all the values as a list of JID objects. This method will work for any field types, but it is normally used to retrieve JID types. If there is a problem parsing ANY JIDs, an exception will be thrown.

Returns:
a list of JID objects, in the order that was received, or an empty list if no values exist
Throws:
ParseException - if there is any problem parsing ANY JID out of the list of values

addValue

protected void addValue(java.lang.String value)
An internal method that simply adds the string value without doing any validation checks. It is a convenience method called by all the other methods to add values to the list.

Parameters:
value - the text value to add

addOption

protected void addOption(DataXOption option)
An internal method that adds an option into the options list without doing any validation checks.

Parameters:
option - the option to add

getStringValues

public java.util.List getStringValues()
retrieves the values sets in the field. If there are no data, then empty list is returned. The return list of values are not modifiable (ie. it's read-only).


setValues

protected void setValues(java.util.List values)
sets the values to a list of values you want added. This method bypasses validation checks and thus will not check the internal values. This method will clone the data from the list you passed in and store it inside its own list. Passing in null will clear the values list. It is very unlikely you will be using this method unless you are dealing with unknown field types. Otherwise, you will use one of the setXXX() and addXXX() methods to manipulate the list. Currently, this method is not public. If you think you need it, then request that it be made public.


getOptions

public java.util.List getOptions()
gets the options list. If the values are null, then an empty list will be returned. The return list of values are not modifiable (ie. it's read-only).


setOptions

public void setOptions(java.util.List ops)
sets the list of options to display. This method is only usable when field type is list-single or list-multi. If the type is not one of those specified, IllegalArgumentException will be thrown. If there are options available before calling this method, the old values will be replaced by the new ones. This method will clone the data from the list you pass in and store it inside its own list.

Parameters:
ops - a list of DataXOption objects
Throws:
java.lang.IllegalArgumentException - if the field type is not the designated type

parse

public void parse(Element fieldElem)
           throws ParseException
parses the data out of the XML DOM elements

Throws:
ParseException

encode

public Element encode()
               throws ParseException
encodes the data in this field into an XML Element contained within the designated namespace

Throws:
ParseException


Copyright © 2001-2005 Echomine. All Rights Reserved.