SModel2 Class Reference
[Core Objects]

Base class for all model objects. More...

Inheritance diagram for SModel2:

Inheritance graph
[legend]

List of all members.

Public Member Functions

& __get ($attr)
 Implements magic attribute access (retrieving).
 __set ($attr, $value)
 Implements magic attribute access (updating).
 attributeExists ($attr)
 Returns whether given attribute exists on this object.
 commit ($updateObj=false)
 Saves object to database/XML store.
 copy ($asNew=false)
 INSERT BRIEF DESCRIPTION HERE.
 getAttributeDefault ($attr)
 Retrieves the default value of an attribute.
 getAttributeForeign ($attr)
 Retrieves the foreign key information of an attribute.
 getAttributeInfo ($attr)
 Retrieves all metadata about an attribute.
 getAttributes ($metainfo=false)
 Retrieves list of attributes that this object has, along with meta-information.
 getAttributeType ($attr)
 Retrieves the type of an attribute.
 getValues ($useBase=false)
 Retrieves attributes and current values for those attributes.
 getValuesRecursive ()
 Retrieves values from this and dependent objects.
 getXML ($options=array())
 Retrieves XML representation of this object.
 isAttributeArray ($attr)
 Retrieves whether attribute is an array or a scalar.
 isAttributeEditable ($attr)
 Retrieves boolean indicating whether attribute is able to be modified.
 isAttributeNullable ($attr)
 Retrieves boolean indicating whether attribute is nullable.
 isChanged ($attr)
 Determins whether a given attribute has changed since the last commit or populate.
 isDirty ()
 Returns whether object has uncommitted changes.
 isMarkedForDeletion ()
 Returns whether this object is marked to be deleted on next commit.
 isStored ()
 Returns whether object is in database/XML store.
 isValid ()
 Determines whether object is safe to be committed.
 markAsLoaded ($recursive=false)
 Marks object as being loaded from DB.
 markForDeletion ()
 Marks object to be deleted on next commit.
 populate ($constraints)
 Loads object from database/XML store.
 revert ()
 Restores the value of the object's attributes to the original state.
 setValues ($values)
 Sets a range of attributes at once.
 setXML ($xml)
 Sets the XML representation of this object, updating contents as possible.

Public Attributes

const COMMIT_ALWAYS
 Always commit this attribute, even when it hasn't been changed.
const COMMIT_CHANGED
 Commit only when attribute has changed.
const COMMIT_FIRST
 COMMIT_ALWAYS on the first commit, and COMMIT_CHANGED on subsequence commits.
const COMMIT_FOREIGN
 Only commit in conjunction with a foreign key.
const COMMIT_NEVER
 Never commit this attribute.
const COMMIT_NOSOURCE
 Attribute doesn't actually exist in DB or datasource and should not be committed or populated.

Detailed Description

Base class for all model objects.

This class implements default methods for functionality that will be more specific in derived class such as SDatabaseModel and SXMLModel. It also provides base functionality, such as attribute management, that is used throughout the model hierarchy.

Each object contains a set of attributes. The class stores information about attributes, such as the type, whether the attribute is nullable and the default value for that attribute. This information is provided by derived classes (the leaf classes, notably) when they call registerAttributes() or addAttribute(). Attributes can be accessed as if they were public member variables of the object. However, through the magic of __get() and __set(), the types of the values are checked when setting attributes, and when accessing invalid attributes (i.e., those that don't exist) an error is flagged.

Each object also keeps track of its base state, that is, the state that it had when it was created, was last populated or last committed, and the current state, that is, the state that it has after any changes have been made by setting attributes or XML. When an object is committed, only differences between the current state and the base state are committed (if the backing store supports that kind of thing) and then the current state becomes the new base state. This mechanism makes it easy to revert changes in the object and also potentially limits the size of updating commits.

SModel2 objects support XML. It is possible to take an XML string and use it to initialize/update an object and each object can produce a string of XML that represents it. This mechanism works for both database backed objects and XML backed objects. The XML backed objects, however, have more complex ways of dealing with converting to and from XML.

Member Function Documentation

& SModel2::__get ( $  attr  ) 

Implements magic attribute access (retrieving).

Parameters:
$attr [string]: name of attribute to retrieve
Returns:
[mixed]: value of attribute, or null if attribute does not exist

SModel2::__set ( $  attr,
$  value 
)

Implements magic attribute access (updating).

This method performs type checking to make sure that the attribute is not being set to a value that is not valid according to the information about attributes for the given model.

Parameters:
$attr [string]: name of attribute to update
$value [mixed]: new value for attribute
Returns:
[boolean]: true if update was successful, false otherwise

SModel2::attributeExists ( $  attr  ) 

Returns whether given attribute exists on this object.

Parameters:
$attr [string]: name of attribute whose existence to check for
Returns:
[boolean]: whether attribute exists

SModel2::commit ( $  updateObj = false  )  [abstract]

Saves object to database/XML store.

This method saves any changes made to this object to a database or XML store. If the object was not already stored in the database or XML store, it will be created there. Otherwise, the method should only save attributes that have changed since the last populate or commit. It is up to derived classes to actually implement this method.

Returns:
[boolean]: success or failure

Reimplemented in View_SDRResourceDetails, View_SDRResourceMinimal, SDatabaseModel, and SXMLModel.

SModel2::copy ( $  asNew = false  ) 

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:
$asNew [TYPE]: DESCRIPTION
Returns:
[TYPE]: RETURN DESCRIPTION

Reimplemented in SDatabaseModel.

SModel2::getAttributeDefault ( $  attr  ) 

Retrieves the default value of an attribute.

The default value is used when an attribute has not been otherwise initialized from the database, or set directly by the user.

Parameters:
$attr [string]: name of attribute
Returns:
[mixed]: default value of attribute, or null if attribute does not exist

SModel2::getAttributeForeign ( $  attr  ) 

Retrieves the foreign key information of an attribute.

Foreign key information is used really only in SDatabaseModel for generating JOINs automatically

Parameters:
$attr [string]: name of attribute
Returns:
[mixed]: foreign key information of attribute, or null if attribute does not exist

SModel2::getAttributeInfo ( $  attr  ) 

Retrieves all metadata about an attribute.

This is equivalent to calling all of the getAttributeType(), getAttributeForeign(), etc.

Parameters:
$attr [string]: name of attribute
Returns:
[array]: attribute metadata

SModel2::getAttributes ( $  metainfo = false  ) 

Retrieves list of attributes that this object has, along with meta-information.

Parameters:
$metainfo [boolean]: if true, include meta-information about each attribute in an associative array
Returns:
[array]: flat list of attribute names or associative array of attribute => meta-information

SModel2::getAttributeType ( $  attr  ) 

Retrieves the type of an attribute.

Parameters:
$attr [string]: name of attribute
Returns:
[string]: type of attribute, or null if attribute does not exist

SModel2::getValues ( $  useBase = false  ) 

Retrieves attributes and current values for those attributes.

The array returned is an associative array, keyed by attribute name.

Parameters:
$useBase [bool]: if true, show base values instead of current values
Returns:
[array]: associative array of attribute => value pairs

SModel2::getValuesRecursive (  ) 

Retrieves values from this and dependent objects.

This only returns database valid fields, not objects and NOSOURCE

Returns:
[array]: nested array of value for this and dependent objects

SModel2::getXML ( $  options = array()  ) 

Retrieves XML representation of this object.

The XML representation of this object is stored in the xmlString and xmlTree member variables. These memebers are not updated until this method is called. This method constructs new XML based on any changes made to the object since the last XML generation (if any). New XML will not be constructed if xmlTree and xmlString already have values and the object hasn't changed since the last call to getXML().

The options currently supported by the $options array parameter are:

  • forceRegen: if true, cached XML is discarded and new XML is generated from scratch
  • root: if set, this provides the name of the root XML element
  • asString: if true, return a string of XML, rather than a SimpleXML object
Parameters:
$options [array]: options to control generation of XML (see above)
Returns:
[mixed]: string of XML or simplexml object (depending on the value of the $asString paramter) or null on failure

Reimplemented in SDatabaseModel, and SXMLModel.

SModel2::isAttributeArray ( $  attr  ) 

Retrieves whether attribute is an array or a scalar.

If attribute is array, then the type information applies to each individual element.

Parameters:
$attr [string]: name of attribute
Returns:
[boolean]: whether attribute is an array, or null if attribute does not exist

SModel2::isAttributeEditable ( $  attr  ) 

Retrieves boolean indicating whether attribute is able to be modified.

Parameters:
$attr [string]: name of attribute
Returns:
[boolean]: whether attribute can be modified, or null if attribute does not exist

SModel2::isAttributeNullable ( $  attr  ) 

Retrieves boolean indicating whether attribute is nullable.

A nullable attribute can be set to null or the empty string. Non-nullable attributes are required to have some value.

Parameters:
$attr [string]: name of attribute
Returns:
[boolean]: whether attribute is nullable or not, or null if attribute does not exist

SModel2::isChanged ( $  attr  ) 

Determins whether a given attribute has changed since the last commit or populate.

Parameters:
$attr [string]: name of attribute to check
Returns:
[boolean]: whether attribute has changed

SModel2::isDirty (  ) 

Returns whether object has uncommitted changes.

If any values have been changed since the last commit or populate, this method will return true. Newly created objects that were not created from the DB/XML store are considered dirty as well.

Returns:
[boolean]: whether object is dirty

SModel2::isMarkedForDeletion (  ) 

Returns whether this object is marked to be deleted on next commit.

Returns:
[boolean]: whether object is marked for deletion

SModel2::isStored (  ) 

Returns whether object is in database/XML store.

If object was populated, or has been committed, this will return true.

Returns:
[boolean]: whether object is in database/XML store

SModel2::isValid (  ) 

Determines whether object is safe to be committed.

This method checks that all required attributes have values, and that their values fit the types given for the attributes. If you wish to do additional validation, you should override this method.

Returns:
[boolean]: whether object is safe to be committed

SModel2::markAsLoaded ( $  recursive = false  ) 

Marks object as being loaded from DB.

This method just calls updateBase() and makes it so that the object appears to have been populated or committed, even if its data was loaded in some other way. Only use this method if the object really does exist in the DB (or other source), but could not be populated directly.

Parameters:
$recursive [boolean]: if true, mark all child objects that are SModel2 objects as loaded as well

SModel2::markForDeletion (  ) 

Marks object to be deleted on next commit.

This method does not immediately delete the object from the database/XML store, but simply marks it as needing to be deleted. On the next call to commit(), the object will be deleted, if possible.

SModel2::populate ( $  constraints  )  [abstract]

Loads object from database/XML store.

This method is to be implemented by derived classes, based on their nature. It takes a generic constraints variable, which for databases, for example, is the same as the constraints array used in DBI2::select(). See the documentation for derived versions of populate for more.

Parameters:
$constraints [mixed]: information that identifies the object to be populated
Returns:
[boolean]: success or failure

Reimplemented in SXMLModel.

SModel2::revert (  ) 

Restores the value of the object's attributes to the original state.

The original state that the values are restored to depends on the history of the object. For a newly created object that was not populated from the database (or XML store), the values are simply reset to the defaults, which depends on the model in use. For an object that has been populated, the values are reset to what they were just after the populate operation. If there have been commits, the object will be restored to whatever the values were on the last commit. The overall idea is that the object will be restored to whatever state it is in in the database/XML store, to the extent that that is possible (if the object was changed via another script in the meantime, then the restored state won't actually match the database).

SModel2::setValues ( $  values  ) 

Sets a range of attributes at once.

This method simply repeatedly calls __set() with the values provided in the array given as the sole parameter. This array is an associative array mapping attribute names to values. If any attributes don't exist, an error is flagged, but the operation is not stopped. As such, those attributes which can be set are set and those which cannot will flag an error.

Parameters:
$values [array]: associative array of attribute => value pairs to be set on this object

SModel2::setXML ( $  xml  ) 

Sets the XML representation of this object, updating contents as possible.

The xmlTree and xmlString members of this object are updated based on the XML given to this method. Additionally, the values of this object are updated based on the XML. The default implementation, given here, is to take the values of all top-level XML nodes that have the names of any of the attributes of this object, and put the values of those nodes into the corresponding entries in currentValues. Other nodes are ignored, as are attributes on those top-level nodes.

The type of the attribute determines how the value is stored. If the type is 'string', 'int' or 'float', then the XML node must not have a subtree (i.e., it must have nothing but textual content) and that textual content is put into the value for the corresponding attribute. If the type is 'array', the XML subtree starting at that node is converted to an array and stored in the attribute. If the type is 'object', then an object is created (as specified by the type) and setXML() is called on that object with the XML subtree for the node.

Parameters:
$xml [string]: string of XML to load, or, alternatively, a simplexml object
Returns:
[boolean]: success or failure

The documentation for this class was generated from the following file:
Generated on Wed Nov 24 02:03:06 2010 for Common by  doxygen 1.5.6