unsw.cse.mica.data
Class Mob

java.lang.Object
  extended by unsw.cse.mica.data.Mob
All Implemented Interfaces:
java.io.Serializable, MicaConstants

public class Mob
extends java.lang.Object
implements java.io.Serializable, MicaConstants

The basic unit of storage and communication in MICA.

Generally, MICA objects (Mobs) are considered to be immutable. Each Mob has several characteristics: firstly, a name that identifies the Mob, secondly, the mob's type, thirdaly, a persistence specifying the lifespan of the mob on the blackboard, and finally a list of slots. Each slot in turn has a list of values.

The current implementation of mobs supports slot lists that consist solely of Strings. Future versions are likely to include some kind of type checking measure, and allow more arbitrary elements in the slots.

See Also:
Serialized Form

Field Summary
 
Fields inherited from interface unsw.cse.mica.util.MicaConstants
DEFAULT_DB_PATH, DEFAULT_HOST, DEFAULT_MICA_HOME, DEFAULT_PERSISTENCE, DEFAULT_PERSISTENT, DEFAULT_PORT, DEFAULT_TYPE_PATH, INTERNAL_SLOT_NAMES, PARAM_DB_PATH, PARAM_DEBUG, PARAM_HOST, PARAM_MICA_HOME, PARAM_PERSISTENT, PARAM_PORT, PARAM_TYPE_PATH, PERSISTENCE_CONNECTED, PERSISTENCE_PERMANENT, PERSISTENCE_TRANSIENT, PERSISTENCES, RESULT_ERROR, RESULT_NOSUCHAGENT, RESULT_NOSUCHMOB, RESULT_SUCCESS, SLOT_CREATIONTIME, SLOT_CREATOR, SLOT_DELETER, SLOT_DELETIONTIME, SLOT_MODIFICATIONTIME, SLOT_MODIFIER, UNKNOWN_AGENT
 
Constructor Summary
Mob(Mob mob)
          Make a mob that is an exact deep copy of an existing mob.
Mob(java.lang.String type)
          Create a new Mob with the specified type, and with an empty name.
 
Method Summary
 void addEmptySlot(java.lang.String slotName)
          Add a slot with no values.
 void addSlot(java.lang.String slotName, java.util.List values)
          Create a new slot with the given values, or if the slot already exists, add the new values
 void addSlot(java.lang.String slotName, java.lang.String value)
          Create a new slot with a given value, or if the slot already exists, add a new value
 long getCreationTime()
          Get the mob's create time (as a long value in milliseconds)
 java.lang.String getCreator()
          Get the name of the agent that created this mob (that is, the agent that wrote it to the blackboard)
 java.lang.String getDeleter()
          Get the name of the agent that deleted this mob from the blackboard.
 long getDeletionTime()
          Get the mob's deletion time (as a long value in milliseconds) If a mob is transient it's deletion time may not be specified.
 java.lang.String getName()
          Get the name of this mob.
 java.lang.String getPersistence()
          Get the mob's persistence setting (either null or one of the strings defined in MicaConstants.PERSISTENCES)
 java.util.List getSlot(java.lang.String slotName)
          Gets the values for a particular slot.
 java.lang.String getSlot1(java.lang.String slotName)
          Get the first element of a given slot.
 double getSlot1AsDouble(java.lang.String slotName)
          Return the first element of the given slot as a double.
 int getSlot1AsInt(java.lang.String slotName)
          Return the first element of the given slot as an integer.
 java.lang.String getSlotN(java.lang.String slotName, int n)
          Get the nth element of a given slot, using a 0-based index.
 java.util.Set getSlots()
          Get the names of all slots that this Mob has.
 java.lang.String getType()
          Get the type of this Mob.
 boolean hasSlot(java.lang.String slotName)
          Tests to see if this particular Mob has a slot of the mentioned name.
 void removeSlot(java.lang.String slotName)
          Removes a particular slot from a mob
 void setName(java.lang.String name)
          Set the name of this mob.
 void setPersistence(java.lang.String persistence)
          Set the mob's persistence.
 void setSlot(java.lang.String slotName, java.util.List slotValues)
          Set a slot with a list of values.
 void setSlot(java.lang.String slotName, java.lang.String slotValue)
          Set a slot with a single values.
 void setType(java.lang.String type)
          Set the type of this mob.
 java.lang.String toString()
          Represent the Mob as a string.
 java.lang.String toXML()
          Convert the Mob to XML.
 java.lang.String toXML(java.lang.String initIndent, java.lang.String otherIndent)
          Convert the Mob to XML.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Mob

public Mob(java.lang.String type)
Create a new Mob with the specified type, and with an empty name.

Parameters:
type - The type of the Mob to be created, which must be non-null and non-empty
Throws:
java.lang.IllegalArgumentException - if type is either null or an empty string.

Mob

public Mob(Mob mob)
Make a mob that is an exact deep copy of an existing mob.

Parameters:
mob -
Method Detail

setType

public void setType(java.lang.String type)
Set the type of this mob.

Parameters:
type - the new type for the mob, which must not be null or have length zero
Throws:
java.lang.IllegalArgumentException - if type is null.

getType

public java.lang.String getType()
Get the type of this Mob.

Returns:
The type as a string.

setName

public void setName(java.lang.String name)
Set the name of this mob.

WARNING: Generally, only the blackboard should set the name of a Mob. Changing the name will generally break references between Mobs.

Parameters:
name - the new name for the mob, whichmust not be null
Throws:
java.lang.IllegalArgumentException - if name is null.

getName

public java.lang.String getName()
Get the name of this mob.

Returns:
The name of this mob.

setPersistence

public void setPersistence(java.lang.String persistence)
Set the mob's persistence.

Parameters:
persistence - the new persistence value for this mob. Must be equal to one of the persistence constants defined in MicaConstants
Throws:
java.lang.IllegalArgumentException - if the persistence is not a known value
See Also:
MicaConstants

getPersistence

public java.lang.String getPersistence()
Get the mob's persistence setting (either null or one of the strings defined in MicaConstants.PERSISTENCES)

Returns:
the persistence setting for this mob
See Also:
MicaConstants

getCreationTime

public long getCreationTime()
Get the mob's create time (as a long value in milliseconds)

Returns:
the creation time of this mob as a value in milliseconds

getCreator

public java.lang.String getCreator()
Get the name of the agent that created this mob (that is, the agent that wrote it to the blackboard)

Returns:
the name of the agent that created this mob

getDeletionTime

public long getDeletionTime()
Get the mob's deletion time (as a long value in milliseconds) If a mob is transient it's deletion time may not be specified.

Returns:
the deletion time of this mob in milliseconds

getDeleter

public java.lang.String getDeleter()
Get the name of the agent that deleted this mob from the blackboard. If the mob is transient, this value may be unspecified.

Returns:
the name of the agent that deleted this mob.

hasSlot

public boolean hasSlot(java.lang.String slotName)
Tests to see if this particular Mob has a slot of the mentioned name.

Parameters:
slotName - Name of the slot
Returns:
true if the mob has a slot called slotName

getSlot

public java.util.List getSlot(java.lang.String slotName)
Gets the values for a particular slot.

This returns a list of values associated with the slot.

Parameters:
slotName - Name of the slot you want to get the vector for.
Returns:
A list containing the slots. Returns null if there is no such slot; returns a list with no elements if there is such a slot, but no elements associated with it.

getSlot1AsInt

public int getSlot1AsInt(java.lang.String slotName)
Return the first element of the given slot as an integer. If the slot does not exist, or is empty the method returns 0.

Parameters:
slotName - the name of the slot for which the first element is required
Returns:
the first element of the given slot as an integer, or 0 if no such slot or element is available.

getSlot1AsDouble

public double getSlot1AsDouble(java.lang.String slotName)
Return the first element of the given slot as a double. If the slot does not exist, or is empty the method returns Double.NaN

Parameters:
slotName - the name of the slot for which the first element is required
Returns:
the first element of the given slot as an double, or 0 if no such slot or element is available.

getSlot1

public java.lang.String getSlot1(java.lang.String slotName)
Get the first element of a given slot.

This version only gets the first element of the slot. It is often useful if you know that the slot only has one value.

Parameters:
slotName - The name of the slot to retrieve the values for.
Returns:
The first element of the list of values set for this slot. If there is no such slot, or there are no elements for a slot, returns null.

getSlotN

public java.lang.String getSlotN(java.lang.String slotName,
                                 int n)
Get the nth element of a given slot, using a 0-based index.

Parameters:
slotName - The name of the slot from which to retrieve the value.
Returns:
The nth element of the list of values set for this slot. If there is no such slot, or there are less than n elements in the slot, returns null.

setSlot

public void setSlot(java.lang.String slotName,
                    java.util.List slotValues)
Set a slot with a list of values. Note that this method erases all previously stored values.

This sets the slot to have a list of values.

To add a value to an existing slot, used addSlot instead.

Parameters:
slotName - The slot to set
slotValues - The list of values for the slot.

setSlot

public void setSlot(java.lang.String slotName,
                    java.lang.String slotValue)
Set a slot with a single values. Note that this method erases all previously stored values.

This sets the slot to have a a single value.

To add a value to an existing slot, used addSlot instead.

Parameters:
slotName - The slot to set
slotValue - The new value for the slot.

removeSlot

public void removeSlot(java.lang.String slotName)
Removes a particular slot from a mob

Parameters:
slotName - the name of the slot to remove

getSlots

public java.util.Set getSlots()
Get the names of all slots that this Mob has. You can then use getSlot() and getSlot1() to get their values.

Returns:
The set of slot names for this mob, where each element is a String.

addSlot

public void addSlot(java.lang.String slotName,
                    java.lang.String value)
Create a new slot with a given value, or if the slot already exists, add a new value

Parameters:
slotName - the name of the slot
value - the value to add to the slot, which must be non-null
Throws:
java.lang.IllegalArgumentException - if value is null.

addSlot

public void addSlot(java.lang.String slotName,
                    java.util.List values)
Create a new slot with the given values, or if the slot already exists, add the new values

Parameters:
slotName - the name of the slot
values - the values to add to the slot, which must be non-null
Throws:
java.lang.IllegalArgumentException - if values is null or any element or values is null

addEmptySlot

public void addEmptySlot(java.lang.String slotName)
Add a slot with no values.

This function is convenient for sometimes creating a slot, so that the Mob has a slot, but has no values stored in it.

Parameters:
slotName - the new slot name

toString

public java.lang.String toString()
Represent the Mob as a string.

Overrides:
toString in class java.lang.Object
Returns:
A string description of the the Mob.

toXML

public java.lang.String toXML(java.lang.String initIndent,
                              java.lang.String otherIndent)
Convert the Mob to XML.

This is sometimes convenient, when you want to output a string in XML.

Parameters:
initIndent - The initial indentation of the first line of the XML. Every line will begin with this initial indentation.
otherIndent - The indent for subsequent lines. Each line will be indented by this string for each level of nesting of the XML structure.
Returns:
The Mob in String format.

toXML

public java.lang.String toXML()
Convert the Mob to XML.

This method simply calls toXML("","\t")

Returns:
The Mob in String format.