de.esoco.data.element

Class DataElementList

java.lang.Object

de.esoco.lib.property.AbstractStringProperties

de.esoco.lib.property.StringProperties

de.esoco.data.element.DataElement<java.util.List<E>>

de.esoco.data.element.ListDataElement<DataElement<?>>

de.esoco.data.element.DataElementList

All Implemented Interfaces:

de.esoco.lib.model.DataModel<DataElement<?>>, de.esoco.lib.property.HasProperties, de.esoco.lib.property.MutableProperties, java.io.Serializable, java.lang.Iterable<DataElement<?>>

Direct Known Subclasses:

EntityDataElement

public class DataElementList
extends ListDataElement<DataElement<?>>

A data element implementation that contains a hierarchical structure of data elements.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class de.esoco.data.element.DataElement

DataElement.CopyMode, DataElement.Flag

Field Summary

Fields inherited from class de.esoco.data.element.DataElement

ALLOWED_VALUES_CHANGED, ANONYMOUS_ELEMENT_PREFIX, DISPLAY_FLAGS, HIDDEN_URL, INPUT_FLAGS, INTERACTION_URL, ITEM_ALL_RESOURCE, ITEM_NEW_RESOURCE, ITEM_RESOURCE_PREFIX, PATH_SEPARATOR_CHAR, SERVER_PROPERTIES

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DataElementList() Default constructor for serialization.
	DataElementList(java.lang.String sName, java.util.Collection<? extends DataElement<?>> rElements) Creates a new instance that is initialized from a certain set of data elements.
	DataElementList(java.lang.String sName, java.lang.String sResourceId, java.util.Collection<? extends DataElement<?>> rElements, java.util.Set<DataElement.Flag> rFlags) Creates a new instance that is initialized from a certain set of data elements.
	DataElementList(java.lang.String sName, java.lang.String sResourceId, DataElement<?>... rElements) Creates a new instance with certain data elements and without a validator and flags.

Method Summary

Modifier and Type	Method and Description
void	add(java.lang.String sName, boolean bValue) Shortcut method to add a new BooleanDataElement with a certain name and value.
void	add(java.lang.String sName, java.util.Date rValue) Shortcut method to add a new DateDataElement with a certain name and Date value.
void	add(java.lang.String sName, int nValue) Shortcut method to add a new IntegerDataElement with a certain name and value.
void	add(java.lang.String sName, java.lang.String sValue) Shortcut method to add a new StringDataElement with a certain name and string value.
void	addElement(int nIndex, DataElement<?> rElement) Overridden to modify the parent reference of the argument data element.
DataElementList	copy(DataElement.CopyMode eMode, de.esoco.lib.property.PropertyName<?>... rCopyProperties) Returns a copy of this data element that contains all or a subset of it's current state.
protected void	copyValue(DataElement<java.util.List<DataElement<?>>> aCopy) Overridden to to nothing as the copying of the child data elements is handled in DataElement.copy(CopyMode, PropertyName...).
DataElement<?>	findChild(java.lang.String sName) Searches for a child data element in the full hierarchy of this instance and returns it if found.
static DataElement<?>	findDataElement(java.lang.String sName, java.util.Collection<DataElement<?>> rElements) Searches for a data element with a certain name in a collection of data elements.
boolean	getBoolean(java.lang.String sName) Returns the boolean value of a certain data element.
DataElementList	getChildList(java.lang.String sElementPath) A convenience method that casts the return value of the name-based method getElementAt(String) to a data element list.
protected java.lang.String	getChildResourceIdPrefix() Can be overridden by subclasses to return a resource id prefix for child elements.
java.util.List<DataElement<?>>	getDataElements() Returns the list of data elements in this instance.
java.util.Date	getDate(java.lang.String sName) Returns the date value of a certain data element.
DataElement<?>	getElement(java.lang.String sElementName) Returns the first element with a certain name from this list.
DataElement<?>	getElementAt(java.lang.String sElementPath) Returns a particular data element from the hierarchy of this list.
java.lang.String	getElementHierarchy(java.lang.String sIndent) Returns a formatted multi-line string that describes the data element hierarchy of this instance.
int	getInt(java.lang.String sName) Returns the integer value of a certain data element.
protected java.util.List<DataElement<?>>	getList() Returns the list of values of this data element.
java.lang.String	getString(java.lang.String sName) Returns the string value of a certain data element.
static void	init() This method should be invoked to initialize the property name constants for de-serialization.
void	markAsChanged() Overridden to also mark the child hierarchy as modified.
protected DataElementList	newInstance() Returns a new instance of the respective data element sub-type on which it is invoked.
void	removeElement(DataElement<?> rElement) Overridden to modify the parent reference of the argument data element.
boolean	replaceElement(DataElement<?> rNewElement) Replaces the first data element in this list with a new element with the same name.
void	set(java.lang.String sName, java.lang.String sValue) Shortcut method to set a StringDataElement with a certain name and string value.
void	setElement(DataElement<?> rElement) Sets an element in this instance.
java.lang.String	toDebugString(java.lang.String sIndent, boolean bIncludeProperties) Creates a string that describes this element for debugging purposes.
java.lang.String	toHierarchyString() Returns the full hierarchy of this data element list as a string.
protected void	updateValue(java.util.List<DataElement<?>> rNewElements) Updates the element value.

Methods inherited from class de.esoco.data.element.ListDataElement

addAll, addAllowedValues, addElement, clear, containsElement, getAllowedValues, getElement, getElementCount, getElementIndex, getElements, getElementValidator, getValue, getValueHashCode, hasEqualValueAs, iterator, toString

Methods inherited from class de.esoco.data.element.DataElement

checkImmutable, checkValidValue, copyAttributes, createItemName, createItemResource, createResourceId, equals, getName, getParent, getPath, getResourceId, getRoot, getSimpleName, getValidator, hashCode, isImmutable, isModified, isOptional, isSelected, isValidValue, readFrom, removeProperty, setModified, setProperty, setSelected, setStringValue, setValidator, setValue, valuesEqual, writeTo

Methods inherited from class de.esoco.lib.property.StringProperties

clearFlag, clearProperties, setFlag, setProperties, setProperty, setProperty

Methods inherited from class de.esoco.lib.property.AbstractStringProperties

convertCollection, convertMap, convertValue, ensurePropertyMapExists, findValue, getIntProperty, getProperty, getPropertyCount, getPropertyMap, getPropertyNames, hasEqualProperties, hasFlag, hasProperty, parseCollection, parseMap, parseValue, setPropertyMap

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface de.esoco.lib.property.HasProperties

getIntProperty, getProperty, getPropertyCount, getPropertyNames, hasFlag, hasProperty

Constructor Detail

DataElementList

public DataElementList(java.lang.String sName,
                       java.util.Collection<? extends DataElement<?>> rElements)

Creates a new instance that is initialized from a certain set of data elements. The contents of the collection argument will be copied into this list element but not the collection itself.

Parameters:

sName - The name of this element

rElements - A collection containing the initial elements of this list element (may be NULL)

DataElementList

public DataElementList(java.lang.String sName,
                       java.lang.String sResourceId,
                       DataElement<?>... rElements)

Creates a new instance with certain data elements and without a validator and flags.

Parameters:

sName - The name of this element

sResourceId - A resource ID or NULL for the default

rElements - The child data elements

DataElementList

public DataElementList(java.lang.String sName,
                       java.lang.String sResourceId,
                       java.util.Collection<? extends DataElement<?>> rElements,
                       java.util.Set<DataElement.Flag> rFlags)

Creates a new instance that is initialized from a certain set of data elements. The contents of the collection argument will be copied into this list element but not the collection itself.

Parameters:

sName - The name of this element

sResourceId - A resource ID or NULL for the default

rElements - A collection containing the initial elements of this list element (may be NULL)

rFlags - The optional flags for this data element

DataElementList

protected DataElementList()

Default constructor for serialization.

Method Detail

findDataElement

public static DataElement<?> findDataElement(java.lang.String sName,
                                             java.util.Collection<DataElement<?>> rElements)

Searches for a data element with a certain name in a collection of data elements. If the collection contains data element lists these will be searched recursively.

Parameters:

sName - The name of the data element

rElements - The elements to search

Returns:

The matching data element or NULL if no such element exists

init

public static void init()

This method should be invoked to initialize the property name constants for de-serialization.

add

public void add(java.lang.String sName,
                java.lang.String sValue)

Shortcut method to add a new StringDataElement with a certain name and string value. See ListDataElement.addElement(Object) for more information.

Parameters:

sName - The name of the data element to add

sValue - The value of the new data element

add

public void add(java.lang.String sName,
                java.util.Date rValue)

Shortcut method to add a new DateDataElement with a certain name and Date value.

Parameters:

sName - The name of the data element to add

rValue - The value of the new data element

add

public void add(java.lang.String sName,
                int nValue)

Shortcut method to add a new IntegerDataElement with a certain name and value.

Parameters:

sName - The name of the data element to add

nValue - The value of the new data element

add

public void add(java.lang.String sName,
                boolean bValue)

Shortcut method to add a new BooleanDataElement with a certain name and value.

Parameters:

sName - The name of the data element to add

bValue - The value of the new data element

addElement

public void addElement(int nIndex,
                       DataElement<?> rElement)

Overridden to modify the parent reference of the argument data element.

Overrides:

addElement in class ListDataElement<DataElement<?>>

Parameters:

nIndex - The position index

rElement - The element value to add

See Also:

ListDataElement.addElement(int, Object)

copy

public DataElementList copy(DataElement.CopyMode eMode,
                            de.esoco.lib.property.PropertyName<?>... rCopyProperties)

Returns a copy of this data element that contains all or a subset of it's current state. Always copied are the name and flags. Never copied is the parent reference because upon copying typically a reference to a copied parent needs to be set. The further data the copy contains depends on the copy mode:

• DataElement.CopyMode.FULL: The copy contains all data (except the parent reference).
• DataElement.CopyMode.FLAT: like DataElement.CopyMode.FULL but without sub-ordinate data elements.
• DataElement.CopyMode.PROPERTIES: The copy contains only the properties but not the element value and attributes.
• DataElement.CopyMode.PLACEHOLDER: The copy contains only the element name to serve as a placeholder.

The copy instance is created by invoking DataElement.newInstance() which has the recommendation to overwrite the return type to the concrete subtype to prevent the need for casting by the invoking code. For the same reason it is recommended that subclasses also override this method with the concrete return type and cast the result of super.copy() to that type.

Overrides:

copy in class DataElement<java.util.List<DataElement<?>>>

Parameters:

eMode - The copy mode

rCopyProperties - An optional list of properties to copy. If not provided all properties will be copied (unless the mode is DataElement.CopyMode.PLACEHOLDER)

Returns:

The copied instance

findChild

public DataElement<?> findChild(java.lang.String sName)

Searches for a child data element in the full hierarchy of this instance and returns it if found. Invokes findDataElement(String, Collection) to perform the search.

Parameters:

sName - The name of the data element to search

Returns:

The child data element with the given name or NULL for none

getBoolean

public boolean getBoolean(java.lang.String sName)

Returns the boolean value of a certain data element. The returned value will be the result of invoking Boolean.booleanValue() on the type-casted value of the data element with the given name if such exists. If not, FALSE will be returned. If the data element's value is not of type Boolean an exception will occur.

Parameters:

sName - The name of the data element to return as a boolean value

Returns:

The boolean value of the data element or FALSE if none could be found

getChildList

public DataElementList getChildList(java.lang.String sElementPath)

A convenience method that casts the return value of the name-based method getElementAt(String) to a data element list. If the type of the named element is not DataElementList or if no such element exists NULL will be returned.

Parameters:

sElementPath - The path of the element list to return

Returns:

The element list at the given path or NULL if no list with the given name exists

getDataElements

public java.util.List<DataElement<?>> getDataElements()

Returns the list of data elements in this instance. The list must not be modified by the invoking code.

Returns:

The list of data elements

getDate

public java.util.Date getDate(java.lang.String sName)

Returns the date value of a certain data element. The returned value will be the type-casted value of the data element with the given name if such exists. If not, NULL will be returned. If the data element's value is not of type Date an exception will occur.

Parameters:

sName - The name of the data element to return as a date value

Returns:

The date value of the data element or NULL if none could be found

getElement

public DataElement<?> getElement(java.lang.String sElementName)

Returns the first element with a certain name from this list.

Parameters:

sElementName - The name of the element to return

Returns:

The element or NULL if no element with the given name exists

getElementAt

public DataElement<?> getElementAt(java.lang.String sElementPath)

Returns a particular data element from the hierarchy of this list. The element path argument can either be a simple element name of a path to an element in the hierarchy of this list's sub-lists. The path separator is a forward slash as defined by DataElement.PATH_SEPARATOR_CHAR.

If the path start with a separator it is considered to be absolute with the name of this list as the first path element. Without a leading separator it must be relative to this instance, i.e. the first element in the path must be the name of a child data element of this instance. The path must never end with a separator. Examples:

• 'Test': returns the element 'Test' from this list
• '/Data/Preferences/Setting1': returns the element 'Setting1' from the sub-list 'Preferences' of this element which is called 'Data'
• 'Preferences/Setting1': returns the element 'Setting1' from the sub-list 'Preferences'
• 'Preferences': returns the sub-list named 'Preferences'

Parameters:

sElementPath - The path of the element to return

Returns:

The element with the given path or NULL if no such element exists

getElementHierarchy

public java.lang.String getElementHierarchy(java.lang.String sIndent)

Returns a formatted multi-line string that describes the data element hierarchy of this instance.

Parameters:

sIndent - The initial indent of the hierarchy (empty for none)

Returns:

The data element hierarchy string

getInt

public int getInt(java.lang.String sName)

Returns the integer value of a certain data element. The returned value will be the result of invoking Number.intValue() on the type-casted value of the data element with the given name if such exists. If not, 0 (zero) will be returned. If the data element's value is not of type Number an exception will occur.

Parameters:

sName - The name of the data element to return as an integer value

Returns:

The integer value of the data element or 0 if none could be found

getString

public java.lang.String getString(java.lang.String sName)

Returns the string value of a certain data element. The returned value will be the result of invoking Object.toString() on the value of the data element with the given name if such exists. If not, NULL will be returned.

Parameters:

sName - The name of the data element to return the string value of

Returns:

The string value of the data element or NULL if none could be found

markAsChanged

public void markAsChanged()

Overridden to also mark the child hierarchy as modified.

Overrides:

markAsChanged in class DataElement<java.util.List<DataElement<?>>>

removeElement

public void removeElement(DataElement<?> rElement)

Overridden to modify the parent reference of the argument data element.

Overrides:

removeElement in class ListDataElement<DataElement<?>>

Parameters:

rElement - The element to remove

See Also:

ListDataElement.removeElement(Object)

replaceElement

public boolean replaceElement(DataElement<?> rNewElement)

Replaces the first data element in this list with a new element with the same name.

Parameters:

rNewElement - The element to replace another with the same name

Returns:

TRUE if an element has been replaced

set

public void set(java.lang.String sName,
                java.lang.String sValue)

Shortcut method to set a StringDataElement with a certain name and string value. See setElement(DataElement) for more information.

Parameters:

sName - The name of the data element to add

sValue - The value of the new data element

setElement

public void setElement(DataElement<?> rElement)

Sets an element in this instance. If an element with the given name already exists it will be replaced. Otherwise a new element will be added to the end of the list.

Parameters:

rElement - The element to set

toDebugString

public java.lang.String toDebugString(java.lang.String sIndent,
                                      boolean bIncludeProperties)

Creates a string that describes this element for debugging purposes.

Overrides:

toDebugString in class DataElement<java.util.List<DataElement<?>>>

Parameters:

sIndent - The indentation of the returned string

bIncludeProperties - TRUE to include the properties, FALSE to omit

Returns:

The debug description

toHierarchyString

public java.lang.String toHierarchyString()

Returns the full hierarchy of this data element list as a string.

Returns:

The hierarchy string

copyValue

protected void copyValue(DataElement<java.util.List<DataElement<?>>> aCopy)

Overridden to to nothing as the copying of the child data elements is handled in DataElement.copy(CopyMode, PropertyName...).

Overrides:

copyValue in class ListDataElement<DataElement<?>>

Parameters:

aCopy - The copied data element to copy the value into

See Also:

ListDataElement.copyValue(DataElement)

getChildResourceIdPrefix

protected java.lang.String getChildResourceIdPrefix()

Can be overridden by subclasses to return a resource id prefix for child elements. This default implementation returns an empty string.

Returns:

The child resource id prefix

getList

protected java.util.List<DataElement<?>> getList()

Description copied from class: ListDataElement

Returns the list of values of this data element. Must be implemented by subclasses to return the type-specific value list.

Specified by:

getList in class ListDataElement<DataElement<?>>

Returns:

The list of values for this instance (must not be NULL)

See Also:

ListDataElement.getList()

newInstance

protected DataElementList newInstance()

Returns a new instance of the respective data element sub-type on which it is invoked. This is needed for GWT which doesn't support reflection. Used by DataElement.copy(CopyMode, PropertyName...) for cloning an instance. Implementations should overwrite the return type with their concrete type to prevent the need for casting by the invoking code.

Specified by:

newInstance in class DataElement<java.util.List<DataElement<?>>>

Returns:

The new instance

updateValue

protected void updateValue(java.util.List<DataElement<?>> rNewElements)

Updates the element value. Will be invoked by DataElement.setValue(Object) to store a new value after validation. If a subclass wants to reject certain values it should do so in the DataElement.isValidValue(Validator, Object) method. Subclasses that are always immutable should implement an assertion because if the element has been initialized correctly (validator = NULL) this method should then be reached.

Specified by:

updateValue in class DataElement<java.util.List<DataElement<?>>>

Parameters:

rNewElements - The new value for this element