wyvern.kernel.properties
Class PList

java.lang.Object
  wyvern.kernel.properties.PList

All Implemented Interfaces:

PropertyList

Direct Known Subclasses:

AbstractGameMap, ArchetypeImpl, EventImpl, Lock, MapLoader, MapObject, ProximityProperty, SimpleHandler

public class PList

extends java.lang.Object

implements PropertyList

This class implements a Property list. Properties are requested by by name, and the value can be any arbitrary Java object.

The accessor methods of this class will first check the list for the specified property. If it isn't found, the method will look for a parent link, recursively, until it finds a top-level archetype with no parent.

If you call removeProperty() on an object, you normally don't want it to inherit the parent's value for that property anymore. For instance, if the parent is an archetype with the "cursed" property, then after you call removeProperty("cursed") on your object, you expect hasProperty("cursed") to return false. So the system keeps an internal value for the property on your object that indicates: "this property is null - don't inherit it from the parent." You can override this behavior by calling inheritProperty(name), in which case, the object will get the inherited value from then on.

Every object has a transient property list. Transient props are not written out to disk when you save the object. You can temporarily tell an object not to inherit the parent's value by calling transientlyRemoveProperty(name), and it will put a placeholder in the transient list, so that for the rest of that session, the getProperty(), hasProperty(), getIntProperty(), etc. will return null, zero, or false as appropriate, even if the parent list or local list has the property.

If you call removeTransientProperty(name), then it just removes the name from the transient property list. This means that the object will use its local (persistent) value, or if there isn't one, the inherited value.

Property names are case-sensitive. Following the standard naming conventions (all lower-case, with hyphens) will help reduce errors related to misspelling the property name.

Version:

1.0, Aug 26, 1997

Author:

Steve Yegge

Field Summary

protected boolean

readOnly_ Set this for system archetypes, when you want them to throw an exception if you try to set a property on them.

Fields inherited from interface wyvern.lib.PropertyList

PROPERTY_PACKAGE

Constructor Summary

PList()
Constructs a new PList

Method Summary

void	addProperty(java.lang.String name) Adds a persistent boolean property to the list.
void	addTransientProperty(java.lang.String name) Adds a boolean property to the transient property list.
double	adjustDoubleProperty(java.lang.String name, double adjust) Adds an adjustment value (which can be negative) to the persistent value of a double property.
int	adjustIntProperty(java.lang.String name, int adjust) Adds an adjustment value (which can be negative) to the persistent value of an int property.
long	adjustLongProperty(java.lang.String name, long adjust) Adds an adjustment value (which can be negative) to the persistent value of a long property.
double	adjustTransientDoubleProperty(java.lang.String name, double adjust) Adjusts a double property, where the adjustment is transient (meaning temporary - not saved to the XML file if the object owning this plist is saved out).
int	adjustTransientIntProperty(java.lang.String name, int adjust) Adjusts an int property, where the adjustment is transient (meaning temporary - not saved to the XML file if the object owning this plist is saved out).
long	adjustTransientLongProperty(java.lang.String name, long adjust) Adjusts a long property, where the adjustment is transient (meaning temporary - not saved to the XML file if the object owning this plist is saved out).
int	countLocalProperties() Returns the number of non-inherited properties we have in our transient and persistent lists.
java.lang.String	debugProperties() Prints out the property list, showing which ones are inherited and which ones are local.
void	dismantlePropertyList() Dismantles the property list, in anticipation of it going away forever.
double	getDoubleProperty(java.lang.String name) Returns the value of a double (bigint) property.
java.lang.Object	getInheritedProperty(java.lang.String name) Returns the inherited value of the specified property, if any.
static java.lang.Integer	getInteger(int value) Returns a new Integer object for the specified int value.
int	getIntProperty(java.lang.String name) Returns the value of an int property.
java.util.Set	getLocalProperties() Returns a Set of the names of all the transient and non-inherited persistent properties on this object.
java.lang.Object	getLocalProperty(java.lang.String name) Gets the local value of a property.
long	getLongProperty(java.lang.String name) Returns the value of a long (bigint) property.
PropertyList	getParent() Returns the parent list for this list, if any.
double	getPersistentDoubleProperty(java.lang.String name) Gets the current persistent value of a double property.
int	getPersistentIntProperty(java.lang.String name) Gets the current persistent value of an int property.
java.util.Set	getPersistentLocalProperties() Returns a Set of the names of all the non-inherited persistent properties on this object.
long	getPersistentLongProperty(java.lang.String name) Gets the current persistent value of a long property.
java.lang.Object	getPersistentProperty(java.lang.String name) Returns the persistent (i.e. normal) value for the property, if found.
static java.lang.String	getProfilingInfo() Returns profiling info.
java.util.Set	getProperties() Returns the names of all the list's local properties.
java.util.Set	getProperties(boolean inherit) Returns all the list's properties, optionally including inherited ones.
java.util.Set	getPropertiesIncludingTransients() Returns the names of all the lists's local properties, including names in the transient list.
java.util.Set	getPropertiesIncludingTransients(boolean inherit) Returns the names of all the lists's local properties, including names in the transient list, and optionally including inherited properties as well.
java.lang.Object	getProperty(java.lang.String name) Returns the value of the requested Property.
java.util.Set	getSerializableProperties() Returns the names of all the lists's local properties, including any properties that have NullValue as values - meaning someone called removeProperty() on them, and the null overrides an inherited version of the property.
java.lang.Object	getSerializableProperty(java.lang.String name) Returns a local property value, but unlike its counterpart getPersistentProperty(), if the value is a NullValue placeholder for when someone called removeProperty() to override an inherited value, this method returns the NullValue.
java.lang.String	getStringProperty(java.lang.String name) Returns getProperty(name) with the return value cast as a String.
double	getTransientDoubleProperty(java.lang.String name) Gets the current transient value of a double property.
int	getTransientIntProperty(java.lang.String name) Gets the current transient value of an int property.
long	getTransientLongProperty(java.lang.String name) Gets the current transient value of a long property.
java.util.Set	getTransientProperties() Returns ONLY the transient properties on this object.
java.lang.Object	getTransientProperty(java.lang.String name) Returns the transient value for the property, if anyone has set one.
boolean	hasLocalProperty(java.lang.String name) Checks whether a given property is local to an object.
boolean	hasPersistentProperty(java.lang.String name) Checks whether the list contains the given property in the persistent property list - ignores any transient setting.
boolean	hasProperty(java.lang.String name) Checks whether the list contains the given property.
boolean	hasTransientProperty(java.lang.String name) Returns true if the transient list contains the specified property.
java.lang.Object	inheritProperty(java.lang.String name) This is like removeProperty(), except that it just removes the property name from the local persistent property list.
boolean	isReadOnly() Returns true if this property list has been marked read-only.
boolean	isRemoved(java.lang.String name) A very special-purpose method, mostly for use by the Map Editor, that lets you determine if a property is explicitly suppressing its inherited value.
boolean	isTransientlyRemoved(java.lang.String name) Same as isRemoved(), but checks the transient list.
java.lang.String	printLocalProperties() Prints only local, persistent properties: the list returned from getProperties(false).
java.lang.String	printProperties() Prints out a nicely formatted list of properties on this object.
java.lang.String	printProperties(boolean inherit) Prints out a nicely formatted list of properties on this object.
java.lang.String	printTransientProperties() Prints only local, transient properties from the object.
java.lang.Object	removeProperty(java.lang.String name) Removes a persistent property from the list.
java.lang.Object	removeTransientProperty(java.lang.String name) Removes a property from the transient list.
void	setDoubleProperty(java.lang.String name, double value) Sets the persistent value of a double property.
void	setIntProperty(java.lang.String name, int value) Sets the persistent value of an int property.
void	setLongProperty(java.lang.String name, long value) Sets the persistent value of a long property.
void	setParent(PropertyList parent) Sets the parent list for this list.
void	setProperty(java.lang.String name, java.lang.Object value) Sets a persistent property on an object.
void	setReadOnly(boolean readOnly) Marks the property list as read-only, so you can't set, remove, or change properties in the list.
void	setTransientDoubleProperty(java.lang.String name, double value) Sets a transient double value explicitly.
void	setTransientIntProperty(java.lang.String name, int value) Sets a transient int value explicitly.
void	setTransientLongProperty(java.lang.String name, long value) Sets a transient long value explicitly.
void	setTransientProperty(java.lang.String name, java.lang.Object value) Sets a transient property.
java.lang.String	toString() Returns a string representation of this PropertyList.
java.lang.String	toString(boolean inherit) Returns a string represenation of this property list.
java.lang.Object	transientlyRemoveProperty(java.lang.String name) Tells the object to temporarily act as if it doesn't have a local/persistent or inherited value for this property name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

readOnly_

protected boolean readOnly_

Set this for system archetypes, when you want them to throw an exception if you try to set a property on them.

Constructor Detail

PList

public PList()

Constructs a new PList

Method Detail

getProperty

public final java.lang.Object getProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the value of the requested Property. Clients must cast the returned value to the property's return type. Example usage:

 Integer glows = (Integer) myObj.getProperty( "LightSource" );
 

Specified by:

getProperty in interface PropertyList

Parameters:

name - the name of the property

Returns:

if there's a transient value of the property, returns the transient value (same as calling getTransientProperty()). If there's no transient value, returns the local persistent value of the property. If there's no local value, searches up the plist inheritance chain and returns the inherited value if any. If no value is found, returns null.

getTransientProperty

public final java.lang.Object getTransientProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the transient value for the property, if anyone has set one. getProperty() will return the transient value if one has been set; this method is a way to get the transient value explicitly.

Specified by:

getTransientProperty in interface PropertyList

Parameters:

name - the name of the property

Returns:

the transient value, or null if not found. (There could be a persistent value, but this won't be returned.)

getPersistentProperty

public final java.lang.Object getPersistentProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the persistent (i.e. normal) value for the property, if found. getProperty() will return the persistent value if nobody has set a transient value; this method is a way to get the persisent value explicitly.

Specified by:

getPersistentProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the local non-transient value for the property, if any, or the inherited value if there's no local value, or null if there's no inherited value.

setProperty

public final void setProperty(java.lang.String name,
                              java.lang.Object value)

Description copied from interface: PropertyList

Sets a persistent property on an object. If the property already exists in the list, it replaces its value with the new value.

Specified by:

setProperty in interface PropertyList

Parameters:

name - the new property to set. If the property already existed, replaces the old value with the new one. Puts the property in the persistent list; has no effect on any transient value for the property.

value - the new value for the property. If null, the property will be removed from the list. To add a "tag" property with no value, use the addProperty() method.

setTransientProperty

public final void setTransientProperty(java.lang.String name,
                                       java.lang.Object value)

Description copied from interface: PropertyList

Sets a transient property. The transient vlaue will override the persistent value, unless it's a numeric type (Integer, Long). If the value is an Integer or Long, getIntProperty() or getLongProperty() on that property will return the sum of the transient and persistent values. A transient property can be removed using removeTransientProperty().

Specified by:

setTransientProperty in interface PropertyList

Parameters:

name - the property name

value - the property value. If null, calls removeTransientProperty(name).

addProperty

public final void addProperty(java.lang.String name)

Description copied from interface: PropertyList

Adds a persistent boolean property to the list. The value is set to true. This method is a convenient equivalent to calling setProperty(Boolean.TRUE). To add a boolean property with a value of false, use setProperty(Boolean.FALSE).

Specified by:

addProperty in interface PropertyList

addTransientProperty

public final void addTransientProperty(java.lang.String name)

Description copied from interface: PropertyList

Adds a boolean property to the transient property list. The value is set to true. To add a boolean value of false, use setTransientProperty(new Boolean(false)).

Specified by:

addTransientProperty in interface PropertyList

Parameters:

name - the name of the property to add

hasProperty

public final boolean hasProperty(java.lang.String name)

Description copied from interface: PropertyList

Checks whether the list contains the given property.

Specified by:

hasProperty in interface PropertyList

Parameters:

name - the property to check for

Returns:

if the object has the property AND the property's value is not a Boolean, returns true. If the value is a boolean, this method returns the Boolean value. This is to make it easier to handle properties that "tag" an object, such as the "identified" property. Looks in the transient property list for a value first.

hasPersistentProperty

public final boolean hasPersistentProperty(java.lang.String name)

Description copied from interface: PropertyList

Checks whether the list contains the given property in the persistent property list - ignores any transient setting. If the value is a Boolean, returns the boolean value, else returns true if the property exists and false if it doesn't. Checks up inheritance chain if not in local list.

Specified by:

hasPersistentProperty in interface PropertyList

Parameters:

name - the property to look for in the persistent list

Returns:

true if the property exists in the non-transient list (unless the value is a Boolean, in which case it returns the boolean value of the Boolean object), or if it's inherited from the parent list.

hasTransientProperty

public final boolean hasTransientProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns true if the transient list contains the specified property.

Specified by:

hasTransientProperty in interface PropertyList

Parameters:

name - the name of the property to check for in the transient list - ignores any persistent setting.

Returns:

true if the object has the property in its transient property list AND the property's value is not a Boolean value. If the value is a Boolean, returns the Boolean's boolean value.

hasLocalProperty

public final boolean hasLocalProperty(java.lang.String name)

Description copied from interface: PropertyList

Checks whether a given property is local to an object. You almost never care - this is mostly for the benefit of the Map Editor, which sometimes needs to know.

Specified by:

hasLocalProperty in interface PropertyList

Parameters:

name - the property to check for

Returns:

true if property exists in either the local persistent property list (not inherited), or it exists in the transient property list.

getLocalProperty

public final java.lang.Object getLocalProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the local value of a property. If there isn't one, it will return null, even if there's an inherited property of the same name. Only looks in persistent list. You probably won't use this very often, if ever.

Specified by:

getLocalProperty in interface PropertyList

Parameters:

name - the name of the property

Returns:

the value (if any) in the local, persistent property list

getInheritedProperty

public final java.lang.Object getInheritedProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the inherited value of the specified property, if any.

Specified by:

getInheritedProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the value we inherit for this property, if we have a parent plist, and if somewhere up the chain, one of our ancestors has a property with this name. Returns null if there is no inherited value.

isRemoved

public final boolean isRemoved(java.lang.String name)

Description copied from interface: PropertyList

A very special-purpose method, mostly for use by the Map Editor, that lets you determine if a property is explicitly suppressing its inherited value. This happens when you call removeProperty(), and we determine that there is an inherited value. The list will add a placeholder of type wyvern.kernel.properties.NullValue. Normally the system returns null if it finds a NullValue in the list. However, when we save the object as xml, we need to save the null value in the xml file. So this method lets you figure out if there's an explicit NullValue in the list.

Specified by:

isRemoved in interface PropertyList

Parameters:

name - the property name to check

Returns:

true if the property's value is a NullValue

isTransientlyRemoved

public final boolean isTransientlyRemoved(java.lang.String name)

Description copied from interface: PropertyList

Same as isRemoved(), but checks the transient list. The only way this method can return true is if someone called transientlyRemoveProperty() on the property during this game server session.

Specified by:

isTransientlyRemoved in interface PropertyList

Parameters:

name - the property name to check

Returns:

true if the property's value is a NullValue

countLocalProperties

public final int countLocalProperties()

Description copied from interface: PropertyList

Returns the number of non-inherited properties we have in our transient and persistent lists.

Specified by:

countLocalProperties in interface PropertyList

Returns:

total count of local prop names. If the same name exists in both the transient and persistent sets, it's counted twice.

getLocalProperties

public final java.util.Set getLocalProperties()

Description copied from interface: PropertyList

Returns a Set of the names of all the transient and non-inherited persistent properties on this object.

Specified by:

getLocalProperties in interface PropertyList

Returns:

null if there are no local properties on this object, or a Set containing the names of all persistent and transient props. Names existing in both sets are only included once.

getPersistentLocalProperties

public final java.util.Set getPersistentLocalProperties()

Description copied from interface: PropertyList

Returns a Set of the names of all the non-inherited persistent properties on this object.

Specified by:

getPersistentLocalProperties in interface PropertyList

Returns:

null if there are no local, persistent properties on this object, or a Set containing the names of all persistent props.

getStringProperty

public final java.lang.String getStringProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns getProperty(name) with the return value cast as a String. Basically just a syntactic convenience.

Specified by:

getStringProperty in interface PropertyList

Parameters:

name - the property name to look up

Returns:

the value as a String, or null if it wasn't found

getIntProperty

public final int getIntProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the value of an int property. This is equivalent to calling getProperty() and getting the intValue of the Integer that's returned (or zero if the value is null).

Specified by:

getIntProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the int value of the property - the sum of the transient int value (if any) and the persistent int value (if any). If you don't want them added together, call getPersistentProperty() and getTransientProperty() on the name, and use the two Integer results however you like.

setIntProperty

public final void setIntProperty(java.lang.String name,
                                 int value)

Description copied from interface: PropertyList

Sets the persistent value of an int property. This can also be done by calling setProperty() and passing an Integer value. This method has no effect on any transient int value that may have been set.

Specified by:

setIntProperty in interface PropertyList

Parameters:

name - the property name

value - the new int value for the property

adjustIntProperty

public final int adjustIntProperty(java.lang.String name,
                                   int adjust)

Description copied from interface: PropertyList

Adds an adjustment value (which can be negative) to the persistent value of an int property. This is useful for changing the value without having to retrieve the value first (thus avoiding an extra hash lookup).

If the property doesn't exist, it's created first with a value of zero before adjusting it. Has no effect on any transient int value for the property, if one has been set. If the property exists on an ancestor archetype, a copy will be made locally on the object before doing the adjustment.

Specified by:

adjustIntProperty in interface PropertyList

Parameters:

name - the property name

adjust - the int value to add to the property.

Returns:

the new, adjusted value

getTransientIntProperty

public final int getTransientIntProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the current transient value of an int property.

Specified by:

getTransientIntProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the int value stored in the transient part of the plist

setTransientIntProperty

public final void setTransientIntProperty(java.lang.String name,
                                          int value)

Description copied from interface: PropertyList

Sets a transient int value explicitly. Normally you'll want to use adjustTransientIntProperty() instead, since other code may already have set a transient value.

Specified by:

setTransientIntProperty in interface PropertyList

Parameters:

name - the property name

value - the new transient int value for the property

adjustTransientIntProperty

public final int adjustTransientIntProperty(java.lang.String name,
                                            int adjust)

Description copied from interface: PropertyList

Adjusts an int property, where the adjustment is transient (meaning temporary - not saved to the XML file if the object owning this plist is saved out). Useful for setting temporary magical bonuses.

Specified by:

adjustTransientIntProperty in interface PropertyList

Parameters:

name - the property name

adjust - the int value to add to the property.

Returns:

the new, adjusted value

getPersistentIntProperty

public final int getPersistentIntProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the current persistent value of an int property.

Specified by:

getPersistentIntProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the int value stored in the persistent part of the plist. Use setIntProperty to set the persistent value.

getLongProperty

public final long getLongProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the value of a long (bigint) property. This is equivalent to calling getProperty() and getting the long value of the Long that's returned (or zero if the value is null).

Specified by:

getLongProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the long value of the property - the sum of the transient long value (if any) and the persistent long value (if any). If you don't want them added together, call getPersistentProperty() and getTransientProperty() on the name, and use the two Long results however you like.

setLongProperty

public final void setLongProperty(java.lang.String name,
                                  long value)

Description copied from interface: PropertyList

Sets the persistent value of a long property. This can also be done by calling setProperty() and passing a long value. This method has no effect on any transient long value that may have been set.

Specified by:

setLongProperty in interface PropertyList

Parameters:

name - the property name

value - the new long value for the property

adjustLongProperty

public final long adjustLongProperty(java.lang.String name,
                                     long adjust)

Description copied from interface: PropertyList

Adds an adjustment value (which can be negative) to the persistent value of a long property. This is useful for changing the value without having to retrieve the value first (thus avoiding an extra hash lookup).

If the property doesn't exist, it's created first with a value of zero before adjusting it. Has no effect on any transient long value for the property, if one has been set. If the property exists on an ancestor archetype, a copy will be made locally on the object before doing the adjustment.

Specified by:

adjustLongProperty in interface PropertyList

Parameters:

name - the property name

adjust - the long value to add to the property.

Returns:

the new, adjusted value

getTransientLongProperty

public final long getTransientLongProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the current transient value of a long property.

Specified by:

getTransientLongProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the long value stored in the transient part of the plist

setTransientLongProperty

public final void setTransientLongProperty(java.lang.String name,
                                           long value)

Description copied from interface: PropertyList

Sets a transient long value explicitly. Normally you'll want to use adjustTransientLongProperty() instead, since other code may already have set a transient value.

Specified by:

setTransientLongProperty in interface PropertyList

Parameters:

name - the property name

value - the new transient long value for the property

adjustTransientLongProperty

public final long adjustTransientLongProperty(java.lang.String name,
                                              long adjust)

Description copied from interface: PropertyList

Adjusts a long property, where the adjustment is transient (meaning temporary - not saved to the XML file if the object owning this plist is saved out). Useful for setting temporary magical bonuses.

Specified by:

adjustTransientLongProperty in interface PropertyList

Parameters:

name - the property name

adjust - the long value to add to the property.

getPersistentLongProperty

public final long getPersistentLongProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the current persistent value of a long property.

Specified by:

getPersistentLongProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the long value stored in the persistent part of the plist. Use setLongProperty to set the persistent value.

getDoubleProperty

public final double getDoubleProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns the value of a double (bigint) property. This is equivalent to calling getProperty() and getting the double value of the Double that's returned (or zero if the value is null).

Specified by:

getDoubleProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the double value of the property - the sum of the transient double value (if any) and the persistent double value (if any).

If you don't want them added together, call getPersistentProperty() and getTransientProperty() on the name, and use the two Double results however you like.

setDoubleProperty

public final void setDoubleProperty(java.lang.String name,
                                    double value)

Description copied from interface: PropertyList

Sets the persistent value of a double property. This can also be done by calling setProperty() and passing a double value. This method has no effect on any transient double value that may have been set.

Specified by:

setDoubleProperty in interface PropertyList

Parameters:

name - the property name

value - the new double value for the property

adjustDoubleProperty

public final double adjustDoubleProperty(java.lang.String name,
                                         double adjust)

Description copied from interface: PropertyList

Adds an adjustment value (which can be negative) to the persistent value of a double property. This is useful for changing the value without having to retrieve the value first (thus avoiding an extra hash lookup).

If the property doesn't exist, it's created first with a value of zero before adjusting it. Has no effect on any transient double value for the property, if one has been set. If the property exists on an ancestor archetype, a copy will be made locally on the object before doing the adjustment.

Specified by:

adjustDoubleProperty in interface PropertyList

Parameters:

name - the property name

adjust - the double value to add to the property.

Returns:

the new, adjusted value

getTransientDoubleProperty

public final double getTransientDoubleProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the current transient value of a double property.

Specified by:

getTransientDoubleProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the double value stored in the transient part of the plist

setTransientDoubleProperty

public final void setTransientDoubleProperty(java.lang.String name,
                                             double value)

Description copied from interface: PropertyList

Sets a transient double value explicitly. Normally you'll want to use adjustTransientDoubleProperty() instead, since other code may already have set a transient value.

Specified by:

setTransientDoubleProperty in interface PropertyList

Parameters:

name - the property name

value - the new transient double value for the property

adjustTransientDoubleProperty

public final double adjustTransientDoubleProperty(java.lang.String name,
                                                  double adjust)

Description copied from interface: PropertyList

Adjusts a double property, where the adjustment is transient (meaning temporary - not saved to the XML file if the object owning this plist is saved out). Useful for setting temporary magical bonuses.

Specified by:

adjustTransientDoubleProperty in interface PropertyList

Parameters:

name - the property name

adjust - the double value to add to the property.

getPersistentDoubleProperty

public final double getPersistentDoubleProperty(java.lang.String name)

Description copied from interface: PropertyList

Gets the current persistent value of a double property.

Specified by:

getPersistentDoubleProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the double value stored in the persistent part of the plist. Use setDoubleProperty to set the persistent value.

removeProperty

public final java.lang.Object removeProperty(java.lang.String name)

Description copied from interface: PropertyList

Removes a persistent property from the list.

Specified by:

removeProperty in interface PropertyList

Parameters:

name - the property to remove.

removeProperty only removes persistent properties - use removeTransientProperty to remove transient properties.

Returns:

previous value stored in this property, or null if there was no mapping for the passed property name.

removeTransientProperty

public final java.lang.Object removeTransientProperty(java.lang.String name)

Description copied from interface: PropertyList

Removes a property from the transient list. Only the persistent value (if any) will remain. The semantics are a bit different from removeProperty(): when you call removeProperty(), it will put a placeholder in the object's persistent list saying that we don't want to inherit a value for the property. When you call removeTransientProperty(), it just removes the property from the transient list, and subsequent calls to getProperty() will return the persistent or inherited value, if any.

Specified by:

removeTransientProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the value that was stored in the transient list under that name, if any; else returns null.

transientlyRemoveProperty

public final java.lang.Object transientlyRemoveProperty(java.lang.String name)

Description copied from interface: PropertyList

Tells the object to temporarily act as if it doesn't have a local/persistent or inherited value for this property name. For instance, if a monster inherits an "ai" property, and you want it to act as if it has no "ai" - i.e. hasProperty("ai") returns value, and getProperty("ai") returns null - then you can call this method to force that behavior. It lasts until the server reboots, and if the object is saved to disk, it will not know that you called this method: it will save the local/persistent value, if any.

You can do this permanently (tell the object that it should never inherit the parent value) by calling removeProperty().

Specified by:

transientlyRemoveProperty in interface PropertyList

Parameters:

name - the property name to hide, transiently

Returns:

the previous value in the transient list under this name, if any. Returns null if there was no transient list, or the previous value in the transient list was null, or if the previous value was a placeholder set by a previous call to transientlyRemoveProperty() on this list.

If the old value implemented AddRemoveNotify, its notifyRemove() method will be called before returning.

inheritProperty

public final java.lang.Object inheritProperty(java.lang.String name)

Description copied from interface: PropertyList

This is like removeProperty(), except that it just removes the property name from the local persistent property list. This has the effect of causing the object to inherit the property value for this name from its parent, if any. This is not usually the behavior you want - see comments in removeProperty() for examples.

Note: if there's a transient value for this property, you have to call removeTransientProperty() on it as well, or you won't actually inherit the value after this call - you'll get the transient value instead.

Specified by:

inheritProperty in interface PropertyList

Parameters:

name - the property name

Returns:

the previous value of the property, if there was one.

getProperties

public final java.util.Set getProperties()

Description copied from interface: PropertyList

Returns the names of all the list's local properties. Does not include inherited properties. Does not include transient properties! If you want to take transient values into account, call getPropertiesIncludingTransients(). For example, if you're searching a player's property list for all properties that start with "wc-", you'll want to include the transient ones as well.

Note: this returns a list of property names - for each name, there may or may not be a transient value. If you're iterating over the list and you only want persistent properties, you'll have to call getPersistentProperty() instead of getProperty().

Specified by:

getProperties in interface PropertyList

Returns:

the local (non-inherited, non-transient) properties. The returned set is a copy of the originals, so you can do whatever you like with it.

getPropertiesIncludingTransients

public final java.util.Set getPropertiesIncludingTransients()

Description copied from interface: PropertyList

Returns the names of all the lists's local properties, including names in the transient list.

Specified by:

getPropertiesIncludingTransients in interface PropertyList

Returns:

all property names in the local and transient lists, but not any inherited property names.

getProperties

public final java.util.Set getProperties(boolean inherit)

Description copied from interface: PropertyList

Returns all the list's properties, optionally including inherited ones.

Specified by:

getProperties in interface PropertyList

Parameters:

inherit - true to include inherited properties, if any. If false, only returns local properties.

getPropertiesIncludingTransients

public final java.util.Set getPropertiesIncludingTransients(boolean inherit)

Description copied from interface: PropertyList

Returns the names of all the lists's local properties, including names in the transient list, and optionally including inherited properties as well.

Specified by:

getPropertiesIncludingTransients in interface PropertyList

Parameters:

inherit - true to include all inherited properties as well. If false, only returns local and transient properties.

Returns:

all property names in the local and transient lists. If the inherit parameter is true, also includes inherited property names.

getSerializableProperties

public final java.util.Set getSerializableProperties()

Description copied from interface: PropertyList

Returns the names of all the lists's local properties, including any properties that have NullValue as values - meaning someone called removeProperty() on them, and the null overrides an inherited version of the property.

Specified by:

getSerializableProperties in interface PropertyList

getTransientProperties

public final java.util.Set getTransientProperties()

Description copied from interface: PropertyList

Returns ONLY the transient properties on this object. Doesn't include properties in the persistent list that start with "@" (effectively making them transient though an older mechanism).

Specified by:

getTransientProperties in interface PropertyList

Returns:

all property names in the transient list.

getSerializableProperty

public final java.lang.Object getSerializableProperty(java.lang.String name)

Description copied from interface: PropertyList

Returns a local property value, but unlike its counterpart getPersistentProperty(), if the value is a NullValue placeholder for when someone called removeProperty() to override an inherited value, this method returns the NullValue.

Specified by:

getSerializableProperty in interface PropertyList

Parameters:

name - the property name

Returns:

value the actual Object stored in the property list, which in most cases is identical to the result from getPersistentProperty(). It can also be a NullValue to indicate that this property is not supposed to be inherited from the parent. Returns null if this property isn't in the local list.

dismantlePropertyList

public final void dismantlePropertyList()

Dismantles the property list, in anticipation of it going away forever. Call this only if you're sure the object is not going to be used again.

toString

public java.lang.String toString()

Returns a string representation of this PropertyList. Doesn't include any inherited properties. Uses transient values of properties - for int properties, adds transient value (if any) to persistent value before printing it.

Returns:

a debugging string

toString

public java.lang.String toString(boolean inherit)

Returns a string represenation of this property list.

Specified by:

toString in interface PropertyList

Parameters:

inherit - true to include inherited properties in the list

Returns:

a string-representation of the object

printProperties

public java.lang.String printProperties()

Description copied from interface: PropertyList

Prints out a nicely formatted list of properties on this object. Prints only the local properties, not inherited ones. Prints transient values, if any, using the rules for transient properties. Transient Object or boolean properties override the persistent values, and int properties get the sum of the transient and persistent parts.

Specified by:

printProperties in interface PropertyList

Returns:

a string that can be used to print the properties

printProperties

public java.lang.String printProperties(boolean inherit)

Description copied from interface: PropertyList

Prints out a nicely formatted list of properties on this object. Prints inherited properties if "inherit" parameter is true. Transient values override persistent values (or for int props, the transient value is added to the persistent value).

Specified by:

printProperties in interface PropertyList

Parameters:

inherit - true to print inherited properties as well.

Returns:

a string that can be used to print the properties

printTransientProperties

public java.lang.String printTransientProperties()

Description copied from interface: PropertyList

Prints only local, transient properties from the object.

Specified by:

printTransientProperties in interface PropertyList

Returns:

a string showing the transient properties in XML format

printLocalProperties

public java.lang.String printLocalProperties()

Description copied from interface: PropertyList

Prints only local, persistent properties: the list returned from getProperties(false).

Specified by:

printLocalProperties in interface PropertyList

Returns:

a string showing the local properties in XML format

debugProperties

public final java.lang.String debugProperties()

Prints out the property list, showing which ones are inherited and which ones are local.

getParent

public final PropertyList getParent()

Description copied from interface: PropertyList

Returns the parent list for this list, if any.

Specified by:

getParent in interface PropertyList

Returns:

the PropertyList (almost always an Archetype) that we're inheriting from, if any.

setParent

public final void setParent(PropertyList parent)

Description copied from interface: PropertyList

Sets the parent list for this list.

Specified by:

setParent in interface PropertyList

setReadOnly

public final void setReadOnly(boolean readOnly)

Description copied from interface: PropertyList

Marks the property list as read-only, so you can't set, remove, or change properties in the list. If you have a reference to a mutable value in the list, you can change it even if the property list is read-only. The purpose of this method is to prevent people from trying to set properties on shared system archetypes, since it affects all instances of the archetype, and it's been the cause of many bugs.

Specified by:

setReadOnly in interface PropertyList

Parameters:

readOnly - true to make the list read-only, false to allow modification

isReadOnly

public final boolean isReadOnly()

Description copied from interface: PropertyList

Returns true if this property list has been marked read-only.

Specified by:

isReadOnly in interface PropertyList

Returns:

true if someone called setReadOnly(true) on it.

getInteger

public static final java.lang.Integer getInteger(int value)

Returns a new Integer object for the specified int value. If the value is between 0 and N, for some small N around 100, then it uses an object-pool reference. Integers are immutable in Java, so we can get away with this. Performance FAQ says not to, though, so I may have to take it out.

Parameters:

value - an int value

Returns:

an Integer wrapper for that value

getProfilingInfo

public static java.lang.String getProfilingInfo()

Returns profiling info. Don't use.