org.dmd.dmc

Class DmcAttribute<VALUE>

java.lang.Object

org.dmd.dmc.DmcAttribute<VALUE>

All Implemented Interfaces:

Serializable, Cloneable, Comparable<String>

Direct Known Subclasses:

DmcHashedAttribute, DmcHierarchicObjectNameAttribute, DmcMappedAttribute, DmcObjectNameAttribute, DmcTypeActionCancelRequestREF, DmcTypeActionCancelResponseREF, DmcTypeActionRequestREF, DmcTypeActionResponseREF, DmcTypeAttributeID, DmcTypeBaseTypeEnum, DmcTypeBoolean, DmcTypeByte, DmcTypeCardinalityEnum, DmcTypeClassInfoRef, DmcTypeClassTypeEnum, DmcTypeClientCountFilterREF, DmcTypeClientCountFilterRequestREF, DmcTypeComplexTypeTestREF, DmcTypeComplexTypeWithRefs, DmcTypeCreateRequestREF, DmcTypeCreateResponseREF, DmcTypeDataTypeEnum, DmcTypeDate, DmcTypeDebugEnum, DmcTypeDeleteRequestREF, DmcTypeDeleteResponseREF, DmcTypeDenotifyRequestREF, DmcTypeDenotifyResponseREF, DmcTypeDmcAttribute, DmcTypeDmcFilter, DmcTypeDmcObject, DmcTypeDmcObjectName, DmcTypeDmgConfigREF, DmcTypeDMPEventREF, DmcTypeDMPEventTypeEnum, DmcTypeDmtMultiValuedRequiredPartPrimitive, DmcTypeDmtTestEnum, DmcTypeDmwTypeToWrapperType, DmcTypeDouble, DmcTypeEnumValue, DmcTypeExample, DmcTypeExtendedRefHSREF, DmcTypeExtendedRefMVIDXREF, DmcTypeExtendedRefMVREF, DmcTypeExtendedRefSVREF, DmcTypeExtendedRefTSREF, DmcTypeFileModeEnum, DmcTypeFilterContainer, DmcTypeFilterTypeEnum, DmcTypeFloat, DmcTypeGenerator, DmcTypeGetRequestREF, DmcTypeGetResponseREF, DmcTypeInteger, DmcTypeKeyedType, DmcTypeLabelledIntegerDataPoint, DmcTypeLoginRequestREF, DmcTypeLoginResponseREF, DmcTypeLogoutRequestREF, DmcTypeLogoutResponseREF, DmcTypeLong, DmcTypeMapZoomEnum, DmcTypeMenuElementTypeAndComment, DmcTypeModifier, DmcTypeModifyTypeEnum, DmcTypeNameContainer, DmcTypeNameContainerTestREF, DmcTypeNamedObjectREF, DmcTypeNamedObjHMREF, DmcTypeNamedObjHSREF, DmcTypeNamedObjMVIDXREF, DmcTypeNamedObjMVREF, DmcTypeNamedObjSVREF, DmcTypeNamedObjTMREF, DmcTypeNamedObjTSREF, DmcTypeNameValuePair, DmcTypeNotifyRequestREF, DmcTypeNotifyResponseREF, DmcTypeNumericRelationEnum, DmcTypeOperationalContextEnum, DmcTypeOriginalTypeEnum, DmcTypeParseTestREF, DmcTypePathAndKey, DmcTypePreAuthRequestREF, DmcTypePreAuthResponseREF, DmcTypePrimitiveHMREF, DmcTypePrimitiveHSREF, DmcTypePrimitiveMVIDXREF, DmcTypePrimitiveMVREF, DmcTypePrimitiveSVREF, DmcTypePrimitiveTMREF, DmcTypePrimitiveTSREF, DmcTypeResponseCategoryEnum, DmcTypeResponseFormatEnum, DmcTypeResponseREF, DmcTypeResponseTypeEnum, DmcTypeRuleParam, DmcTypeRuleScopeEnum, DmcTypeRuleTypeEnum, DmcTypeSchemaAndReason, DmcTypeScopeEnum, DmcTypeSetRequestREF, DmcTypeSetResponseREF, DmcTypeShort, DmcTypeString, DmcTypeTestBasicObjectFixedREF, DmcTypeTimeDoubleDataPoint, DmcTypeUnnamedObjHSREF, DmcTypeUnnamedObjMVIDXREF, DmcTypeUnnamedObjMVREF, DmcTypeUnnamedObjSVREF, DmcTypeUnnamedObjTSREF, DmcTypeUsingIndexedAttributesREF, DmcTypeUsingObjRefHMREF, DmcTypeUUIDLite, DmcTypeValue, DmcTypeValueTypeEnum, DmcTypeWrapperTypeEnum

public abstract class DmcAttribute<VALUE>
extends Object
implements Cloneable, Serializable, Comparable<String>

The DmcAttribute is an abstract base class from which all attribute values associated with Dark Matter Core Objects must be derived. The class is parameterized to allow for easy "wrapping" of existing Java types. The only caveat for the types being wrapped is that they must be marked as Serializable and they must have an empty signature default constructor; this is required to allow for use of GWT serialization.

To define a new type you need two parts, the VALUE class (which is supplied as the VALUE parameter to this class) and, by convention, a DmcType[VALUE] class that is derived from DmcAttribute. The DmcType[VALUE] class must implement four functions: typeCheck(), cloneValue(), serializeValue() and deserializeValue(). The DmcType[VALUE] class is abstract.

The remainder of the functionality required is generated as part of the Dark Matter Object (DMO) generation process. This process results in VALUE specific implementations of single-valued (SV), multi-valued(MV), mapped (MAP for HashMap and TreeMap)and set (SET for HashSet and TreeSet) to be created in your generated.types package for a particular schema. Each of these implementations is derived from your DmcType[VALUE] class and overload the appropriate methods defined in DmcAttribute.

The DmcAttribute merely provides a mechanism for constructing ID/VALUE pairs for single and multi-valued attributes. There are four primary modification interfaces on a DmcAttribute:

• set() - sets the value of a single-valued attribute
• setMVnth() - sets the nth value of an indexed, multi-valued attribute
• add() - adds a value to a multi-valued attribute
• del() - deletes a value from a multi-valued attribute

To completely remove an attribute value from an object, the DmcObject.rem() function is called.

Retrieval of values is accomplished via:

• getSV() - which returns a single value
• getMV() - which returns an Iterator over multiple values
• getMVnth() - which returns the nth value of an indexed, multi-valued attribute

The DmcAttribute and it's derivatives are generally not used directly; their functionality is hidden behind a generated DMO which provides typed interfaces to access and manipulate attribute values.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected DmcAttributeInfo	attrInfo
protected Integer	ID

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DmcAttribute() Constructs a new attribute value holder.
protected	DmcAttribute(DmcAttributeInfo ai) Constructs a new attribute value holder.

Method Summary

Modifier and Type	Method and Description
VALUE	add(Object value) Adds the specified value to a multi-valued attribute.
protected void	addModsMV(DmcTypeModifierMV mods, DmcAttribute<?> existingValue, DmcAdapterIF adapter)
protected void	addModsSV(DmcTypeModifierMV mods, DmcAttribute<?> existingValue, DmcAdapterIF adapter)
abstract DmcAttribute<VALUE>	cloneIt() This method is overridden in the auto-generated classes to create a deep clone of the attribute.
protected abstract VALUE	cloneValue(VALUE original) This method must be overridden to clone whatever value is stored in this attribute.
int	compareTo(String o) Compares the name of this attribute to the specified String for order.
boolean	contains(Object obj) If we have a multi-valued attribute, we checked to see it it contains the specified value.
boolean	containsKey(Object key) If we have a mapped attribute, we checked to see it it contains the specified key.
VALUE	del(Object v) Removes a value from a multi-valued attribute.
void	deserializeIt(DmcInputStreamIF dis) This method will deserialize this attribute from an input stream.
abstract VALUE	deserializeValue(DmcInputStreamIF dis) This method must be overridden to read a single value from the input stream.
protected String	formatValue(VALUE value) This method is called in toOIF() to format an attribute value.
protected void	formatValueAsCompactJSON(StringBuffer sb) This method may be overloaded to properly format attributes that refer directly to DmcObjects or that are object references.
protected void	formatValueAsJSON(StringBuffer sb, int padding, String indent) This method may be overloaded to properly format attributes that refer directly to DmcObjects or that are object references.
DmcAttributeInfo	getAttributeInfo()
VALUE	getByKey(Object key) This method is overloaded in DmcHashedAttribute - it returns null at this level.
Integer	getID() Returns the unique attribute ID.E
Iterator<VALUE>	getMV() Returns an Iterator over a multi-valued attribute's values.
VALUE	getMVnth(int index) A convenience function to return the nth value from a multi-valued attribute.
int	getMVSize() For a multi-valued attribute, this returns the number of values in the attribute.
String	getName()
protected abstract DmcAttribute<?>	getNew() Derived classes must return a new, empty version of themselves.
VALUE	getSV() Returns the single-valued attribute value.
boolean	hasValue() If we have an indexed, multi-valued attribute, this method will traverse all of the slots to determine if we still have any non-null values.
String	modifierFormat() Returns this attribute as just "value" with no line feeds.
void	serializeIt(DmcOutputStreamIF dos) Serializes this attribute value.
abstract void	serializeValue(DmcOutputStreamIF dos, VALUE value) This method must be overridden to serialize the specified value to the output stream.
VALUE	set(Object value) Sets the value of a single-valued attribute.
void	setAttributeInfo(DmcAttributeInfo ai) Sets the attribute info associated with this attribute.
VALUE	setMVnth(int index, Object value) For indexed, multi-valued attributes, we set the nth value as specified.
void	toOIF(StringBuffer sb) Returns this attribute in Object Instance Format (OIF) which is basically the attribute name followed by the string representation of the value of the attribute.
void	toOIF(StringBuffer sb, int padding) Returns this attribute in Object Instance Format (OIF) which is basically the attribute name followed by the string representation of the value of the attribute.
protected abstract VALUE	typeCheck(Object value) Derived classes must overload this method to determine if the value passed in conforms with their type criteria.
protected boolean	valueChangedMV(DmcAttribute<?> existingValue, DmcAdapterIF adapter)
protected boolean	valueChangedSV(DmcAttribute<?> existingValue, DmcAdapterIF adapter)

Methods inherited from class java.lang.Object

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

Field Detail

ID

protected Integer ID

attrInfo

protected transient DmcAttributeInfo attrInfo

Constructor Detail

DmcAttribute

protected DmcAttribute()

Constructs a new attribute value holder.

DmcAttribute

protected DmcAttribute(DmcAttributeInfo ai)

Constructs a new attribute value holder.

Method Detail

getAttributeInfo

public DmcAttributeInfo getAttributeInfo()

Returns:

The attribute info if it has been set.

setAttributeInfo

public void setAttributeInfo(DmcAttributeInfo ai)

Sets the attribute info associated with this attribute. You should only call this method if you know what you're doing! It's primarily used by the deserialization mechanisms.

Parameters:

ai - The attribute information.

getID

public Integer getID()

Returns the unique attribute ID.E

Returns:

The ID.

getName

public String getName()

Returns:

The name of this attribute.

compareTo

public int compareTo(String o)

Compares the name of this attribute to the specified String for order.

Specified by:

compareTo in interface Comparable<String>

typeCheck

protected abstract VALUE typeCheck(Object value)
                            throws DmcValueException

Derived classes must overload this method to determine if the value passed in conforms with their type criteria.

Parameters:

value - the value to be checked

Returns:

a value holder

Throws:

DmcValueException - if the value is incorrect

cloneValue

protected abstract VALUE cloneValue(VALUE original)

This method must be overridden to clone whatever value is stored in this attribute. The concept of clone constructors was considered, but this doesn't work for enumerated values.

Parameters:

original - the original value

Returns:

A clone of the value.

serializeValue

public abstract void serializeValue(DmcOutputStreamIF dos,
                                    VALUE value)
                             throws Exception

This method must be overridden to serialize the specified value to the output stream.

Parameters:

dos - The output stream.

value - The value to be serialized.

Throws:

Exception - if problems occur

deserializeValue

public abstract VALUE deserializeValue(DmcInputStreamIF dis)
                                throws Exception

This method must be overridden to read a single value from the input stream.

Parameters:

dis - the input stream.

Returns:

A value read from the input stream.

Throws:

Exception - if problems occur

getNew

protected abstract DmcAttribute<?> getNew()

Derived classes must return a new, empty version of themselves. This is required in order to be GWT compatible since the Class.newInstance() method IS NOT SUPPORTED.

Returns:

An instance of the appropriate DmcAttribute derivative. This mechanism is required to support the DmcTypeModifier concepts that allow you to record the changes made on an object and transmit them in modification events.

set

public VALUE set(Object value)
          throws DmcValueException

Sets the value of a single-valued attribute.

Parameters:

value - The value to be set

Returns:

the attribute value

Throws:

DmcValueException - if the value is not compatible with the underlying type.

getSV

public VALUE getSV()

Returns the single-valued attribute value.

Returns:

the attribute value

add

public VALUE add(Object value)
          throws DmcValueException

Adds the specified value to a multi-valued attribute. NOTE: multi-valued attributes DON'T allow duplicate values.

Parameters:

value - The value to be added

Returns:

the attribute value

Throws:

DmcValueException - if the value is not compatible with the underlying type.

del

public VALUE del(Object v)

Removes a value from a multi-valued attribute.

Parameters:

v - The value to be removed.

Returns:

the attribute value

getMV

public Iterator<VALUE> getMV()

Returns an Iterator over a multi-valued attribute's values.

Returns:

Iterator<VALUE>

getMVSize

public int getMVSize()

For a multi-valued attribute, this returns the number of values in the attribute. If the attribute is single-valued, 0 is returned.

Returns:

the number of values.

getMVnth

public VALUE getMVnth(int index)

A convenience function to return the nth value from a multi-valued attribute.

Parameters:

index - The value index.

Returns:

the value

setMVnth

public VALUE setMVnth(int index,
                      Object value)
               throws DmcValueException

For indexed, multi-valued attributes, we set the nth value as specified. If the value at the index is to be removed, set the value to null.

Parameters:

index - The value index.

value - The value to be set. if the value is null, that index location is nulled.

Returns:

the value

Throws:

DmcValueException

getByKey

public VALUE getByKey(Object key)

This method is overloaded in DmcHashedAttribute - it returns null at this level.

Parameters:

key - the key value

Returns:

the value associated with the specified key for HASHMAPPED or TREEMAPPED attributes.

contains

public boolean contains(Object obj)

If we have a multi-valued attribute, we checked to see it it contains the specified value.

Parameters:

obj - The object we're looking for.

Returns:

true if the object is contained by the attribute.

containsKey

public boolean containsKey(Object key)

If we have a mapped attribute, we checked to see it it contains the specified key.

Parameters:

key - The key we're looking for.

Returns:

true if the object is contained by the attribute.

hasValue

public boolean hasValue()

If we have an indexed, multi-valued attribute, this method will traverse all of the slots to determine if we still have any non-null values.

Returns:

true if there are any values an false otherwise.

cloneIt

public abstract DmcAttribute<VALUE> cloneIt()

This method is overridden in the auto-generated classes to create a deep clone of the attribute.

Returns:

a clone of the attribute

serializeIt

public void serializeIt(DmcOutputStreamIF dos)
                 throws Exception

Serializes this attribute value.

Parameters:

dos - The stream to which we're serialized.

Throws:

IOException - if IO problems occur

DmcValueException - if value problems occur

Exception

deserializeIt

public void deserializeIt(DmcInputStreamIF dis)
                   throws Exception

This method will deserialize this attribute from an input stream. This method is overridden in DmcHashedAttribute to handle hashed attributes.

Parameters:

dis - The input stream.

Throws:

Exception - if you've tried to store a non-DmcHashedAttribute derivative as HASHMAPPED or TREEMAPPED.

formatValue

protected String formatValue(VALUE value)

This method is called in toOIF() to format an attribute value. If you want a different String display format for a type of value, you can overload this in your DmcType implementation. This method is NOT called for object names.

Returns:

the formatted value

toOIF

public void toOIF(StringBuffer sb)

Returns this attribute in Object Instance Format (OIF) which is basically the attribute name followed by the string representation of the value of the attribute. For multi-valued attributes, each value is dumped on a separate line, prepended with its name.

Parameters:

sb - the string buffer to which we write

toOIF

public void toOIF(StringBuffer sb,
                  int padding)

Returns this attribute in Object Instance Format (OIF) which is basically the attribute name followed by the string representation of the value of the attribute. For multi-valued attributes, each value is dumped on a separate line, prepended with its name.

Parameters:

sb - The string buffer to which we append the attribute values

padding - The amount of padding to provide for the "left-justified" attribute name.

modifierFormat

public String modifierFormat()

Returns this attribute as just "value" with no line feeds. This is to format the attributes that are part of modifiers. Such attribute always have only one value, so this method will throw an IllegalStateException if there's more than one value in the attribute.

Returns:

the formatted value

addModsSV

protected void addModsSV(DmcTypeModifierMV mods,
                         DmcAttribute<?> existingValue,
                         DmcAdapterIF adapter)

valueChangedSV

protected boolean valueChangedSV(DmcAttribute<?> existingValue,
                                 DmcAdapterIF adapter)

addModsMV

protected void addModsMV(DmcTypeModifierMV mods,
                         DmcAttribute<?> existingValue,
                         DmcAdapterIF adapter)

valueChangedMV

protected boolean valueChangedMV(DmcAttribute<?> existingValue,
                                 DmcAdapterIF adapter)

formatValueAsJSON

protected void formatValueAsJSON(StringBuffer sb,
                                 int padding,
                                 String indent)

This method may be overloaded to properly format attributes that refer directly to DmcObjects or that are object references.

Parameters:

sb - the string buffer we write to

padding - the padding

indent - the indent

formatValueAsCompactJSON

protected void formatValueAsCompactJSON(StringBuffer sb)

This method may be overloaded to properly format attributes that refer directly to DmcObjects or that are object references.

Parameters:

sb - the string buffer we write to