Interface Inx_Api_Recipient_RecipientRowSet

Description

An Inx_Api_Recipient_RecipientRowSet is best explained as a table of data representing a set of recipients, which is usually generated by executing a selection that queries the recipient context.

An Inx_Api_Recipient_RecipientRowSet is best explained as a table of data representing a set of recipients, which is usually generated by executing a selection that queries the recipient context. An Inx_Api_Recipient_RecipientRowSet object maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The next() method moves the cursor to the next row (recipient), and because it returns false when there are no more rows in the Inx_Api_Recipient_RecipientRowSet object, it can be used in a while loop to iterate through the result set.

Be sure to call next() before the first retrieval statement on the row set. As stated above, initially the cursor is before the first row, thus no data can be retrieved from the row set before calling next(). Doing so will trigger an Inx_Api_DataException.

The Inx_Api_Recipient_RecipientRowSet interface provides getter methods (getString, getInteger, and so on) for retrieving attribute values from the current row. Values can be retrieved using the attribute object.

The following snippet shows how to retrieve the email address of all recipients in the row set, thus also illustrating how to iterate over an Inx_Api_Recipient_RecipientRowSet:

 $oRecipientContext = $oSession->createRecipientContext();
 $oAttribute = $oRecipientContext->getMetaData()->getEmailAttribute();
 $oRecipientRowSet = $oRecipientContext->select();

 while( $oRecipientRowSet->next() )
 {
 	echo $oRecipientRowSet->getString( $oAttribute )."<br>";
 }

The update methods may be used in two ways:

  1. To update a column value in the current row. In an Inx_Api_Recipient_RecipientRowSet object, the cursor can be moved backwards and forwards, to an absolute position. The following snippet shows how to update the Lastname attribute in the fifth row of the RecipientRowSet object rrs and then uses the method commitRowUpdate to commit the changed data from which rrs was derived:
     $oAttribute = $oRecipientMetaData->getUserAttribute( "Lastname" );
     $oRecipientRowSet->setRow(4); // moves the cursor to the fifth row of $recipientRowSet
     // updates the 'Lastname' attribute of row 4 (fifth row) to be 'Smith'
     $oRecipientRowSet->updateString( $oAttribute, "Smith" );
     $oRecipientRowSet->commitRowUpdate(); // updates the row in the data source
  2. To insert attribute values into the insert row. The Inx_Api_Recipient_RecipientRowSet object has a special row associated with it that serves as a staging area for building a recipient to be inserted. The following snippet shows how to move the cursor to the insert row and insert the new recipient data into rrs and into the data source table using the method commitRowUpdate:
     $oAttribute_email = $oRecipientMetaData->getEmailAttribute();
     $oAttribute_attr = $oRecipientMetaData->getUserAttribute( "Lastname" );
     $oRecipientRowSet->moveToInsertRow(); // moves cursor to the insert row
     // email attribute of the insert row to be smith@gmx.com
     $oRecipientRowSet->updateString( $oAttribute_email, "smith@gmx.com");
     $oRecipientRowSet->updateString( $oAttribute_attr, "Smith");
     $oRecipientRowSet->commitRowUpdate();  // insert the row in the data source
    The code above will create a new recipient with the address smith@gmx.com and the last name Smith. Usually creating new recipients is accomplished using an empty Inx_Api_Recipient_RecipientRowSet. Such a row set can be obtained using the Inx_Api_Recipient_RecipientContext::createRowSet() method. However, the returned row set can only be used to create recipients, as there are no recipients in the row set.

All row changes except for the remove() and setAttributeValue() methods require a call of commitRowUpdate() to be reflected on the server. Any uncommitted changes will be lost once the Inx_Api_Recipient_RecipientRowSet is closed. However, calling commitRowUpdate() on deleted rows will trigger an Inx_Api_DataException, as the recipient in the current row no longer exists.

Note: To safely abandon all changes of the current row, use the rollbackRowUpdate() method. This will prevent any changes to the current row from being committed through commitRowUpdate(). Be aware that rollbackRowUpdate will only undo uncommitted changes to the current row. So, once you called commitRowUpdate() there is &quot;no way back&quot;.

<strong>Note:</strong> An Inx_Api_Recipient_RecipientContext object <strong>must</strong> be closed once it is not needed anymore to prevent memory leaks and other potentially harmful side effects.

For more information about recipients and the operations that can be performed on them, see the Inx_Api_Recipient_RecipientContext documentation.

  • author: chge, 16.05.2013
  • version: $Revision: 9553 $ $Date: 2008-01-04 11:28:41 +0200 (Pn, 04 Sau 2008) $ $Author: vladas $
  • see: Inx_Api_Recipient_RecipientContext
  • since: API 1.0

Located in /Api/Recipient/RecipientRowSet.php (line 99)

Inx_Api_InxRowSet
   |
   --Inx_Api_Recipient_ReadOnlyRecipientRowSet
      |
      --Inx_Api_Recipient_RecipientManipulationRowSet
         |
         --Inx_Api_Recipient_RecipientRowSet
Method Summary
int getId ()
bool setAttributeValue (Inx_Api_Recipient_Attribute $oAttr,  $mNewValue, [Inx_Api_IndexSelection $oSelection = null], mixed $oNewValue)
Methods
getId (line 121)

Retrieves the recipient id of the current row of this Inx_Api_Recipient_RecipientRowSet object.

Retrieves the recipient id of the current row of this Inx_Api_Recipient_RecipientRowSet object.

  • return: the recipient id in the current recipient.
  • throws: Inx_Api_DataException if the recipient was deleted or no recipient is selected (e.g. you forgot to call next()).
  • access: public
int getId ()
setAttributeValue (line 112)

Sets the specified attribute value to the recipients in the specified selection.

Sets the specified attribute value to the recipients in the specified selection. This method does <strong>not</strong> require a call to commitRowUpdate() to be reflected on the server. The selection parameter may be ommitted to set the attribute value for all recipients in this row set.

  • return: true if the attribute was updated, false otherwise.
  • access: public
bool setAttributeValue (Inx_Api_Recipient_Attribute $oAttr,  $mNewValue, [Inx_Api_IndexSelection $oSelection = null], mixed $oNewValue)

Inherited Methods

Inherited From Inx_Api_Recipient_RecipientManipulationRowSet

Inx_Api_Recipient_RecipientManipulationRowSet::updateBoolean()
Inx_Api_Recipient_RecipientManipulationRowSet::updateDate()
Inx_Api_Recipient_RecipientManipulationRowSet::updateDatetime()
Inx_Api_Recipient_RecipientManipulationRowSet::updateDouble()
Inx_Api_Recipient_RecipientManipulationRowSet::updateInteger()
Inx_Api_Recipient_RecipientManipulationRowSet::updateObject()
Inx_Api_Recipient_RecipientManipulationRowSet::updateString()
Inx_Api_Recipient_RecipientManipulationRowSet::updateTime()

Inherited From Inx_Api_Recipient_ReadOnlyRecipientRowSet

Inx_Api_Recipient_ReadOnlyRecipientRowSet::getBoolean()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getContext()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getDate()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getDatetime()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getDouble()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getInteger()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getMetaData()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getObject()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getString()
Inx_Api_Recipient_ReadOnlyRecipientRowSet::getTime()

Inherited From Inx_Api_InxRowSet

Inx_Api_InxRowSet::afterLastRow()
Inx_Api_InxRowSet::beforeFirstRow()
Inx_Api_InxRowSet::close()
Inx_Api_InxRowSet::getRow()
Inx_Api_InxRowSet::getRowCount()
Inx_Api_InxRowSet::next()
Inx_Api_InxRowSet::previous()
Inx_Api_InxRowSet::setRow()

Documentation generated on Thu, 17 Sep 2015 14:27:28 +0200 by phpDocumentor 1.3.2