com.edustructures.sifworks
Class SIFElement

java.lang.Object
  com.edustructures.sifworks.Element
      com.edustructures.sifworks.SIFElement

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

AcademicPerformanceSummary, Accommodation, AccommodationCategory, Accommodations, Action, ActivityAward, AdministratorAttendance, Advisor, AnnualItem, Approval, AssessmentGradeLevel, AssessmentHistory, AssignmentTime, AuditInfo, BackgroundCheck, BudgetAccount, CalendarDateType, Component, ContactFlags, Copyright, Counselor, CurrentCourseActivity, Customer, Demographics, DemographicsData, DwellingArrangement, ExpenseAccount, FISAmount, FISPeriod, FrequencyTime, FTAmount, GridLocation, HomeEnrollment, HRProgramType, IncidentCategory, InstructionalLevel, ItemQuantity, LanguageOfInstruction, LEAInfoData, LeastRestrictiveEnvironment, LifeCycle, LRContact, ManifestationDetermination, MarkingPeriod, MeetingTime, MostRecent, NameList, Narrative, Numeric, ParentGuardian, PartCTransitionMeetingNotHeldReason, PartCTransitionMeetingOutcome, Percentage, Period, ProgramExitReason, ProgramFundingSource, ProgramPlanType, ProgramStatus, PurchaseQuantity, Records, ReferralSource, ReportingPeriod, Requirement, ResidencyStatus, ResourceContact, ResourceEvaluations, RightsElement, SaleQuantity, SCEDCode, ScheduleInfoOverride, SchoolCourseInfoData, SchoolInfoData, ServiceFundingSource, ServiceProviderType, SIF_Application, SIF_Condition, SIF_Error, SIF_EventObject, SIF_ExtendedQuery, SIF_ExtendedQueryResults, SIF_GetAgentACL, SIF_GetMessage, SIF_GetZoneStatus, SIF_JoinOn, SIF_LogEntryHeader, SIF_Metadata, SIF_OriginalHeader, SIF_Ping, SIF_Property, SIF_SecureChannel, SIF_Select, SIF_Sleep, SIF_Vendor, SIF_Wakeup, SIFDataObject, SIFKeyedElement, SIFList, SIFMessagePayload, SIFOrderByElement, SIFSelectElement, SourceAuthor, SpanGap, StaffAssigned, StaffPersonalData, StandardHierarchyLevel, StudentAttendance, StudentContactsSummary, StudentGradeLevel, StudentParticipationData, StudentPersonalData, StudentProgramAccommodation, StudentProgramType, TeacherAttendance, Term, TermPerformance, Transaction, TransferPoint, TransStudent, WhenServiceProvided

public abstract class SIFElement
extends Element

The abstract base class for all SIF Elements.

Each object type and complex field element defined in the SIF Specification is encapsulated by a subclass of SIFElement. Objects include <StudentPersonal>, <StaffPersonal>, <BusInfo>, etc. while complex field elements include <Address>, <OtherId>, <PhoneNumber> and so on. Simple fields which have only a string value but which have no child elements are encapsulated by the SimpleField class instead of by SIFElement. An example of such a field is the <FirstName> child of the <Name> element.

SIFElements may have a single parent and zero or more children. Complex fields are always represented as child objects. The addChild, getChildren, removeChild, countChildren, and removeAllChildren methods are provided to manipulate the child list. Simple fields are stored in a dictionary keyed by the field's ElementDef constant as defined in the SIFDTD class. The value of a simple field is encapsulated by a SimpleField object, which stores not only the current string value of the field but also its change state and a reference to its ElementDef.

Comparing SIFElement Graphs

Agent developers do not typically work with SIFElement objects directly. The compareGraphTo method is one exception. Agents can use this method to compare the contents of two SIFElements in order to determine which elements and attributes are different. For an example of how this method can be used to assist in SIF_Event reporting, refer to the SchoolInfoProvider ADK Example program. Similarly, the SIFDiff example program demonstrates using the compareGraphTo method to display the differences between two SIF Data Objects read from disk.

SIFVersion

The abstract getSIFVersion method returns the SIFVersion that is currently in effect for this object. This is often used to determine the element tag name and sequence number when rendering XML because these may change from one version of SIF to the next. However, the SIFElement class does not itself keep track of version; it is up to the derived class to do so. Both SIFDataObject and SIFMessagePayload store the SIF version associated with their objects. By working up the object ancestry, it is possible to determine the SIFVersion currently associated with a SIFElement. The effectiveSIFVersion method performs this task.

Version:

1.0

See Also:

Serialized Form

Field Summary

Fields inherited from class com.edustructures.sifworks.Element

CURRENT_SERIALIZE_VERSION

Constructor Summary

SIFElement(ElementDef def)
Constructs a SIFElement

Method Summary

void	addChild(ElementDef id, SIFElement element) Adds a child SIFElement
SIFElement	addChild(SIFElement element) Adds a child SIFElement.
java.lang.Object	clone()
Element[][]	compareGraphTo(SIFElement target) Compares all child elements and attributes of this Element with that of another Element.
static SIFElement	create(SIFElement parent, ElementDef id) Creates an instance of a SIFElement from its ID
SIFVersion	effectiveSIFVersion() Gets the SIFVersion effective for this element by searching the ancestry until a valid SIFVersion is returned by one of the parent objects.
SIFElement	getChild(ElementDef id) Gets the child object with the matching ElementDef
SIFElement	getChild(ElementDef id, java.lang.String key) Gets the child object with the matching ElementDef and key
SIFElement	getChild(ElementDef id, java.lang.String[] compKey) Gets a child object identified by its ElementDef and composite key
SIFElement	getChild(java.lang.String tag) Gets the child object with the matching ElementDef
SIFElement	getChild(java.lang.String name, java.lang.String key) Gets the child object with the matching element name and key
int	getChildCount() Returns the number of children
java.util.List<SIFElement>	getChildList() Gets all child objects as an unmodifiable list
java.util.List<SIFElement>	getChildList(ElementDef id) Gets all child objects with a matching ElementDef
java.util.List<SIFElement>	getChildList(java.lang.String name) Gets all child objects with a matching version-independent element name
SIFElement[]	getChildren() Gets all child objects
SIFElement[]	getChildren(ElementDef id) Gets all child objects with a matching ElementDef
java.util.List<Element>	getContent() Gets an ordered list of all child elements and fields that are in a changed state and do not have a null value.
java.util.List<Element>	getContent(SIFVersion version) Gets an ordered list of all child elements and fields that are in a changed state and do not have a null value.
SimpleField	getField(ElementDef id) Gets a field's value and sequence number
SimpleField	getField(java.lang.String name) Gets a field's value and sequence number
int	getFieldCount() Gets the number of fields for this object
java.util.List<SimpleField>	getFields() Gets all fields for this object.
java.lang.String	getFieldValue(ElementDef id) Gets a field's value as a String
java.lang.String	getKey() Gets the key of this object.
SIFSimpleType	getSIFValue() Gets the SIF strongly-typed value of this element
SIFVersion	getSIFVersion() Gets the SIFVersion associated with this element, if applicable.
java.lang.String	getTextValue() Gets the text value of this element if applicable.
java.lang.String	getXmlId() Returns the unique identifier that was set to the setXmlId(String) method.
boolean	hasTextValue() Does this element have a text value?
boolean	removeChild(ElementDef id) Removes a child object identified by its ElementDef
boolean	removeChild(ElementDef id, java.lang.String key) Removes a child object identified by its ElementDef and key
java.lang.Boolean	removeChild(ElementDef id, java.lang.String[] complexKey) Removes a child object identified by its ElementDef and complex key This method removes only the first element it finds that matches the ElementDef and key.
java.lang.Boolean	removeChild(SIFElement child) Removes a child object
void	restoreImplementationDef(Element candidate) Return the actual ElementRef of the child.
void	setChanged(boolean changed) Sets this element and each of its children to the specified changed state.
void	setChildren(ElementDef id, SIFElement[] children) Adds the specified children as an array to the SIFElement object.
void	setEmpty(boolean empty) Sets this element and each of its children to the specified empty state.
SimpleField	setField(ElementDef id, int value) Deprecated. Please call setField(ElementDef, SIFSimpleType)
SimpleField	setField(ElementDef id, SIFSimpleType value) Sets a field's value
SimpleField	setField(ElementDef id, java.lang.String value) Sets a field's value
void	setField(SimpleField field) Sets the value of an attribute or simple text element on this SIFElement
void	setSIFValue(SIFSimpleType value) Sets the SIF strongly-typed value of this element
void	setSIFVersion(SIFVersion version) Sets the SIFVersion associated with this element, if applicable.
void	setTextValue(java.lang.String value) Sets the text value of this element if applicable.
void	setXmlId(java.lang.String id) Sets an identifier that can be used to uniquely identify this SIFElement instance to an application.
java.lang.String	tag() Gets the tag name for this element.

Methods inherited from class com.edustructures.sifworks.Element

compareTo, getElementDef, getParent, getRoot, isChanged, isDoNotEncode, isEmpty, setChanged, setDoNotEncode, setElementDef, setEmpty, setParent, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SIFElement

public SIFElement(ElementDef def)

Constructs a SIFElement

Parameters:

def - The ElementDef constant from the SIFDTD class that provides metadata for this element

Method Detail

getSIFVersion

public SIFVersion getSIFVersion()

Gets the SIFVersion associated with this element, if applicable.

The base class implementation of this method always returns null.

Returns:

A SIFVersion object that identifies the version of SIF that should be used to render this object (or that was used to parse it). Not all implementation classes store a SIFVersion, so null may be returned.

setSIFVersion

public void setSIFVersion(SIFVersion version)

Sets the SIFVersion associated with this element, if applicable.

The base class implementation of this method does nothing.

Parameters:

version - A SIFVersion object that identifies the version of SIF that should be used to render this object (or that was used to parse it). Not all implementation classes store a SIFVersion, so calling this method may have no affect.

effectiveSIFVersion

public SIFVersion effectiveSIFVersion()

Gets the SIFVersion effective for this element by searching the ancestry until a valid SIFVersion is returned by one of the parent objects.

Returns:

A SIFVersion object that identifies the version of SIF that should be used to render this object (or that was used to parse it).

tag

public java.lang.String tag()

Gets the tag name for this element. The effective version of SIF is used to determine the exact tag name since tag names may change from one version of SIF to the next.

Note: In order for this method to return the proper tag name, it must know the version of SIF in use. The version is obtained by visiting the element ancestry and calling getSIFVersion on each parent until a non-null value is returned. Thus, this is a relatively expensive operation and should only be called when the SIFVersion is not known. If the SIFVersion is known, calling getElementDef().tag(version) directly is preferred.

Returns:

The element tag name that should be used when rendering XML

See Also:

effectiveSIFVersion()

getXmlId

public java.lang.String getXmlId()

Returns the unique identifier that was set to the setXmlId(String) method.

This value is not used by the ADK and is reserved for use by the application.

Returns:

a string value that uniquely identifies this object to the application.

setXmlId

public void setXmlId(java.lang.String id)

Sets an identifier that can be used to uniquely identify this SIFElement instance to an application.

This property is not used by the ADK and is reserved for use by the application.

Parameters:

id - a String value that uniquely identifies this object to the application that is using it.

getKey

public java.lang.String getKey()

Gets the key of this object. All SIFElements must be able to return a unique key that distinguishes the object from its peers in a child list. For SIF, the key is almost always the "RefId" field of an object. In some cases more than one attribute is combined to form a key; in this case the convention "attr1.attr2" should be used, where the key values are listed in sequential order.

Returns:

The key value of this object

getChild

public SIFElement getChild(java.lang.String name,
                           java.lang.String key)

Gets the child object with the matching element name and key

Parameters:

name - The version-independent element name. Note the element name is not necessarily the same as the element tag, which is version dependent.

key - The key to match

Returns:

The SIFElement that has a matching element name and key, or null if no matches found

getChild

public SIFElement getChild(ElementDef id,
                           java.lang.String[] compKey)

Gets a child object identified by its ElementDef and composite key

Parameters:

id - A ElementDef defined by the SIFDTD class to uniquely identify this field

compKey - The key values in sequential order

Returns:

The child that was requested, or null

addChild

public void addChild(ElementDef id,
                     SIFElement element)

Adds a child SIFElement

Parameters:

id - The ElementDef for the child

element - The child element

Throws:

java.lang.IllegalArgumentException - Thrown if the child being added is already a child of a different parent

addChild

public SIFElement addChild(SIFElement element)

Adds a child SIFElement.

Parameters:

element -

Returns:

The SIFElement that was actually added as a child to this object.

Throws:

java.lang.IllegalArgumentException - Thrown if the child being added is already a child of a different parent

restoreImplementationDef

public void restoreImplementationDef(Element candidate)

Return the actual ElementRef of the child. For example, if this were a StudentPersonal and the child were a Name, we would reassign its ElementRef to be ADK.DTD.STUDENTPERSONAL_NAME

We also need to redefine the ElementRef to be ADK.DTD.STUDENTPERSONAL_NAME. This will allow it to be written in the proper sequence in versions of SIF in which it is collapsed

Parameters:

candidate -

setChildren

public void setChildren(ElementDef id,
                        SIFElement[] children)

Adds the specified children as an array to the SIFElement object.

All existing children that are defined as the same type as the ElementDef parameter are removed and replaced with this list. Calling this method with the Element[] parameter set to null removes all children.

Parameters:

id - The type of element that is being added

children - The elements that are being added, all of which are defined with the same ElementDef

Throws:

java.lang.IllegalArgumentException - thrown if either parameter is null

removeChild

public java.lang.Boolean removeChild(SIFElement child)

Removes a child object

Parameters:

child - The child element

Returns:

True if the child was removed from this element, otherwise false

removeChild

public boolean removeChild(ElementDef id,
                           java.lang.String key)

Removes a child object identified by its ElementDef and key

This method removes only the first element it finds that matches the ElementDef and key.

Parameters:

id - The ElementDef constant that identifies the type of child to remove

key - The element key value that identifies the specific child to remove

Returns:

True if the child was removed from this element, otherwise false

removeChild

public boolean removeChild(ElementDef id)

Removes a child object identified by its ElementDef

This method removes only the first element it finds that matches the ElementDef

Parameters:

id - The ElementDef constant that identifies the type of child to remove

Returns:

True if the child was removed from this element, otherwise false

removeChild

public java.lang.Boolean removeChild(ElementDef id,
                                     java.lang.String[] complexKey)

Removes a child object identified by its ElementDef and complex key This method removes only the first element it finds that matches the ElementDef and key.

Parameters:

id - The ElementDef constant that identifies the type of child to remove

complexKey - The complex key values that, taken together, identify the specific child to remove

Returns:

True if the child was removed from this element, otherwise false

getChildren

public SIFElement[] getChildren()

Gets all child objects

Returns:

An array of all SIFElement children

getChildList

public java.util.List<SIFElement> getChildList()

Gets all child objects as an unmodifiable list

Returns:

An array of all SIFElement children

getChildren

public SIFElement[] getChildren(ElementDef id)

Gets all child objects with a matching ElementDef

Parameters:

id - An ElementDef defined by the SIFDTD class to uniquely identify this field

Returns:

An unsorted array of the SIFElements that have a matching ElementDef

getChildList

public java.util.List<SIFElement> getChildList(ElementDef id)

Gets all child objects with a matching ElementDef

Parameters:

id - An ElementDef defined by the SIFDTD class to uniquely identify this field

Returns:

A Vector of the SIFElements that have a matching ElementDef

getChildList

public java.util.List<SIFElement> getChildList(java.lang.String name)

Gets all child objects with a matching version-independent element name

Parameters:

name - The version-independent name of an element. Note the name is not necessarily the same as the element tag

Returns:

A Vector of the SIFElements that have a matching element name

getChild

public SIFElement getChild(ElementDef id)

Gets the child object with the matching ElementDef

Parameters:

id - A ElementDef defined by the SIFDTD class to uniquely identify this field

Returns:

The SIFElement that has a matching ElementDef, or null if none found

getChild

public SIFElement getChild(ElementDef id,
                           java.lang.String key)

Gets the child object with the matching ElementDef and key

Parameters:

id - A ElementDef defined by the SIFDTD class to uniquely identify this field

key - The key to match

Returns:

The SIFElement that has a matching ElementDef and key, or null if no matches found

getChild

public SIFElement getChild(java.lang.String tag)

Gets the child object with the matching ElementDef

Parameters:

tag - The SIF 2.0 XML Tag name of the child

Returns:

The SIFElement that has a matching ElementDef, or null if none found

getChildCount

public int getChildCount()

Returns the number of children

Returns:

The count of all children

setTextValue

public void setTextValue(java.lang.String value)

Sets the text value of this element if applicable. The text value will be parsed into the native datatype of the the element.

The formatter used for parsing by default is the SIF 1.x formatter, which means this value must be able to be parsed using SIF 1.x formatting rules. To change the format used for Text values on elements, set the ADK.setTextFormatter(SIFFormatter) property

Specified by:

setTextValue in class Element

Parameters:

value - The text value of this element (e.g. <element>text<element>)

Throws:

java.lang.NumberFormatException - if the value being set cannot be parsed into the datatype being stored for this field

setSIFValue

public void setSIFValue(SIFSimpleType value)

Sets the SIF strongly-typed value of this element

Specified by:

setSIFValue in class Element

Parameters:

value - The value of this element as a SIFSimpleType

getSIFValue

public SIFSimpleType getSIFValue()

Gets the SIF strongly-typed value of this element

Specified by:

getSIFValue in class Element

Returns:

The value of this element as a SIFSimpleType

getTextValue

public java.lang.String getTextValue()

Gets the text value of this element if applicable. The default format of the text value is the SIF 1.x format

To change the format used for Text values on elements, set the ADK.setTextFormatter(SIFFormatter) property

Specified by:

getTextValue in class Element

Returns:

The text value of this element (e.g. <element>text</element>)

hasTextValue

public boolean hasTextValue()

Does this element have a text value?

Returns:

true if this element has a text value (e.g. <element>text</element>)

getField

public SimpleField getField(ElementDef id)

Gets a field's value and sequence number

Parameters:

id - The field's ElementDef object defined by the SIFDTD class.

Returns:

A SimpleField object containing the field's value and sequence number, or null if the field has no value

See Also:

getFieldValue(com.edustructures.sifworks.ElementDef), getField(String)

getField

public SimpleField getField(java.lang.String name)

Gets a field's value and sequence number

Parameters:

name - The name of the field's ElementDef object defined by the SIFDTD class.

Returns:

A SimpleField object containing the field's value and sequence number, or null if the field has no value

See Also:

getFieldValue(com.edustructures.sifworks.ElementDef), getField(ElementDef)

getFieldValue

public java.lang.String getFieldValue(ElementDef id)

Gets a field's value as a String

Parameters:

id - The field's ElementDef object defined by the SIFDTD class.

Returns:

The current value of the field as a String, or null if the field has no value

See Also:

getField(ElementDef)

setField

public SimpleField setField(ElementDef id,
                            int value)

Deprecated. Please call setField(ElementDef, SIFSimpleType)

Sets an integer field's value

Parameters:

id - The field definition object

value - The value to assign to the field

Returns:

The internal field object, returned as a convenience so the caller can mark the field as dirty or empty by calling its setDirty and setEmpty methods.

setField

public SimpleField setField(ElementDef id,
                            SIFSimpleType value)

Sets a field's value

Parameters:

id - The field definition object

value - The value to assign to the field

Returns:

The internal field object, returned as a convenience so the caller can mark the field as dirty or empty by calling its setDirty and setEmpty methods.

setField

public SimpleField setField(ElementDef id,
                            java.lang.String value)

Sets a field's value

Parameters:

id - The field definition object

value - The value to assign to the field

Returns:

The internal field object, returned as a convenience so the caller can mark the field as dirty or empty by calling its setDirty and setEmpty methods.

setField

public void setField(SimpleField field)

Sets the value of an attribute or simple text element on this SIFElement

Parameters:

field -

getFields

public java.util.List<SimpleField> getFields()

Gets all fields for this object. The returned list will be a copy of the underlying list of fields

Returns:

An array of unsorted SimpleField objects

getFieldCount

public int getFieldCount()

Gets the number of fields for this object

Returns:

The number of fields that are currently set on this object

getContent

public java.util.List<Element> getContent()

Gets an ordered list of all child elements and fields that are in a changed state and do not have a null value. Attributes are not included. Elements are ordered by sequence number according to the version of SIF effective for this object.

Returns:

An Element array comprised of all child SIFElement and SimpleField objects ordered according to sequence number. An empty array is returned if there are no child SIFElements or fields (e.g. if this SIFElement has a text value as its content.)

See Also:

effectiveSIFVersion()

getContent

public java.util.List<Element> getContent(SIFVersion version)

Gets an ordered list of all child elements and fields that are in a changed state and do not have a null value. Attributes are not included. Elements are ordered by sequence number according to the specified version of SIF.

Parameters:

version - The version of SIF to use when ordering the elements.

Returns:

An Element array comprised of all child SIFElement and SimpleField objects ordered according to sequence number. An empty array is returned if there are no child SIFElements or fields (e.g. if this SIFElement has a text value as its content.)

setEmpty

public void setEmpty(boolean empty)

Sets this element and each of its children to the specified empty state. An object in the empty state will be written to an XML stream as an empty element with no children.

Overrides:

setEmpty in class Element

Parameters:

empty - true to set the empty state, false to clear it

setChanged

public void setChanged(boolean changed)

Sets this element and each of its children to the specified changed state. An object in the changed state will be written to the XML stream when a SIF message is rendered; objects that are not changed will be excluded.

Overrides:

setChanged in class Element

Parameters:

changed - true to set the changed state, false to clear it

compareGraphTo

public Element[][] compareGraphTo(SIFElement target)

Compares all child elements and attributes of this Element with that of another Element. Any attributes or elements of the target that have a different text value from the corresponding attribute or element in this object, or that appear in one graph but not in the other, are returned in an array. Repeatable elements are considered the same object only if their keys match.

The comparision is exclusive of the source and target objects; that is, their text values are not included in the comparision. This method is typically called on top-level SIF Data Objects such as StudentPersonal, LibraryPatronStatus, CircTx, BusInfo, etc.

The result of the comparision is returned as a dual-dimensioned array, where the first element in the array represents the source object and the second element represents the target object. Each of these arrays will contain the same number of entries. Within each array, each slot consists of a SIFElement or SimpleField object. In the ADK, the SIFElement class encapsulates complex elements such as Name, PhoneNumber, and Demographics while the SimpleField class encapsulates elements with no children such as Name/FirstName and Name/LastName, or attributes such as StudentPersonal/@RefId. If a given element or attribute appears in one graph but not in the other, its slot in the array will contain a null value.

For example, the arrays returned by this method might consist of the following:

Array[0][0..5]	Array[1][0..5]
@RefId='AB123...'	@RefId='CCD91...'
<LastName>Johnson</LastName>	<LastName>Johnsen</LastName>
<OtherId Type='06'>1004</OtherId>	null
<OtherId Type='ZZ'>SCHOOL:997</OtherId>	null
null	<OtherId Type='ZZ'>BARCODE:P12345</OtherId>

In this example, the RefId attribute (a SimpleField instance) has a different value in the source than in the target, as does the LastName element (a SIFElement instance). Two OtherId elements of type '06' and 'ZZ' appeared in the source but not in the target, so they are included in Array[0][2] and Array[0][3] but have a corresponding null value in Array[1][2] and Array[1][3]. Finally, one OtherId element of type 'ZZ' appeared in the target but not in the source, so it appears in Array[1][5] but has a corresponding null value in Array[0][5].

For examples of how this method is used, please consult the SIFDiff and SchoolInfoProvider ADK Example agents.

Parameters:

target - The Element to be compared

Returns:

An dual-dimensioned array of Elements constituting the differences between this Element and the comparision Element. The size of these arrays will always be equals. If there are no elements in either array, this Element and the comparision Element have identical content.

Throws:

java.lang.IllegalArgumentException - is thrown if this Element and the target are not of the same type; that is, they do not have the same ElementDef value. For example, trying to compare a SIFDTD.STUDENTPERSONAL element with a SIFDTD.BUSINFO element will result in an exception.

create

public static SIFElement create(SIFElement parent,
                                ElementDef id)
                         throws ADKSchemaException

Creates an instance of a SIFElement from its ID

Parameters:

id - The metadata element that identifies

parent - The parent Metadata element

Returns:

The newly-created child

Throws:

ADKSchemaException

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException