wyvern.lib
Interface PropertyList

All Known Subinterfaces:

Archetype, Armor, Attackable, Bag, Commandable, CommandEvent, Container, Damageable, GameMap, GameObject, HitNotify, Inventory, Monster, Openable, Player, Weapon

All Known Implementing Classes:

AbstractCommandable, AbstractGameMap, ArchetypeImpl, ArmorImpl, BasicBag, Chest, DiggableWall, Door, DynamicObject, EventImpl, Generator, MapObject, MonsterImpl, MonsterInventory, PlayerImpl, PList, Trenchcoat, WeaponImpl

public interface PropertyList

Every GameObject and GameMap has a PropertyList that holds its persistent data, in the form of properties.

Properties are mappings of strings to arbitrary values. The values can be primitive types or any Java or Jython object.

Property lists can inherit from other property lists. They have a parent pointer that can be accessed by getParent(). You can set transient property values in the list. This is useful if you want to make sure your transient value never gets saved out - for instance, if a player wears a ring of invisibility, you don't want the invisible property to be saved out, in case the server crashes after the save (the player would then be permanently invisible). Transient properties have special rules:

• if it's a boolean value or Object (bean/archetype) value, the transient value, if any, overrides the persistent value. For instance, if you set a transient Appearance property, it will override the normal appearance. This means that if you call getProperty(), it first looks for a transient value, and returns that if found, else the normal value.

• if it's an int value, getIntProperty will return the sum of the int value and the transient int value. This is usually the right thing to do - for instance, drinking a potion of strength temporarily adds strength into your transient list, and you want it added to your normal strength. This means if you call getIntProperty(), it will return the sum of the transient value (if any) and the normal value.
• a Double value is treated like an Object value - it overrides the persistent value.

You can override the rules for transient properties by getting the transient and persistent values yourself using getTransientProperty() and getPersistentProperty(), and combine or use the values any way you like. Similarly, if you don't like the fact that the transient int value is added to the normal, persistent int value, you can get the two Integer values with getPersistentProperty() and getTransientProperty() and interpret them however you want.

Note: Setting a transient property never affects the inherited property list - transient properties are always local properties, never inherited.

Version:

1.0, Aug 26, 1997

Author:

Steve Yegge

Field Summary

static java.lang.String

PROPERTY_PACKAGE

Method Summary

void	addProperty(java.lang.String property) 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.
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.
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.
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(boolean inherit) Returns a string representation of this PropertyList, optionally including values of inherited properties.
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.

Field Detail

PROPERTY_PACKAGE

public static final java.lang.String PROPERTY_PACKAGE

See Also:

Constant Field Values

Method Detail

getProperty

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

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" );
 

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 java.lang.Object getTransientProperty(java.lang.String name)

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.

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 java.lang.Object getPersistentProperty(java.lang.String name)

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.

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 void setProperty(java.lang.String name,
                        java.lang.Object value)

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

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.

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

setTransientProperty

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

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().

Parameters:

name - the property name

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

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

addProperty

public void addProperty(java.lang.String property)

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).

Throws:

java.lang.IllegalStateException - if the list is marked read-only

addTransientProperty

public void addTransientProperty(java.lang.String name)

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)).

Parameters:

name - the name of the property to add

Throws:

java.lang.IllegalStateException - if the list is marked read-only

hasProperty

public boolean hasProperty(java.lang.String name)

Checks whether the list contains the given property.

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 boolean hasPersistentProperty(java.lang.String name)

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.

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 boolean hasTransientProperty(java.lang.String name)

Returns true if the transient list contains the specified property.

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 boolean hasLocalProperty(java.lang.String name)

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.

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 java.lang.Object getLocalProperty(java.lang.String name)

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.

Parameters:

name - the name of the property

Returns:

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

getInheritedProperty

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

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

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.

getStringProperty

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

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

Parameters:

name - the property name to look up

Returns:

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

getIntProperty

public int getIntProperty(java.lang.String name)

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).

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.

Throws:

IllegalValueException - if the value is not an Integer (either in the transient list or the persistent list)

setIntProperty

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

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.

Parameters:

name - the property name

value - the new int value for the property

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

adjustIntProperty

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

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.

Parameters:

name - the property name

adjust - the int value to add to the property.

Returns:

the new, adjusted value

Throws:

java.lang.NullPointerException - if the name is null

IllegalValueException - if the value stored under the passed name isn't an Integer.

java.lang.IllegalStateException - if the list is marked read-only

getTransientIntProperty

public int getTransientIntProperty(java.lang.String name)

Gets the current transient value of an int property.

Parameters:

name - the property name

Returns:

the int value stored in the transient part of the plist

Throws:

java.lang.NullPointerException - if the name is null

setTransientIntProperty

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

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

Parameters:

name - the property name

value - the new transient int value for the property

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

adjustTransientIntProperty

public 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). Useful for setting temporary magical bonuses.

Parameters:

name - the property name

adjust - the int value to add to the property.

Returns:

the new, adjusted value

Throws:

IllegalValueException - if the value stored under the passed property isn't an Integer.

java.lang.IllegalStateException - if the list is marked read-only

java.lang.NullPointerException - if the name is null

getPersistentIntProperty

public int getPersistentIntProperty(java.lang.String name)

Gets the current persistent value of an int property.

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 long getLongProperty(java.lang.String name)

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).

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.

Throws:

IllegalValueException - if the value is not a long (either in the transient list or the persistent list)

setLongProperty

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

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.

Parameters:

name - the property name

value - the new long value for the property

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

adjustLongProperty

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

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.

Parameters:

name - the property name

adjust - the long value to add to the property.

Returns:

the new, adjusted value

Throws:

java.lang.NullPointerException - if the name is null

IllegalValueException - if the value stored under the passed name isn't a Long.

java.lang.IllegalStateException - if the list is marked read-only

getTransientLongProperty

public long getTransientLongProperty(java.lang.String name)

Gets the current transient value of a long property.

Parameters:

name - the property name

Returns:

the long value stored in the transient part of the plist

setTransientLongProperty

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

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

Parameters:

name - the property name

value - the new transient long value for the property

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

adjustTransientLongProperty

public 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). Useful for setting temporary magical bonuses.

Parameters:

name - the property name

adjust - the long value to add to the property.

Throws:

IllegalValueException - if the value stored under the passed property isn't a Long.

java.lang.IllegalStateException - if the list is marked read-only

java.lang.NullPointerException - if the name is null

getPersistentLongProperty

public long getPersistentLongProperty(java.lang.String name)

Gets the current persistent value of a long property.

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 double getDoubleProperty(java.lang.String name)

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).

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.

Throws:

IllegalValueException - if the value is not a double (either in the transient list or the persistent list)

setDoubleProperty

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

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.

Parameters:

name - the property name

value - the new double value for the property

Throws:

java.lang.IllegalStateException - if the list is marked read-only

adjustDoubleProperty

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

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.

Parameters:

name - the property name

adjust - the double value to add to the property.

Returns:

the new, adjusted value

Throws:

IllegalValueException - if the value stored under the passed name isn't a Double.

java.lang.IllegalStateException - if the list is marked read-only

getTransientDoubleProperty

public double getTransientDoubleProperty(java.lang.String name)

Gets the current transient value of a double property.

Parameters:

name - the property name

Returns:

the double value stored in the transient part of the plist

setTransientDoubleProperty

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

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

Parameters:

name - the property name

value - the new transient double value for the property

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalStateException - if the list is marked read-only

adjustTransientDoubleProperty

public 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). Useful for setting temporary magical bonuses.

Parameters:

name - the property name

adjust - the double value to add to the property.

Throws:

IllegalValueException - if the value stored under the passed name isn't a Double

java.lang.IllegalStateException - if the list is marked read-only

getPersistentDoubleProperty

public double getPersistentDoubleProperty(java.lang.String name)

Gets the current persistent value of a double property.

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 java.lang.Object removeProperty(java.lang.String name)

Removes a persistent property from the list.

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.

Throws:

java.lang.IllegalStateException - if the list is marked read-only

removeTransientProperty

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

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.

Parameters:

name - the property name

Returns:

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

Throws:

java.lang.IllegalStateException - if the list is marked read-only

transientlyRemoveProperty

public 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. 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().

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.

Throws:

java.lang.IllegalStateException - if you try to call this method on a read-only property list.

inheritProperty

public 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. 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.

Parameters:

name - the property name

Returns:

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

Throws:

java.lang.IllegalStateException - if you try to call this method on a read-only property list.

getProperties

public java.util.Set getProperties()

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().

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 java.util.Set getPropertiesIncludingTransients()

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

Returns:

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

getProperties

public java.util.Set getProperties(boolean inherit)

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

Parameters:

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

getPropertiesIncludingTransients

public 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.

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 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.

getTransientProperties

public java.util.Set getTransientProperties()

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).

Returns:

all property names in the transient list.

getSerializableProperty

public 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.

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.

toString

public java.lang.String toString(boolean inherit)

Returns a string representation of this PropertyList, optionally including values of inherited properties. Uses transient values of properties, if any.

Parameters:

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

printProperties

public java.lang.String printProperties()

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.

Returns:

a string that can be used to print the properties

printProperties

public java.lang.String printProperties(boolean inherit)

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).

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()

Prints only local, transient properties from the object.

Returns:

a string showing the transient properties in XML format

printLocalProperties

public java.lang.String printLocalProperties()

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

Returns:

a string showing the local properties in XML format

countLocalProperties

public int countLocalProperties()

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

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 java.util.Set getLocalProperties()

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

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 java.util.Set getPersistentLocalProperties()

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

Returns:

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

setParent

public void setParent(PropertyList parent)

Sets the parent list for this list.

getParent

public PropertyList getParent()

Returns the parent list for this list, if any.

Returns:

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

setReadOnly

public void setReadOnly(boolean readOnly)

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.

Parameters:

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

isReadOnly

public boolean isReadOnly()

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

Returns:

true if someone called setReadOnly(true) on it.

isRemoved

public 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. 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.

Parameters:

name - the property name to check

Returns:

true if the property's value is a NullValue

isTransientlyRemoved

public boolean isTransientlyRemoved(java.lang.String name)

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.

Parameters:

name - the property name to check

Returns:

true if the property's value is a NullValue