com.edustructures.sifworks
Class SIFDataObject

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

AccountingPeriod, Activity, ActivityProvider, AggregateCharacteristicInfo, AggregateStatisticFact, AggregateStatisticInfo, Assessment, AssessmentAdministration, AssessmentForm, AssessmentPackage, AssessmentRegistration, AssessmentSubTest, Assignment, AttendanceCodeInfo, Authentication, Billing, BusEquipment, BusInfo, BusPositionInfo, BusRouteDetail, BusRouteInfo, BusStopInfo, CalendarDate, CalendarSummary, CurriculumStructure, DisciplineIncident, EmployeeAssignment, EmployeeContract, EmployeeCredential, EmployeeCredit, EmployeePersonal, EmployeePicture, EmployeeRecertification, EmployeeWage, EmploymentRecord, FinancialAccount, FinancialAccountAccountingPeriodLocationInfo, FinancialAnnual, FinancialBudget, FinancialClass, FinancialIncomeStatement, FinancialTransaction, FiscalYear, FoodserviceItem, FoodserviceItemPortion, FoodserviceItemSales, FoodserviceItemUnit, FoodserviceMealPrices, FoodserviceMenuPlan, FoodserviceMilkSales, FoodservicePurchaseTransaction, FoodserviceReimbursementRates, FoodserviceSales, FoodserviceStaffEnrollmentCount, FoodserviceStaffMealCounts, FoodserviceStudentEnrollmentCount, FoodserviceStudentMealCounts, FoodserviceTransaction, FoodserviceTransactionDetails, FoodserviceTransactionPayMethod, GradingAssignment, GradingAssignmentScore, GradingCategory, LEAInfo, LearningResource, LearningStandardDocument, LearningStandardItem, Lesson, LibraryPatronStatus, LocationInfo, MarkInfo, MarkValueInfo, OfficialStudentPeriodAttendance, Payment, ProfessionalDevelopmentActivities, Purchasing, ReportAuthorityInfo, ReportManifest, ReportPackage, RoomInfo, RoomType, SchoolCourseInfo, SchoolInfo, SectionInfo, SectionMarkInfo, SIF_AgentACL, SIF_LogEntry, SIF_ReportObject, SIF_ZoneStatus, SIFDataObjectXML, StaffAssignment, StaffMeal, StaffPersonal, StudentAcademicRecord, StudentAttendanceSummary, StudentContact, StudentDailyAttendance, StudentDemographicRecord, StudentLocator, StudentMeal, StudentParticipation, StudentPeriodAttendance, StudentPersonal, StudentPicture, StudentPlacement, StudentRecordExchange, StudentRecordPackage, StudentResponseSet, StudentSchoolEnrollment, StudentScoreSet, StudentSectionEnrollment, StudentSectionMarks, StudentSnapshot, StudentSpecialEducationRecord, StudentTransportInfo, TermInfo, TestAccommodation, TimeWorked, VendorInfo, W4

public abstract class SIFDataObject
extends SIFElement

The abstract base class for all root-level SIF Data Object classes. SIFDataObject encapsulates top-level data objects defined by SIF Working Groups, including <StudentPersonal>, <LibraryPatronStatus>, <BusInfo>, and so on.

Setting Elements & Attributes of a SIF Data Object

There are two general approaches to getting and setting the element/attribute values of a SIFDataObject. First, you can call the getXxx and setXxx methods of the subclass to manipulate the elements and attributes in an object-oriented fashion. For example, to assign a first and last name to a StudentPersonal object, create a Name object and attach it to the StudentPersonal with the setName method:

// Build a StudentPersonal object
StudentPersonal sp = new StudentPersonal();
sp.setRefId( ADK.makeGUID() );
sp.setName( new Name( "Davis", "Alan" ) );


The second approach to getting and setting element/attribute values is to call the setElementOrAttribute and getElementOrAttribute methods, which accept an XPath-like query string that identifies a specific SIF element or attribute relative to the SIFDataObject. (See also the Mappings class for a higher-level mechanism that performs much of the work involved in dynamically mapping application fields to SIF elements and attributes).

// Build a StudentPersonal object
StudentPersonal sp = new StudentPersonal();
sp.setRefId( ADK.makeGUID() );
sp.setElementOrAttribute( "Name[@Type='02']/LastName", "Davis", null );
sp.setElementOrAttribute( "Name[@Type='02']/FirstName", "Brian", null );


XPath-like query strings can include substitution tokens and can even call static Java methods. For example, the following uses name/value pairs defined in a Map to select the first and last name. The static capitalize method of the "MyFunctions" class is called to capitalize the last name:

// Prepare a table with field values
HashMap values = new HashMap();
values.put( "LASTNAME", "Davis" );
values.put( "FIRSTNAME", "Brian" );

// Build a StudentPersonal object
StudentPersonal sp = new StudentPersonal();
sp.setRefId( ADK.makeGUID() );
sp.setElementOrAttribute( "Name[@Type='02']/LastName=@MyFunctions.capitalize( $(LASTNAME) )", null, values );
sp.setElementOrAttribute( "Name[@Type='02']/FirstName=$(FIRSTNAME)", null, values );


Object Type

The getObjectType method returns the an ElementDef constant from the SIFDTD class that identifies the SIF Data Object. The the getObjectTag convenience method returns the element tag name of the object for the version of SIF associated with the instance. For example,

// Lookup a Topic instance
SIFDataObject data = new SIFDataObject( ADK.DTD().STUDENTPERSONAL );
TopicFactory factory = myAgent.getTopicFactory();
Topic t = factory.getInstance( data.getObjectType() );


SIF Version

Each SIFDataObject is associated with a SIFVersion instance. The version is used by the SIFWriter class when rendering the object as XML. By default, it is assumed to be the version of SIF in effect for this agent; that is, the value passed to the ADK.initialize method. However, to support mixed environments where an agent may send and receive objects using different versions of SIF, the version may be changed by the ADK during message processing:

• When constructing a SIFDataObject instance from parsed XML content, the SIFParser class sets its SIFVersion to the version identified by the xmlns attribute of the <SIF_Message> envelope.
  
  
• The version may be changed by the ADK prior to rendering a SIFDataObject as XML. For example, when your agent responds to a <SIF_Request> message that specifically identifies a version to use for the results, the ADK will change the version of the SIFDataObject when generating <SIF_Response> messages. Once messages have been generated, it restores the SIFVersion to its original setting.
  
  
• An agent may manually change the SIFVersion associated with a SIFDataObject by calling the setSIFVersion method.

Version:

ADK 1.0

See Also:

Serialized Form

Field Summary

Fields inherited from class com.edustructures.sifworks.Element

CURRENT_SERIALIZE_VERSION

Constructor Summary

SIFDataObject(SIFVersion version, ElementDef def)
Constructs a SIFDataObject

Method Summary

void	addSIFExtendedElement(java.lang.String name, java.lang.String value) Sets a SIF_ExtendedElement.
java.lang.Object	clone()
Element	getElementOrAttribute(java.lang.String xpath) Gets an element or attribute value identified by an XPath-like query string.
java.lang.String	getObjectTag() Gets the element tag name of this object
ElementDef	getObjectType() Gets the ElementDef that identifies this SIF Data Object type
java.lang.String	getRefId() Gets this object's RefId.
SIF_ExtendedElement	getSIFExtendedElement(java.lang.String name) Gets the SIF_ExtendedElement with the specified Name attribute.
SIF_ExtendedElement[]	getSIFExtendedElements() Gets all SIF_ExtendedElements/SIF_ExtendedElement children of this object.
SIF_ExtendedElements	getSIFExtendedElementsContainer() Gets the SIF_ExtendedElements container in which all child SIF_ExtendedElement elements are placed by the addSIFExtendedElement(String, String) method.
SIF_Metadata	getSIFMetadata() Gets the SIF_Metadata for this object.
SIFVersion	getSIFVersion() Gets the version of SIF that should be used to render this SIFDataObject and its child elements
void	setElementOrAttribute(java.lang.String xpath, java.lang.String value) Sets an element or attribute value
void	setElementOrAttribute(java.lang.String xpath, java.lang.String value, FieldAdaptor adaptor) Sets an element or attribute value identified by an XPath-like query string.
void	setElementOrAttribute(java.lang.String xpath, java.lang.String value, ValueBuilder valueBuilder) Sets an element or attribute value identified by an XPath-like query string.
void	setSIFExtendedElements(SIF_ExtendedElement[] elements) Sets an array of SIF_ExtendedElement objects.
void	setSIFExtendedElementsContainer(SIF_ExtendedElements container) Sets the SIF_ExtendedElements container for this object.
void	setSIFMetadata(SIF_Metadata metadata) Sets the SIF_Metadata for this object.
void	setSIFVersion(SIFVersion version) Changes the version of SIF that should be used to render this SIFDataObject and its children.
java.lang.String	toXML() Returns the XML representation of this SIF Data Object

Methods inherited from class com.edustructures.sifworks.SIFElement

addChild, addChild, compareGraphTo, create, effectiveSIFVersion, getChild, getChild, getChild, getChild, getChild, getChildCount, getChildList, getChildList, getChildList, getChildren, getChildren, getContent, getContent, getField, getField, getFieldCount, getFields, getFieldValue, getKey, getSIFValue, getTextValue, getXmlId, hasTextValue, removeChild, removeChild, removeChild, removeChild, restoreImplementationDef, setChanged, setChildren, setEmpty, setField, setField, setField, setField, setSIFValue, setTextValue, setXmlId, tag

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

SIFDataObject

public SIFDataObject(SIFVersion version,
                     ElementDef def)

Constructs a SIFDataObject

Parameters:

version - The version of SIF that should be used to render this SIFDataObject and its child elements. If this SIFDataObject is the result of parsing a SIF message, this is the version of SIF identified by the message envelope.

def - The ElementDef that provides metadata for this element

Method Detail

getRefId

public java.lang.String getRefId()

Gets this object's RefId.

Most SIF Data Object elements define a RefId value to uniquely identify the object. However, some objects such as SIF_ZoneStatus and StudentMeal do not have a RefId. For these, a blank string will be returned.

Returns:

The value of this object's RefId element

getObjectType

public ElementDef getObjectType()

Gets the ElementDef that identifies this SIF Data Object type

Returns:

An ElementDef constant defined by the SIFDTD class

getObjectTag

public java.lang.String getObjectTag()

Gets the element tag name of this object

Returns:

The element tag for the version of SIF associated with the object

getSIFVersion

public SIFVersion getSIFVersion()

Gets the version of SIF that should be used to render this SIFDataObject and its child elements

Overrides:

getSIFVersion in class SIFElement

Returns:

A SIFVersion

setSIFVersion

public void setSIFVersion(SIFVersion version)

Changes the version of SIF that should be used to render this SIFDataObject and its children. The calling thread may change the way a SIFDataObject is rendered by calling this method. It is recommended the version be restored to its original value after rendering is completed.

Overrides:

setSIFVersion in class SIFElement

Parameters:

version - The version of SIF that should be used

setElementOrAttribute

public void setElementOrAttribute(java.lang.String xpath,
                                  java.lang.String value)
                           throws ADKSchemaException

Sets an element or attribute value

Parameters:

xpath - An XPath-like query string that identifies identifies the element or attribute to set. The string must reference elements and attributes by their version-independent names.

value - The value of the element or attribute

Throws:

ADKSchemaException - IF the xpath is not valid

setElementOrAttribute

public void setElementOrAttribute(java.lang.String xpath,
                                  java.lang.String value,
                                  FieldAdaptor adaptor)
                           throws ADKSchemaException

Sets an element or attribute value identified by an XPath-like query string.

Parameters:

xpath - An XPath-like query string that identifies the element or attribute to set. The string must reference elements and attributes by their version-independent names.

value - The value to assign to the element or attribute if the query string does not set a value; may be null

adaptor - A data source may be used for variable substitutions within the query string

Throws:

ADKSchemaException - If the xpath is not valid

setElementOrAttribute

public void setElementOrAttribute(java.lang.String xpath,
                                  java.lang.String value,
                                  ValueBuilder valueBuilder)
                           throws ADKSchemaException

Sets an element or attribute value identified by an XPath-like query string.

Parameters:

xpath - An XPath-like query string that identifies the element or attribute to set. The string must reference elements and attributes by their version-independent names.

value - The value to assign to the element or attribute if the query string does not set a value; may be null

valueBuilder - a ValueBuilder implementation that evaluates expressions in XPath-like query strings using name/value pairs in the variables map

Throws:

ADKSchemaException - If the xpath is not valid

getElementOrAttribute

public Element getElementOrAttribute(java.lang.String xpath)
                              throws ADKSchemaException

Gets an element or attribute value identified by an XPath-like query string.

Parameters:

xpath - An XPath-like query string that identifies the element or attribute to get. The string must reference elements and attributes by their version-independent names.

Returns:

An Element instance encapsulating the element or attribute if found. If not found, null is returned. To retrieve the value of the Element, call its getTextValue method.

Throws:

ADKSchemaException - If the xpath is not valid

addSIFExtendedElement

public void addSIFExtendedElement(java.lang.String name,
                                  java.lang.String value)

Sets a SIF_ExtendedElement.

Parameters:

name - The element name

value - The element value

Since:

ADK 1.5

getSIFExtendedElements

public SIF_ExtendedElement[] getSIFExtendedElements()

Gets all SIF_ExtendedElements/SIF_ExtendedElement children of this object.

Returns:

An array of SIF_ExtendedElement instances. If no SIF_ExtendedElements child element was found, an empty array is returned

Since:

ADK 1.5

setSIFExtendedElements

public void setSIFExtendedElements(SIF_ExtendedElement[] elements)

Sets an array of SIF_ExtendedElement objects. All existing SIF_ExtendedElement instances are removed and replaced with this list. Calling this method with the parameter value set to null removes all SIF_ExtendedElements.

Parameters:

elements - The SIF_Extended elements instances to set on this object

Since:

ADK 1.5

getSIFExtendedElementsContainer

public SIF_ExtendedElements getSIFExtendedElementsContainer()

Gets the SIF_ExtendedElements container in which all child SIF_ExtendedElement elements are placed by the addSIFExtendedElement(String, String) method. Note if there is currently no container element, one is created and added as a child of the SIFDataObject.

This method is provided as a convenience to agents that wish to obtain the SIF_ExtendedElements container element in order to manually add extended elements to it. This is useful, for example, if you need to call methods on the extended element before adding it to the container (e.g. the setDoNotEncode method). The equivalent functionality is possible by making this call:

SIF_ExtendedElements container = (SIF_ExtendedElements)getChild( SIFDTD.SIF_EXTENDEDELEMENTS );


Returns:

The SIF_ExtendedElements container element, which is created and added as a child to this SIFDataObject if it does not currently exist.

setSIFExtendedElementsContainer

public void setSIFExtendedElementsContainer(SIF_ExtendedElements container)

Sets the SIF_ExtendedElements container for this object.

Normally, agents can just call addSIFExtendedElement(String, String), which automatically creates a SIF_ExtendedElements container, if necessary and allows for easy addition of SIF_ExtendedElements.

This method is provided as a convenience to agents that need more control or wish to set or completely replace the existing SIF_ExtendedElements container.

Parameters:

container - The new SIF_ExtendedElements container

getSIFMetadata

public SIF_Metadata getSIFMetadata()

Gets the SIF_Metadata for this object.

Returns:

The SIF_Metadata element, which is created and added as a child to this SIFDataObject if it does not currently exist.

setSIFMetadata

public void setSIFMetadata(SIF_Metadata metadata)

Sets the SIF_Metadata for this object.

Parameters:

metadata - The new SIF_Metadata object

getSIFExtendedElement

public SIF_ExtendedElement getSIFExtendedElement(java.lang.String name)

Gets the SIF_ExtendedElement with the specified Name attribute.

Parameters:

name - The value of the SIF_ExtendedElement/@Name attribute to search for

Returns:

The SIF_ExtendedElement that has a Name attribute matching the name parameter, or null if no such element exists

Since:

ADK 1.5

toXML

public java.lang.String toXML()

Returns the XML representation of this SIF Data Object

Returns:

The XML representation of this SIF Data Object

clone

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

Overrides:

clone in class SIFElement

Throws:

java.lang.CloneNotSupportedException