com.pega.pegarules.pub.clipboard
Interface ClipboardProperty

public interface ClipboardProperty

Represents a single property.

Note that there are two distinct ways of retrieving a property's value. The first group of methods are named getStringValue, getPageValue, and getPropertyValue. These all return the raw value contained by the property. This value isn't manipulated as a result of the method.

The other group of methods are named toBoolean, toDate, toDouble, toInteger, and toString. These methods all ensure that the property attributes match those found in its dictionary definition and attempt to validate the property before returning a value. If the parent page of this property is classless, the property is not validated.

An additional overload of the to* methods is provided, where the current PegaAPI object is passed as an argument. These methods should be used when the caller may want to be informed of missing or empty properties, instead of simply receiving the default empty value of the given property. These methods check the PegaAPI.isBackwardChaining() flag; if true, and the given property is missing or empty, a MissingPropertyException will be thrown. If false, or if a null PegaAPI object is passed to the method, the normal to* method behavior will apply (the default value will be returned).

Lightweight Page Lists

Lightweight Page Lists are a special version of Page Lists. Indicated by the "Is Lightweight" field in Rule-Obj-Property, Lightweight Page Lists can hold only string values. Think of a Lightweight Page List as containing a table of string values, with the columns representing property values and the rows representing pages in the list.

Pages and properties in a Lightweight Page List cannot have attached messages. They will be ignored for the purposes of declarative rules. All pages in a lightweight page list must be of the same class (or descendant of said class). The internal structure of lightweight page lists is different from a normal page list, which causes certain methods to behave differently:

• add(int, Object) and add(Object): StringMap and ClipboardPage objects may be added to Lightweight Page Lists.
• getColumnInfos(): Usable only with Lightweight Page Lists. Returns property information for each column (property).
• getColumnNames(): Usable only with Lightweight Page Lists. Returns column (property) names.
• getPageValue(int): Not usable with Lightweight Page Lists.
• getPropertyValue(int): Not usable with Lightweight Page Lists.
• getStringValue(int, String): Use this method to retrieve an individual value from a Lightweight Page List.
• isLightweight(): Is this property lightweight?
• iterator(): Elements in a Lightweight Page List iterator are String arrays (String[]), not ClipboardProperty instances. The order of the values in these arrays is the same as the order in the Column Name and Info arrays returned by getColumnNames() and getColumnInfos().

Version:

$Revision: 21101 $ $Date: 2012-02-22 10:12:41 -0500 (Wed, 22 Feb 2012) $

Author:

Gabe Ernst-Edwards

Field Summary

static java.lang.String	COPYRIGHT
static int	LIST_APPEND When passed as the index parameter to getPropertyValue(int), getPageValue(), or getStringValue(), a new property will be created and appended to the end of this list.
static java.lang.String	VERSION

Method Summary

void	add(int aAtPosition, java.lang.Object aValue) Inserts a value at the specified position in this list property.
void	add(java.lang.Object aValue) Append a value to the end of this list property.
void	add(java.lang.String aGroupSubscript, java.lang.Object aValue) Add a value to the group contained by this property.
void	addMessage(java.lang.String aMsgDescr) Associates a message descriptor with this property.
void	addMessage(java.lang.String aMsgDescr, java.lang.String aFieldName) Associates a message descriptor with this property.
void	addMessageWithKey(java.lang.String aMsgDescr, java.lang.String aPzInsKey) Associates a message descriptor and pzInsKey of its originated rule with this property.
void	addMessageWithKey(java.lang.String aMsgDescr, java.lang.String aFieldName, java.lang.String aPzInsKey) Associates a message descriptor and pzInsKey of its originated rule with this property.
void	clearAttrProtected() Clear the Protected attribute from this property.
void	clearMessages() Clears all messages (and the Error attribute) from this property and all embedded pages and properties.
void	clearValue() Eliminate the value of this property.
java.util.List	getColumnInfos() Get the list of ImmutablePropertyInfo instances, one for each column in this lightweight page list.
java.util.List	getColumnNames() Get the list of column names in this lightweight page list.
int	getDecimalPrecision() returns the decimal precision defined for this property.
java.lang.String	getEntryHandle() Returns a handle to this property that can be used for receiving client input.
java.lang.String	getEntryHandle(boolean aIncludeSubscripts) Returns a handle to this property that can be used for receiving client input.
java.lang.String	getEntryHandle(java.lang.String aPropertyReference) Returns a handle to the referenced property that can be used for receiving client input.
java.lang.String	getGatewayPageName(ClipboardPage aPage, java.lang.String aGatewayClass) Get the fully qualified gateway page name if this property was used as a gateway to other instance's properties.
java.lang.String	getLocalizedText() Returns the localized value of a property
java.lang.String	getLocalizedText(java.lang.String aString) Returns the localized value of aString, using the localization info from this property
int	getMaxLength() Get the maximum length of a string type in this property.
int	getMessageCount() Returns count of messages added to this property.
java.lang.String	getMessages() Returns any message(s) added for this property.
char	getMode() Returns the mode of this property.
java.lang.String	getModeName() Returns the English name of this property's mode.
java.lang.String	getName() Returns the name of this property.
java.lang.Object	getObjectValue() Return value of this Java Object property.
java.lang.Object	getObjectValue(int aIndex) Returns the Object value of an element of this Java Object List property.
java.lang.Object	getObjectValue(java.lang.String aGroupSubscript) Returns the Object value of an element of this Java Object group property.
ClipboardPage	getPageValue() Return value of this property as a page.
ClipboardPage	getPageValue(int aIndex) Returns the ClipboardPage value of an element of this page list property.
ClipboardPage	getPageValue(java.lang.String aGroupSubscript) Returns the ClipboardPage value of an element of this page group property.
ClipboardPage	getParentPage() Identifies the page which contains this property.
ClipboardProperty	getParentProperty() Identifies the property which contains this property.
ClipboardProperty	getProperty(java.lang.String aReference) Provides a ClipboardProperty instance corresponding to the referenced item.
ClipboardProperty	getPropertyValue(int aIndex) Returns a ClipboardProperty element of this list property.
ClipboardProperty	getPropertyValue(java.lang.String aGroupSubscript) Returns a ClipboardProperty element of this group property.
java.lang.String	getQualifier(java.lang.String aName) Gets a run-time qualifier value of this property.
java.lang.String	getReference() Returns an absolute reference to this property.
java.lang.String	getReferenceInformation() Get debug information describing this property's Reference attributes
java.lang.String	getReferenceString() Get the fully qualified reference of the property this Reference Property points to.
java.lang.String	getStandardText(java.lang.String aKey) Returns the standard value of a property
java.lang.String	getStringValue() Return value of this property as a string.
java.lang.String	getStringValue(int aIndex) Returns the String value of an element of this string list property.
java.lang.String	getStringValue(int aIndex, java.lang.String aPropertyName) Get a string value from a property in a page list.
java.lang.String	getStringValue(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a string, or if the caller wants, an exception when the property is missing or empty.
java.lang.String	getStringValue(java.lang.String aGroupSubscript) Returns the String value of an element of this string group property.
ClipboardPage	getTopLevelPage() Identifies the top-level page that contains this property.
char	getType() Returns the data type of this property.
java.lang.String	getTypeName() Returns the English name of this property's type.
boolean	hasAttrError() Test if the Error attribute is set for this property, indicating that a message was added for it.
boolean	hasAttrIncompatible() Test if the Incompatible attribute is set for this property, which happens when the structure of the property conflicts with its definition.
boolean	hasAttrProtected() Test if the Protected attribute is set for this property.
boolean	hasAttrUndefined() Test if the Undefined attribute is set for this property, which happens when the Pega.Page.applySemantics method fails to find a Rule-Obj-Property instance to define this property.
boolean	hasGoodValue() Test if the property has a good value.
boolean	hasInvalidValue() Test if the property has an invalid value.
boolean	hasReference() If this is a TYPE_REFERENCE_PAGE property, has a reference been established to another property? This method has three possible states: 1.
boolean	hasValidValue() Test if the property has a valid value.
int	indexOf() If this property is an element of a list, return its index in the list.
boolean	isBad() Test if the property has a bad value.
boolean	isDefinedAsReference() In the Rule-Obj-Property definition of this property, is the "Is Reference Property" flag enabled?
boolean	isEmpty() Query if this property has no value.
boolean	isGroup() Query if this property has a group structure
boolean	isGroupElement() Is this property an elemeint in a group?
boolean	isJavaObject() Query if this property is of mode JavaObject.
boolean	isLightweight() Is this a lightweight property? Lightweight properties use an efficient structure to save processing overhead, but require special methods to access their contents.
boolean	isList() Query if this property has a list structure
boolean	isListElement() Is this property an element in a list?
boolean	isModifiable() Test if the property is modifiable.
boolean	isPage() Query if this property has a page mode (which includes groups).
boolean	isReadOnly() Query if this property is on a Read Only page
boolean	isScalar() Test if the property is scalar.
boolean	isSpecial() Test if the property is "Special".
java.util.Iterator	iterator() Returns an iterator allowing access to values contained in this list, page, or group property.
boolean	moveValue(java.lang.Object aSourceValue) Set value of property and remove the source property from its parent.
java.lang.Object	remove(int aIndex) Removes the indexed element from this property's list.
java.lang.Object	remove(java.lang.String aGroupSubscript) Remove an element from the group contained by this property.
void	removeFromClipboard() Removes this property from its parent, which is either a page or a list.
boolean	resetReferenceInformation() If this property is a Reference Property, reset the reference information to "unlink" it from the source property.
boolean	seekValue(PublicAPI aTools) Invoke backward chaining to compute the value of this property, given the current state of the declarative expression network for the top-level page.
boolean	seekValue(PublicAPI aTools, boolean aAlwaysRecompute) Invoke backward chaining to compute the value of this property, given the current state of the declarative expression network for the top-level page.
void	setAsReference(PRThread aThread, ClipboardProperty aSourceProperty) Set this property as a reference to another specified property.
void	setAttrProtected() Set the Protected attribute for this property.
void	setEntryCode(java.lang.String aEntryCode) Set the dictionary definition of this property.
void	setQualifier(java.lang.String aName, java.lang.String aValue) Sets a run-time qualifier value for this property.
boolean	setValue(com.pega.ibm.icu.math.BigDecimal aValue) Set value of property from BigDecimal value.
boolean	setValue(boolean aValue) Set value of property from boolean value.
boolean	setValue(ClipboardProperty aValue) Set value of property.
boolean	setValue(java.util.Date aValue) Set value of property from Date value.
boolean	setValue(double aValue) Set value of property from double value.
boolean	setValue(int aValue) Set value of property from int value.
boolean	setValue(java.lang.Object aValue) Set value of property.
boolean	setValueFromLocalizedString(java.lang.String aLocale, java.lang.String aValue) Interprets the specified string according to locale specific conventions and sets the normalized value into the property
int	size() Get the length of an atomic property or the number of elements in this list or group property.
com.pega.ibm.icu.math.BigDecimal	toBigDecimal() Return value of this property as a IBM BigDecimal value.
com.pega.ibm.icu.math.BigDecimal	toBigDecimal(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a IBM BigDecimal value, or if the caller wants, an exception when the property is missing or empty.
boolean	toBoolean() Return value of this property as a boolean value.
boolean	toBoolean(boolean aDefault) Return value of this property as a boolean value.
boolean	toBoolean(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a boolean value, or if the caller wants, an exception when the property is missing or empty.
java.util.Date	toDate() Return value of this property as a date.
java.util.Date	toDate(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a date, or if the caller wants, an exception when the property is missing or empty.
double	toDouble() Return value of this property as a double.
double	toDouble(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a double.
int	toInteger() Return value of this property as an integer.
int	toInteger(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a int, or if the caller wants, an exception when the property is missing or empty.
java.lang.String	toString() Return value of this property as a string.
java.lang.String	toString(com.pega.pegarules.priv.PegaAPI aPega) Return value of this property as a string, or if the caller wants, an exception when the property is missing or empty.

Field Detail

COPYRIGHT

static final java.lang.String COPYRIGHT

See Also:

Constant Field Values

VERSION

static final java.lang.String VERSION

See Also:

Constant Field Values

LIST_APPEND

static final int LIST_APPEND

When passed as the index parameter to getPropertyValue(int), getPageValue(), or getStringValue(), a new property will be created and appended to the end of this list.

See Also:

Constant Field Values

Method Detail

add

void add(java.lang.String aGroupSubscript,
         java.lang.Object aValue)

Add a value to the group contained by this property.

Parameters:

aGroupSubscript - the subscript of the new group element

aValue - the new value to add. May be a String, ClipboardPage, or a ClipboardProperty of String or Page mode. If aValue is an embedded ClipboardProperty or a named or embedded ClipboardPage, a copy of the value is made and placed into the list.

Throws:

WrongModeException - if this property does not contain a group or the value is of an incompatible mode

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

remove

java.lang.Object remove(java.lang.String aGroupSubscript)

Remove an element from the group contained by this property.

Parameters:

aGroupSubscript - name of the element to remove

Returns:

element removed

Throws:

WrongModeException - if this property does not contain a group

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

remove

java.lang.Object remove(int aIndex)

Removes the indexed element from this property's list.

Parameters:

aIndex - one-based element number

Returns:

null (the removed object is never returned)

Throws:

WrongModeException - if this property does not contain a list

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

removeFromClipboard

void removeFromClipboard()

Removes this property from its parent, which is either a page or a list.

Throws:

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

getMode

char getMode()

Returns the mode of this property. The mode describes the structure of this property's value.

Returns:

This property's mode. The return value will be one of these constants:

• ImmutablePropertyInfo.MODE_UNKNOWN
• ImmutablePropertyInfo.MODE_JAVAOBJECT
• ImmutablePropertyInfo.MODE_JAVAOBJECT_LIST
• ImmutablePropertyInfo.MODE_JAVAOBJECT_GROUP
• ImmutablePropertyInfo.MODE_JAVAPROPERTY
• ImmutablePropertyInfo.MODE_JAVAPROPERTY_LIST
• ImmutablePropertyInfo.MODE_STRING
• ImmutablePropertyInfo.MODE_STRING_LIST
• ImmutablePropertyInfo.MODE_STRING_GROUP
• ImmutablePropertyInfo.MODE_PAGE
• ImmutablePropertyInfo.MODE_PAGE_LIST
• ImmutablePropertyInfo.MODE_PAGE_GROUP

getModeName

java.lang.String getModeName()

Returns the English name of this property's mode.

Returns:

the name of this property's mode (i.e. "String" or "Page List")

getName

java.lang.String getName()

Returns the name of this property.

If this property is a List element, the name is blank. Use indexOf() to get the position of this property in its list. If this property is a Group element, its name equal to its group subscript.

Returns:

this property's name

getReference

java.lang.String getReference()

Returns an absolute reference to this property. This method will fail if the property is not embedded in a top-level page.

Returns:

a reference to this property

isReadOnly

boolean isReadOnly()

Query if this property is on a Read Only page

Returns:

true if the property is read only false otherwise

getType

char getType()

Returns the data type of this property. The type describes the format and semantics of this property's value.

Returns:

This property's type. The return value will be one of these constants:

• ImmutablePropertyInfo.TYPE_UNKNOWN
• ImmutablePropertyInfo.TYPE_FREEFORM
• ImmutablePropertyInfo.TYPE_TEXT
• ImmutablePropertyInfo.TYPE_IDENTIFIER
• ImmutablePropertyInfo.TYPE_PASSWORD
• ImmutablePropertyInfo.TYPE_TEXTENCRYPTED
• ImmutablePropertyInfo.TYPE_DATETIME
• ImmutablePropertyInfo.TYPE_DATE
• ImmutablePropertyInfo.TYPE_TIMEOFDAY
• ImmutablePropertyInfo.TYPE_TRUEFALSE
• ImmutablePropertyInfo.TYPE_NUMBER
• ImmutablePropertyInfo.TYPE_DECIMAL
• ImmutablePropertyInfo.TYPE_AMOUNT
• ImmutablePropertyInfo.TYPE_TOPLEVEL_PAGE
• ImmutablePropertyInfo.TYPE_INCLUDED_PAGE
• ImmutablePropertyInfo.TYPE_DISTINCT_PAGE

getTypeName

java.lang.String getTypeName()

Returns the English name of this property's type.

Returns:

the name of this property's type

getMaxLength

int getMaxLength()

Get the maximum length of a string type in this property.

Returns:

Maximum length. 0 indicates no length limits are imposed.

hasAttrError

boolean hasAttrError()

Test if the Error attribute is set for this property, indicating that a message was added for it.

Returns:

true if the Error attribute is set, false otherwise

hasAttrIncompatible

boolean hasAttrIncompatible()

Test if the Incompatible attribute is set for this property, which happens when the structure of the property conflicts with its definition. For example, a list when a group is expected.

Returns:

true if the Incompatible attribute is set, false otherwise

hasAttrProtected

boolean hasAttrProtected()

Test if the Protected attribute is set for this property.

Returns:

true if the Protected attribute is set, false otherwise

hasAttrUndefined

boolean hasAttrUndefined()

Test if the Undefined attribute is set for this property, which happens when the Pega.Page.applySemantics method fails to find a Rule-Obj-Property instance to define this property.

Returns:

true if the Undefined attribute is set, false otherwise

hasGoodValue

boolean hasGoodValue()

Test if the property has a good value.

Returns:

true if this property is not empty and does not have the Error or External attribute set, false otherwise

hasInvalidValue

boolean hasInvalidValue()

Test if the property has an invalid value.

Returns:

true if this property is not empty and has the External attribute set, false otherwise

hasValidValue

boolean hasValidValue()

Test if the property has a valid value.

Returns:

true if this property is not empty and does not have the External attribute set, false otherwise

getPageValue

ClipboardPage getPageValue(int aIndex)

Returns the ClipboardPage value of an element of this page list property.

Parameters:

aIndex - one-based index of the desired element. Pass the special value ClipboardProperty.LIST_APPEND to have a new page appended to this list and returned.

Returns:

the value of this list element

Throws:

WrongModeException - this property is not a page list

getPageValue

ClipboardPage getPageValue(java.lang.String aGroupSubscript)

Returns the ClipboardPage value of an element of this page group property.

Parameters:

aGroupSubscript - name of element value to be returned

Returns:

the value of this group element

Throws:

WrongModeException - this property is not a page or page group

getPropertyValue

ClipboardProperty getPropertyValue(int aIndex)

Returns a ClipboardProperty element of this list property.

Parameters:

aIndex - one-based index of the desired element. Pass the special value ClipboardProperty.LIST_APPEND to have a new property appended to this list and returned.

Returns:

the list element

Throws:

WrongModeException - this property is not a list

getPropertyValue

ClipboardProperty getPropertyValue(java.lang.String aGroupSubscript)

Returns a ClipboardProperty element of this group property.

Parameters:

aGroupSubscript - name of the element to return

Returns:

the group element

Throws:

WrongModeException - this property is not a page or group

getStringValue

java.lang.String getStringValue(int aIndex)

Returns the String value of an element of this string list property. The string value returned is raw-- it is not validated or formatted as a result of this method.

Parameters:

aIndex - one-based index of the desired element. Pass the special value ClipboardProperty.LIST_APPEND to have a new property appended to this list and returned.

Returns:

the value of this list element

Throws:

WrongModeException - this property is not a string list

getStringValue

java.lang.String getStringValue(java.lang.String aGroupSubscript)

Returns the String value of an element of this string group property. The string value returned is raw-- it is not validated or formatted as a result of this method.

Parameters:

aGroupSubscript - name of the group element value to return

Returns:

the value of this group element

Throws:

WrongModeException - this property is not a page or string group

getObjectValue

java.lang.Object getObjectValue()

Return value of this Java Object property. This method is only applicable to properties of the Java Object mode.

Returns:

Object contained by this property

Throws:

WrongModeException - The property's mode is not ImmutablePropertyInfo.MODE_JAVAOBJECT.

getObjectValue

java.lang.Object getObjectValue(int aIndex)

Returns the Object value of an element of this Java Object List property.

Parameters:

aIndex - one-based index of the desired element. Pass the special value ClipboardProperty.LIST_APPEND to have a new property appended to this list and returned.

Returns:

the value of this list element

Throws:

WrongModeException - this property is not a Java Object List

getObjectValue

java.lang.Object getObjectValue(java.lang.String aGroupSubscript)

Returns the Object value of an element of this Java Object group property.

Parameters:

aGroupSubscript - name of the group element value to return

Returns:

the value of this group element

Throws:

WrongModeException - this property is not a page or Java Object group

indexOf

int indexOf()

If this property is an element of a list, return its index in the list. The first position in the list is 1.

Returns:

index of this property

Throws:

WrongModeException - this property is not a list

isEmpty

boolean isEmpty()

Query if this property has no value.

Returns:

true if the property is a list or group that has no elements, a page that contains no properties, a string that is null, or the mode is unknown

isList

boolean isList()

Query if this property has a list structure

Returns:

true if the property contains a list, false otherwise

isGroup

boolean isGroup()

Query if this property has a group structure

Returns:

true if the property contains a group, false otherwise

isJavaObject

boolean isJavaObject()

Query if this property is of mode JavaObject.

Returns:

true if the property is a JavaObject, false otherwise

isPage

boolean isPage()

Query if this property has a page mode (which includes groups).

Returns:

true if the property has a page mode, false otherwise

isBad

boolean isBad()

Test if the property has a bad value.

Returns:

true if this property is not empty and has the External attribute set, or has the Error attribute set, false otherwise

isModifiable

boolean isModifiable()

Test if the property is modifiable. This implies that its mode is defined and the Protected attribute is not set.

Returns:

true if this property is modifiable, false otherwise

isScalar

boolean isScalar()

Test if the property is scalar. This implies that its mode is defined to be String.

Returns:

true if this property is scalar, false otherwise

isSpecial

boolean isSpecial()

Test if the property is "Special". This implies that it is not available for direct input from the user.

Returns:

true if this property is special, false otherwise

addMessage

void addMessage(java.lang.String aMsgDescr)

Associates a message descriptor with this property. Adding a message to the property causes the Error attribute to be set.

Parameters:

aMsgDescr - the message to be added to this property

Throws:

InvalidParameterException - aMsgDescr cannot be null

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

addMessage

void addMessage(java.lang.String aMsgDescr,
                java.lang.String aFieldName)

Associates a message descriptor with this property. Adding a message to the property causes the Error attribute to be set.

Parameters:

aMsgDescr - the message to be added to this property

aFieldName - 'field name' for the FieldValue definitions this will be translated through

Throws:

InvalidParameterException - aMsgDescr cannot be null

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

addMessageWithKey

void addMessageWithKey(java.lang.String aMsgDescr,
                       java.lang.String aPzInsKey)

Associates a message descriptor and pzInsKey of its originated rule with this property. Adding a message to the property causes the Error attribute to be set.

Parameters:

aMsgDescr - the message to be added to this property

aPzInsKey - (optional) The pzInsKey of the rule where the message originated.

Throws:

InvalidParameterException - aMsgDescr cannot be null

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

addMessageWithKey

void addMessageWithKey(java.lang.String aMsgDescr,
                       java.lang.String aFieldName,
                       java.lang.String aPzInsKey)

Associates a message descriptor and pzInsKey of its originated rule with this property. Adding a message to the property causes the Error attribute to be set.

Parameters:

aMsgDescr - the message to be added to this property

aFieldName - 'field name' for the FieldValue definitions this will be translated through

aPzInsKey - (optional) The pzInsKey of the rule where the message originated.

Throws:

InvalidParameterException - aMsgDescr cannot be null

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

clearMessages

void clearMessages()

Clears all messages (and the Error attribute) from this property and all embedded pages and properties.

Throws:

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

clearAttrProtected

void clearAttrProtected()

Clear the Protected attribute from this property.

Throws:

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

clearValue

void clearValue()

Eliminate the value of this property.

Throws:

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

iterator

java.util.Iterator iterator()

Returns an iterator allowing access to values contained in this list, page, or group property. Note that this iterator reflects the contents of this property at the time of its creation. Further changes to this property will not be reflected in this iterator.

Returns:

the iterator. For most properties, the objects returned by Iterator.next() are ClipboardProperty instances. Lightweight page lists are the exception; in this case the objects are String arrays (String[]).

Throws:

WrongModeException - this property does not contain a list, page, or group

toBoolean

boolean toBoolean()

Return value of this property as a boolean value. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a boolean even if the property's type does not match.

Returns:

value of this property, or false if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a boolean.

toBoolean

boolean toBoolean(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a boolean value, or if the caller wants, an exception when the property is missing or empty. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a boolean even if the property's type does not match.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of returning the default empty value).

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

value of this property, or false if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a boolean.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

toBoolean

boolean toBoolean(boolean aDefault)

Return value of this property as a boolean value. In the process, this property's definition is retrieved from the dictionary if it is not already known.

Parameters:

aDefault - The value to return if the actual property value can't be returned for some reason (it's blank or doesn't contain a boolean value).

Returns:

value of this property or the value of aDefault if the actual value could not be returned.

toDate

java.util.Date toDate()

Return value of this property as a date. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a Date even if the property's type does not match.

Returns:

value of this property, or 1970-Jan-01 if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a Date.

toDate

java.util.Date toDate(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a date, or if the caller wants, an exception when the property is missing or empty. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a Date even if the property's type does not match.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of returning the default empty value). If the property is missing or empty, and PegaAPI.isBackwardChaining() is set to true, a MissingPropertyException is thrown.

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

value of this property, or 1970-Jan-01 if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a Date.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

toDouble

double toDouble()

Return value of this property as a double. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a double even if the property's type does not match.

Returns:

value of this property, or 0.0 if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a double.

toDouble

double toDouble(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a double. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a double even if the property's type does not match.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of the default empty value). If the property is missing or empty, and isBackwardChaining() is set to true, a MissingPropertyException is thrown.

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

value of this property, or 0.0 if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a double.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

toBigDecimal

com.pega.ibm.icu.math.BigDecimal toBigDecimal()

Return value of this property as a IBM BigDecimal value. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a BigDecimal even if the property's type does not match.

Returns:

value of this property, or BigDecimal.ZERO if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a BigDecimal.

toBigDecimal

com.pega.ibm.icu.math.BigDecimal toBigDecimal(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a IBM BigDecimal value, or if the caller wants, an exception when the property is missing or empty. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a BigDecimal even if the property's type does not match.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of returning the default empty value). If the property is missing or empty, and PegaAPI.isBackwardChaining() is set to true, a MissingPropertyException is thrown.

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

value of this property, or BigDecimal.ZERO if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a BigDecimal.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

toInteger

int toInteger()

Return value of this property as an integer. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return an integer even if the property's type does not match.

Returns:

value of this property, or 0 if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a integer.

toInteger

int toInteger(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a int, or if the caller wants, an exception when the property is missing or empty. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a int even if the property's type does not match.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of returning the default empty value). If the property is missing or empty, and PegaAPI.isBackwardChaining() is set to true, a MissingPropertyException is thrown.

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

value of this property, or 0 if the property is empty.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a double.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

toString

java.lang.String toString()

Return value of this property as a string.

Overrides:

toString in class java.lang.Object

Returns:

value of this property. If the value could not be returned as a string an empty string ("") is returned.

toString

java.lang.String toString(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a string, or if the caller wants, an exception when the property is missing or empty. In the process, this property's definition is retrieved from the dictionary if it is not already known. This method will attempt to return a string even if the property's type does not match.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of returning the default empty value). If the property is missing or empty, and PegaAPI.isBackwardChaining() is set to true, a MissingPropertyException is thrown.

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

value of this property as a String. If the value could not be returned as a string an empty string ("") is returned.

Throws:

InvalidValueException - if this property is not empty and it cannot be converted to a double.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

getPageValue

ClipboardPage getPageValue()

Return value of this property as a page. If the mode of this property is unknown and the property is not read-only, the mode is set to ImmutablePropertyInfo.MODE_PAGE.

Returns:

ClipboardPage contained by this property (never null).

Throws:

WrongModeException - The property's mode is not ImmutablePropertyInfo.MODE_PAGE.

getStringValue

java.lang.String getStringValue()

Return value of this property as a string. If the mode of this property is unknown and the property is not read-only, the mode is set to ImmutablePropertyInfo.MODE_STRING. The string value returned is raw-- it is not validated or formatted as a result of this method.

Returns:

String contained by this property (never null).

Throws:

WrongModeException - The property's mode is not ImmutablePropertyInfo.MODE_STRING.

getStringValue

java.lang.String getStringValue(com.pega.pegarules.priv.PegaAPI aPega)

Return value of this property as a string, or if the caller wants, an exception when the property is missing or empty. If the mode of this property is unknown and the property is not read-only, the mode is set to ImmutablePropertyInfo.MODE_STRING. The string value returned is raw-- it is not validated or formatted as a result of this method.

Use this method if the caller may want to know whether this property is empty or not present on the clipboard (instead of the default empty value). If the property is missing or empty, and isBackwardChaining() is set to true, a MissingPropertyException is thrown.

Parameters:

aPega - The current PegaAPI, used to determine if backward chaining is enabled.

Returns:

String contained by this property (never null).

Throws:

WrongModeException - The property's mode is not ImmutablePropertyInfo.MODE_STRING.

MissingPropertyException - if this property is empty or missing, and PegaAPI.isBackwardChaining() is set to true.

getDecimalPrecision

int getDecimalPrecision()

returns the decimal precision defined for this property.

Returns:

number of digits to right of decimal point, or -1 if not specified or not applicable

getEntryHandle

java.lang.String getEntryHandle()

Returns a handle to this property that can be used for receiving client input. An entry handle is a special form of property reference that is used in the context of Streams.

Returns:

the handle. If there is none, an empty string is returned.

getEntryHandle

java.lang.String getEntryHandle(java.lang.String aPropertyReference)

Returns a handle to the referenced property that can be used for receiving client input. An entry handle is a special form of property reference that is used in the context of Streams. The results of this method can differ from getEntryHandle() if there is a Reference Property somewhere within the structure covered by aPropertyReference.

Parameters:

aPropertyReference - property reference to get the entry handle for. The reference is evaluated relative to this property. This property cannot be a List or Group, but elements are allowed. For instance, this property can't be .pxResults, but .pxResults(1) is allowed.

Returns:

the handle. If there is none, an empty string is returned.

Throws:

WrongModeException - this property is a list or group

getEntryHandle

java.lang.String getEntryHandle(boolean aIncludeSubscripts)

Returns a handle to this property that can be used for receiving client input. An entry handle is a special form of property reference that is used in the context of Streams.

Parameters:

aIncludeSubscripts - Should the entry handle include subscript details for list/groups?

Returns:

the handle. If there is none, an empty string is returned.

getMessages

java.lang.String getMessages()

Returns any message(s) added for this property. The messages will have been formatted for display and multiple messages will be separated by newline ('\n') characters.

Returns:

the message(s). If there are none, an empty string is returned.

getMessageCount

int getMessageCount()

Returns count of messages added to this property.

Returns:

message count

setAttrProtected

void setAttrProtected()

Set the Protected attribute for this property.

Throws:

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

setValue

boolean setValue(boolean aValue)

Set value of property from boolean value.

Parameters:

aValue - the new value for this property.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified Note: setting the value of a property clears any messages associated with that property as well!

setValue

boolean setValue(java.util.Date aValue)

Set value of property from Date value.

Parameters:

aValue - the new value for this property.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified Note: setting the value of a property clears any messages associated with that property as well!

setValue

boolean setValue(double aValue)

Set value of property from double value.

Parameters:

aValue - the new value for this property.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified Note: setting the value of a property clears any messages associated with that property as well!

setValue

boolean setValue(int aValue)

Set value of property from int value.

Parameters:

aValue - the new value for this property.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified Note: setting the value of a property clears any messages associated with that property as well!

setValue

boolean setValue(com.pega.ibm.icu.math.BigDecimal aValue)

Set value of property from BigDecimal value.

Parameters:

aValue - the new value for this property.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

setValue

boolean setValue(java.lang.Object aValue)

Set value of property. Any messages associated with this property are cleared.

Parameters:

aValue - An object to be used as the new value of this property. If aValue is an embedded ClipboardProperty or a named or embedded ClipboardPage, a copy of the value is made and placed into the list. Note that properties with blank ("") values may be stripped from the page during serialization.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

setValueFromLocalizedString

boolean setValueFromLocalizedString(java.lang.String aLocale,
                                    java.lang.String aValue)

Interprets the specified string according to locale specific conventions and sets the normalized value into the property

Parameters:

aLocale - locale in which value is to be interpreted, or null for default

aValue - value to be interpreted and set

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

setValue

boolean setValue(ClipboardProperty aValue)

Set value of property. Any messages associated with this property are cleared.

Parameters:

aValue - A ClipboardProperty object whose value will be copied and used as the new value of this property. The attributes of this source property are also copied to the target property.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

add

void add(java.lang.Object aValue)

Append a value to the end of this list property. This property must have a list mode.

Parameters:

aValue - A ClipboardProperty, String, ClipboardPage, or StringMap object to be appended to this list property. If aValue is an embedded ClipboardProperty or a named or embedded ClipboardPage, a copy of the value is made and placed into the list. The mode of the new value must match that of this list. If this property is of mode Java Object List, any class of object is accepted as a value. Note that if a ClipboardProperty with a mode of Java Object is passed, it will be treated as an entry in the list, not a Java Object value.

Throws:

ReadOnlyException - this property is embedded on a Read-Only page and cannot be modified

add

void add(int aAtPosition,
         java.lang.Object aValue)

Inserts a value at the specified position in this list property. This property must have a list mode.

Parameters:

aAtPosition - Index of the new value's position (where the first position is 1)

aValue - A ClipboardProperty, String, ClipboardPage, or StringMap object to be inserted into this list property. If aValue is an embedded ClipboardProperty or a named or embedded ClipboardPage, a copy of the value is made and placed into the list. The mode of the new value must match that of this list. If this property is of mode Java Object List, any class of object is accepted as a value. Note that if a ClipboardProperty with a mode of Java Object is passed, it will be treated as an entry in the list, not a Java Object value.

Throws:

ReadOnlyException - this property is embedded on a Read-Only page and cannot be modified

size

int size()

Get the length of an atomic property or the number of elements in this list or group property.

Returns:

number of elements. If this method fails, 0 is returned.

getProperty

ClipboardProperty getProperty(java.lang.String aReference)

Provides a ClipboardProperty instance corresponding to the referenced item. If this property is a list and aReference is a numeric string, that item from the list will be returned. If this property is a group the aReference will be used as a group name. If the property is a page then aReference will be used as a property name on that page. Any other property mode fails with a WrongModeException.

Parameters:

aReference - property index or subscript

Returns:

corresponding ClipboardProperty instance

Throws:

WrongModeException - this property is not a page, list, or group

getParentPage

ClipboardPage getParentPage()

Identifies the page which contains this property.

Returns:

the containing page. If there is none (i.e., this property was removed from its page), null.

getParentProperty

ClipboardProperty getParentProperty()

Identifies the property which contains this property.

Returns:

the containing property. If there is none (i.e., this property is embedded on a top-level page), null.

getTopLevelPage

ClipboardPage getTopLevelPage()

Identifies the top-level page that contains this property.

Returns:

ClipboardPage The top-level page.

seekValue

boolean seekValue(PublicAPI aTools)

Invoke backward chaining to compute the value of this property, given the current state of the declarative expression network for the top-level page.

Parameters:

aTools - The current PublicAPI context

Returns:

boolean true if goal seek succeeded

Throws:

MissingPropertyException - Thrown if upstream input property is missing or empty and goal seek fails.

IndeterminateGoalException - Thrown if goal property doesn't exist in top-level page's class, or isn't a target property of a declarative expression.

seekValue

boolean seekValue(PublicAPI aTools,
                  boolean aAlwaysRecompute)

Invoke backward chaining to compute the value of this property, given the current state of the declarative expression network for the top-level page.

Parameters:

aTools - The current PublicAPI context

aAlwaysRecompute - true to always goal-seek even if property has a value.

Returns:

boolean true if goal seek succeeded

Throws:

MissingPropertyException - Thrown if upstream input property is missing or empty and goal seek fails.

IndeterminateGoalException - Thrown if goal property doesn't exist in top-level page's class, or isn't a target property of a declarative expression.

setEntryCode

void setEntryCode(java.lang.String aEntryCode)

Set the dictionary definition of this property. This method should not be used unless the entry code has been obtained from the dictionary. See ImmutablePropertyInfo.getEntryCode().

This method is public only to allow our generation facilities to set this value for performance reasons. Use at your own risk.

Parameters:

aEntryCode - the entry code used to set the property definition

getLocalizedText

java.lang.String getLocalizedText()

Returns the localized value of a property

Returns:

String localized value

getLocalizedText

java.lang.String getLocalizedText(java.lang.String aString)

Returns the localized value of aString, using the localization info from this property

Parameters:

aString - a String to localize

Returns:

the localized version of aString

getStandardText

java.lang.String getStandardText(java.lang.String aKey)

Returns the standard value of a property

Parameters:

aKey - String

Returns:

String standard value

getStringValue

java.lang.String getStringValue(int aIndex,
                                java.lang.String aPropertyName)

Get a string value from a property in a page list. Similar to calling this.getPageValue(aIndex).getString(aPropertyname). Especially useful when accessing values in a Lightweight Page List.

Parameters:

aIndex - one-based index of the desired element.

aPropertyName - name of the property whose value should be returned

Returns:

value of the named property

isLightweight

boolean isLightweight()

Is this a lightweight property? Lightweight properties use an efficient structure to save processing overhead, but require special methods to access their contents.

Returns:

true if it is.

getColumnNames

java.util.List getColumnNames()

Get the list of column names in this lightweight page list.

Returns:

a List of Strings where each entry is a column (property) name

Throws:

WrongModeException - if this property is not a lightweight page list

getColumnInfos

java.util.List getColumnInfos()

Get the list of ImmutablePropertyInfo instances, one for each column in this lightweight page list.

Returns:

a List of ImmutablePropertyInfo instances

Throws:

WrongModeException - if this property is not a lightweight page list

moveValue

boolean moveValue(java.lang.Object aSourceValue)

Set value of property and remove the source property from its parent. Any messages associated with this property are cleared. This method is more efficient than setValue(Object) if the source property is destined to be discarded (e.g., coming from a temporary list).

Parameters:

aSourceValue - A ClipboardProperty object whose value will be copied and used as the new value of this property. The attributes of this source property are also copied to the target property. This property and its value are guaranteed to be removed from its parent page or list, but are not guaranteed to be the actual objects embedded in this page. Use a getValue() method to retrive the new value.

Returns:

true if the value is set, false otherwise

Throws:

UnmodifiablePropertyException - if this property cannot be modified due to being Reserved or Protected

ReadOnlyException - if this property is embedded on a Read Only page and cannot be modified

isListElement

boolean isListElement()

Is this property an element in a list?

Returns:

true if it is

isGroupElement

boolean isGroupElement()

Is this property an elemeint in a group?

Returns:

true if it is

setQualifier

void setQualifier(java.lang.String aName,
                  java.lang.String aValue)

Sets a run-time qualifier value for this property. The qualifier must be listed in this property's definition (Rule-Obj-Property). The value is not validated or modified in any way. To remove a qualifier, pass a new value of null.

Parameters:

aName - name of the qualifier to set

aValue - new value of the qualifier, null if the qualifier should be removed

Throws:

PRRuntimeException - if the qualifier is not defined or if it is defined as a design-time qualifier

getQualifier

java.lang.String getQualifier(java.lang.String aName)

Gets a run-time qualifier value of this property. The qualifier must be listed in this property's definition (Rule-Obj-Property).

Parameters:

aName - name of the qualifier to get

Returns:

the value of the qualifier. null if a value has not been set.

Throws:

PRRuntimeException - if the qualifier is not defined or if it is defined as a design-time qualifier

setAsReference

void setAsReference(PRThread aThread,
                    ClipboardProperty aSourceProperty)

Set this property as a reference to another specified property. Both properties must be mode Page, and this property must be TYPE_REFERENCE

Parameters:

aThread -

aSourceProperty -

Throws:

WrongModeException

resetReferenceInformation

boolean resetReferenceInformation()

If this property is a Reference Property, reset the reference information to "unlink" it from the source property.

Returns:

boolean Did the operation succeed

getReferenceInformation

java.lang.String getReferenceInformation()

Get debug information describing this property's Reference attributes

Returns:

String

hasReference

boolean hasReference()

If this is a TYPE_REFERENCE_PAGE property, has a reference been established to another property? This method has three possible states: 1. If this property is not marked as a Reference, it returns false. 2. If this property is marked as a Reference (TYPE_REFERENCE_PAGE), but the reference has not been established yet (via the Property-Ref method), it returns false. 3. If this property is marked as a Reference, and the reference has been established via the Property-Ref method, it returns true.

Returns:

true if this is a Reference Property and Property-Ref has established a link to another property, false otherwise

getReferenceString

java.lang.String getReferenceString()

Get the fully qualified reference of the property this Reference Property points to. This method has three possible states: 1. If this property is not marked as a Reference, it returns a blank string (""). 2. If this property is marked as a Reference, but the reference has not been established yet (via the Property-Ref method), it returns a blank string (""). 3. If this property is marked as a Reference, and the reference has been established via the Property-Ref method, it returns a non-blank string naming the target property.

Returns:

Fully-qualified property reference, or "" if no reference has been established or this property is not a Reference type.

isDefinedAsReference

boolean isDefinedAsReference()

In the Rule-Obj-Property definition of this property, is the "Is Reference Property" flag enabled?

Returns:

boolean is this property defined as a Reference Property?

getGatewayPageName

java.lang.String getGatewayPageName(ClipboardPage aPage,
                                    java.lang.String aGatewayClass)

Get the fully qualified gateway page name if this property was used as a gateway to other instance's properties.

Parameters:

aPage - The page holding the gateway property itself

aGatewayClass - The gateway class of the property

Returns:

"" if this is not used as a gateway else provides a proper gateway page name