Ontology Wrapper
\
OntologyWrapper
traits

\OntologyWrapperIteratorSerialiser

Iterator serialiser

The duty of this class is to serialise query data returned by the services into a formatted set of data. The goal is to serialise the paged results into a single structure tagged by the API, providing a resolved set of data suited to be handled by user interface clients.

The class manages five main elements:

  • {@link iterator()}: The iterator is an object derived from the {@link mIteratorObject} class which holds the results of a query on the units collection. The iterator must have been previously paged and sorted.
  • {@link format()}: The format in which the iterator is to be serialised in:
    • {@link kAPI_RESULT_ENUM_DATA_COLUMN}: Column view. The {@link UnitObject::ListOffsets()} method will be used to select the object properties to be included.
    • {@link kAPI_RESULT_ENUM_DATA_FORMAT}: Formatted view. The data will contain the set of properties of the objects.
    • {@link kAPI_RESULT_ENUM_DATA_RECORD}: Record view. The data will contain the actual objects and related objects in their original format.
    • {@link kAPI_RESULT_ENUM_DATA_MARKER}: Marker view. The data will contain marker data for the selected objects.
  • {@link domain()}: The domain of the objects featured by the iterator, this property is required only if the format is {@link kAPI_RESULT_ENUM_DATA_COLUMN}, since in that case all objects should belong to the same domain.
  • {@link shape()}: The shape offset, this property is required only if the format is {@link kAPI_RESULT_ENUM_DATA_MARKER} to indicate which object property contains the geographic shape.
  • {@link language()}: The strings default language.

When requesting the {@link kAPI_RESULT_ENUM_DATA_COLUMN} or the {@link kAPI_RESULT_ENUM_DATA_FORMAT} format, the results will be encoded as an array indexed by object native identifier, containing the object data encoded as follows:

  • {@link kAPI_PARAM_RESPONSE_FRMT_NAME}: This element holds the data property name or label, both at the property level as well as the value level.
  • {@link kAPI_PARAM_RESPONSE_FRMT_INFO}: This element holds the data property and value information or description.
  • {@link kAPI_PARAM_RESPONSE_FRMT_DISP}: This element holds the data property display string, or list of display elements.
  • {@link kAPI_PARAM_RESPONSE_FRMT_LINK}: This element holds the URL for properties that represent an internet links.
  • {@link kAPI_PARAM_RESPONSE_FRMT_SERV}: If the property is an object reference, this element holds the list of parameters that can be used to call the service that will retrieve the data of the referenced object.
  • {@link kAPI_PARAM_RESPONSE_FRMT_DOCU}: If the property is a sub-structure, this element will hold the sub-structure data formatted in the same way as the root structure.

Once serialised, the iterator data is available via the {@link paging()}, {@link dictionary()} and {@link data()} methods which return respectively the paging, the dictionary and the serialised data.

Summary

Methods
Properties
Constants
__construct()
iterator()
format()
domain()
shape()
language()
paging()
dictionary()
data()
serialise()
No public properties found
No constants found
serialiseColumns()
serialiseFormatted()
serialiseMarkers()
serialiseRecords()
setColumns()
setRecord()
setProperty()
setTagLabel()
setDataValue()
aggregateProperty()
formatDataValue()
formatEnumeration()
formatTypedList()
formatLanguageStrings()
formatUnitReference()
formatShape()
formatBoolean()
formatInteger()
formatFloat()
formatTimeStamp()
formatScalar()
cacheTag()
cacheTerm()
cacheNode()
cacheEdge()
cacheUnit()
cacheUser()
cacheObject()
setHiddenTags()
clusterTags()
CollectOffsetTags()
$mIterator
$mFormat
$mDomain
$mOffset
$mShape
$mLanguage
$mPaging
$mDictionary
$mData
$mCache
$mProcessed
$mStructs
$mCurrentUnit
$mHidden
N/A
No private methods found
No private properties found
N/A

Properties

$mFormat

$mFormat : string

Format.

This protected data member holds the data format.

Type

string

$mDomain

$mDomain : string

Domain.

This protected data member holds the iterator objects domain.

Type

string

$mOffset

$mOffset : string

Offsets tag.

This protected data member holds the offsets tag to be tracked, this is relevant when serialising tags, the value corresponds to the tag offset which records the offsets found in a particular collection, these are the valid values:

  • {@link kTAG_TAG_OFFSETS}: Tag offsets.
  • {@link kTAG_TERM_OFFSETS}: Term offsets.
  • {@link kTAG_NODE_OFFSETS}: Node offsets.
  • {@link kTAG_EDGE_OFFSETS}: Edge offsets.
  • {@link kTAG_UNIT_OFFSETS}: Unit offsets.
  • {@link kTAG_ENTITY_OFFSETS}: Entity offsets.

Type

string

$mShape

$mShape : int

Shape.

This protected data member holds the default shape offset as the tag's serial number.

Type

int

$mLanguage

$mLanguage : string

Language.

This protected data member holds the default language.

Type

string

$mPaging

$mPaging : array

Paging.

This protected data member holds the paging information.

Type

array

$mDictionary

$mDictionary : array

Dictionary.

This protected data member holds the dictionary information.

Type

array

$mData

$mData : array

Data.

This protected data member holds the serialised data for the iterator.

Type

array

$mCache

$mCache : array

Cache.

This protected data member holds the object cache.

Type

array

$mProcessed

$mProcessed : boolean

Processed flag.

This protected data member holds the processed flag, which is set when the iterator is serialised.

Type

boolean

$mStructs

$mStructs : boolean

Traverse sub-structures flag.

This protected data member holds the flag that determines whether to traverse sub-substructures.

Type

boolean

$mCurrentUnit

$mCurrentUnit : \OntologyWrapper\PersistentObject

Current unit.

This protected data member holds the current unit object.

Type

\OntologyWrapper\PersistentObject

$mHidden

$mHidden : array

Hidden tags.

This protected data member holds the list of tags that will be hidden.

Type

array

Methods

__construct()

__construct(\OntologyWrapper\ObjectIterator $theIterator, string $theFormat, string $theLanguage, string $theDomain, string $theShape)

Instantiate class.

The constructor accepts all required object properties, the iterator, format and language are required, the other parameters may be set via the member accessor methods and are required depending on the type of format.

The iterator should have been paged by the caller: in this class we do not handle paging and sorting, we simply scan the iterator.

Parameters

\OntologyWrapper\ObjectIterator $theIterator

Iterator.
string $theFormat

Data format.
string $theLanguage

Default language.
string $theDomain

Optional domain for columns.
string $theShape

Optional shape for markers.

iterator()

iterator(\OntologyWrapper\ObjectIterator $theIterator, boolean $getOld) : \OntologyWrapper\ObjectIterator

Manage iterator

This method can be used to set the iterator, each time the iterator is set, the {@link paging()} information will be updated.

If the provided parameter is not an iterator, the method will return the current iterator.

Whenever the iterator is modified, the method will reset the processed flag, the paging information and the serialised data.

The method does not allow resetting the iterator.

Parameters

\OntologyWrapper\ObjectIterator $theIterator

Iterator.
boolean $getOld

TRUE get old value.

Returns

\OntologyWrapper\ObjectIterator —

Current or previous iterator.

format()

format(string $theFormat, boolean $getOld) : string

Manage format

This method can be used to set the format, the method will check if the provided value is correct.

Provide NULL to retrieve the current format.

Whenever the format is modified, the method will reset the processed flag, the paging information and the serialised data.

The method does not allow resetting the format.

Parameters

string $theFormat

Format.
boolean $getOld

TRUE get old value.

Throws

\OntologyWrapper\Exception

Returns

string —

Current or previous format.

domain()

domain(string $theDomain, boolean $getOld) : array

Manage domain

This method can be used to set the domain, the method will cache the provided domain and set the data member as a reference to the cached array object.

Provide NULL to retrieve the current domain.

Whenever the domain is modified, the method will reset the processed flag, the paging information and the serialised data.

The method does not allow resetting the domain.

Parameters

string $theDomain

Domain.
boolean $getOld

TRUE get old value.

Returns

array —

Current or previous domain array object.

shape()

shape(string $theShape, boolean $getOld) : array

Manage shape

This method can be used to set the shape, the method will cache the provided shape and set the data member as a reference to the cached array object.

Provide NULL to retrieve the current shape.

Whenever the shape is modified, the method will reset the processed flag, the paging information and the serialised data.

The method does not allow resetting the shape.

Parameters

string $theShape

Shape.
boolean $getOld

TRUE get old value.

Returns

array —

Current or previous shape array object.

language()

language(string $theLanguage, boolean $getOld) : array

Manage language

This method can be used to set the language, the method will set the language data member to the provided value.

Provide NULL to retrieve the current language.

The method does not allow resetting the language.

Parameters

string $theLanguage

Language.
boolean $getOld

TRUE get old value.

Returns

array —

Current or previous language.

paging()

paging() : array

Return paging information

This method will return the paging information; if the iterator was not yet serialised, the method will return NULL.

Returns

array —

Paging information or NULL.

dictionary()

dictionary() : array

Return dictionary information

This method will return the dictionary information; if the iterator was not yet serialised, the method will return NULL.

Returns

array —

Dictionary information or NULL.

data()

data() : array

Return serialised data

This method will return the serialised data; if the iterator was not yet serialised, the method will return NULL.

Returns

array —

Serialised data or NULL.

serialise()

serialise()

Serialise iterator

This method will serialise the iterator according to the parameters provided at instantiation.

If the iterator was previously serialised, the method will do nothing.

serialiseColumns()

serialiseColumns()

Serialise columns

This method will serialise the iterator data for columns

serialiseFormatted()

serialiseFormatted()

Serialise formatted

This method will serialise the iterator data for formatted records

serialiseMarkers()

serialiseMarkers()

Serialise markers

This method will serialise the iterator data for markers.

serialiseRecords()

serialiseRecords()

Serialise records

This method will serialise the iterator data for aggregated records.

setColumns()

setColumns()

Set table columns

The duty of this method is to set the table column information according to the current domain.

The method will format the columns in two ways, depending on the data format:

  • {@link kAPI_RESULT_ENUM_DATA_COLUMN}: The dictionary {@link kAPI_DICTIONARY_LIST_COLS} element will be loaded with an array of elements holding the column tag label and description.
  • {@link kAPI_RESULT_ENUM_DATA_RECORD}: The dictionary {@link kAPI_DICTIONARY_LIST_COLS} element will be loaded with an array indexed by tag serial numbers with tag native identifiers as value.

This method expects the domain parameter to have been set.

setRecord()

setRecord( $theContainer,  $theObject)

Set record

The duty of this method is to aggregate the provided object and all related objects in the provided container.

Parameters

$theContainer
$theObject

setProperty()

setProperty(array $theContainer, string $theOffset, mixed $theValue)

Set property

The duty of this method is to cache the property tag, allocate the property in the provided container, set the property labels and format the property value.

Parameters

array $theContainer

Data container.
string $theOffset

Data offset.
mixed $theValue

Data value.

setTagLabel()

setTagLabel(array $theContainer, array $theTag)

Set tag label

The duty of this method is to set the provided container with the label and description of the provided tag.

Parameters

array $theContainer

Data container.
array $theTag

Tag array object.

setDataValue()

setDataValue(array $theContainer, mixed $theValue, array $theTag)

Set value

The duty of this method is to set the provided container with the provided data value.

This method expects the current offset tag to have been cached.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Tag array object.

aggregateProperty()

aggregateProperty(string $theClass, string $theOffset, mixed $theValue, boolean $doTags)

Aggregate property

The duty of this method is to aggregate the provided offset tag and parse the eventual structured value.

Parameters

string $theClass

Object class.
string $theOffset

Data offset.
mixed $theValue

Data value.
boolean $doTags

TRUE means recurse tags.

formatDataValue()

formatDataValue(array $theContainer, mixed $theValue, array $theTag)

Format value

The duty of this method is to format and set the provided container with the provided data value.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Tag array object.

formatEnumeration()

formatEnumeration(array $theContainer, mixed $theValue, array $theTag)

Format enumerated value

The duty of this method is to format the provided enumerated value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatTypedList()

formatTypedList(array $theContainer, mixed $theValue, array $theTag)

Format typed list value

The duty of this method is to format the provided typed list value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatLanguageStrings()

formatLanguageStrings(array $theContainer, mixed $theValue, array $theTag)

Format language strings value

The duty of this method is to format the provided language strings and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatUnitReference()

formatUnitReference(array $theContainer, mixed $theValue, array $theTag)

Format unit reference value

The duty of this method is to format the provided unit reference and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatShape()

formatShape(array $theContainer, mixed $theValue, array $theTag)

Format shape value

The duty of this method is to format the provided shape and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatBoolean()

formatBoolean(array $theContainer, mixed $theValue, array $theTag)

Format boolean value

The duty of this method is to format the provided boolean value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatInteger()

formatInteger(array $theContainer, mixed $theValue, array $theTag)

Format integer value

The duty of this method is to format the provided integer value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatFloat()

formatFloat(array $theContainer, mixed $theValue, array $theTag)

Format float value

The duty of this method is to format the provided float value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatTimeStamp()

formatTimeStamp(array $theContainer, mixed $theValue, array $theTag)

Format time stamp value

The duty of this method is to format the provided time stamp value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

formatScalar()

formatScalar(array $theContainer, mixed $theValue, array $theTag)

Format scalar value

The duty of this method is to format the provided scalar value and set into the provided container.

Parameters

array $theContainer

Data container.
mixed $theValue

Data value.
array $theTag

Offset tag.

cacheTag()

cacheTag(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, mixed $theValue, boolean $doSequence) : mixed

Load tag in cache

This method will load the provided tag into the provided container, if not yet there, and return the cached tag as an array object.

The provided parameter may be an array, in that case the method will interpret the parameter as a list of references, add all the resolved objects to the provided container and return an array indexed by object identifier, with as value the object array.

If the last parameter is TRUE, the tag identifier will be its sequence number; if FALSE, its native identifier.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
mixed $theValue

Tag reference or object.
boolean $doSequence

TRUE, use sequence as identifier.

Returns

mixed —

The cached tag or tags.

cacheTerm()

cacheTerm(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, mixed $theValue) : mixed

Load term in cache

This method will load the provided term into the provided container, if not yet there, and return the cached term as an array object.

The provided parameter may be an array, in that case the method will interpret the parameter as a list of references, add all the resolved objects to the provided container and return an array indexed by object identifier, with as value the object array.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
mixed $theValue

Term reference or object.

Returns

mixed —

The cached term or terms.

cacheNode()

cacheNode(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, mixed $theValue) : mixed

Load node in cache

This method will load the provided node into the provided container, if not yet there, and return the node object as an array.

The provided parameter may be an array, in that case the method will add all the provided nodes and return an array of node array objects indexed by node native identifier.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
mixed $theValue

Node reference or object.

Returns

mixed —

The cached node or nodes.

cacheEdge()

cacheEdge(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, mixed $theValue) : mixed

Load edge in cache

This method will load the provided edge into the provided container, if not yet there, and return the edge object as an array.

The provided parameter may be an array, in that case the method will add all the provided edges and return an array of edge array objects indexed by edge native identifier.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
mixed $theValue

Edge reference or object.

Returns

mixed —

The cached edge or edges.

cacheUnit()

cacheUnit(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, mixed $theValue, boolean $doObject) : mixed

Load unit in cache

This method will load the provided unit into the provided container, if not yet there, and return the unit object as an array.

The provided parameter may be an array, in that case the method will add all the provided units and return an array of unit objects indexed by unit native identifier.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
mixed $theValue

Unit reference or object.
boolean $doObject

TRUE means cache object.

Returns

mixed —

The cached unit or units.

cacheUser()

cacheUser(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, mixed $theValue, boolean $doObject) : mixed

Load user in cache

This method will load the provided user into the provided container, if not yet there, and return the user object as an array.

The provided parameter may be an array, in that case the method will add all the provided users and return an array of user array objects indexed by term native identifier.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
mixed $theValue

User reference or object.
boolean $doObject

TRUE means cache object.

Returns

mixed —

The cached user or users.

cacheObject()

cacheObject(\OntologyWrapper\Wrapper $theWrapper, array $theContainer, string $theClass, array $theStrings, mixed $theValue, boolean $doObject) : mixed

Load object in cache

This method will load the provided node into the provided container, if not yet there, and return the cached node as an object or array object.

The provided parameter may be an array, in that case the method will interpret the parameter as a list of references, add all the resolved objects to the provided container and return an array indexed by object identifier, with as value the object or array object.

Parameters

\OntologyWrapper\Wrapper $theWrapper

Data wrapper.
array $theContainer

Data container.
string $theClass

Object class name.
array $theStrings

Language string offsets.
mixed $theValue

Object reference or object.
boolean $doObject

TRUE means cache object.

Returns

mixed —

The cached object or objects.

setHiddenTags()

setHiddenTags(\OntologyWrapper\PersistentObject $theObject)

Set hidden tags

The duty of this method is to set the list of tags that should not be published.

This is done according to the current data format, only the {@link kAPI_RESULT_ENUM_DATA_FORMAT} is relevant in this case, since the {@link kAPI_RESULT_ENUM_DATA_COLUMN} has a fixed set, the {@link kAPI_RESULT_ENUM_DATA_MARKER} uses only the object native identifier and the shape tag, and the {@link kAPI_RESULT_ENUM_DATA_RECORD} format selects all properties.

Once the method has completed, the {@link $mHidden} data member will hold the list of tag sequence numbers which will not be published.

By default we hide the object's internal and dynamic offsets.

Parameters

\OntologyWrapper\PersistentObject $theObject

Object.

clusterTags()

clusterTags()

Cluster tags

This method will update the response dictionary cluster.

This method should only be called on tags query collections.

CollectOffsetTags()

CollectOffsetTags(array $theContainer, \OntologyWrapper\PersistentObject $theTag)

Collect offset tags

This method will collect the offset tag objects of the provided tag into the provided container.

Parameters

array $theContainer

Receives tag objects.
\OntologyWrapper\PersistentObject $theTag

Tag object or array object.