Best Practices - Handling Collections

The purpose of this document is to provide best practices to handle collections.

Collections of child instances are managed as arrays, with additional technical properties and methods that simplify their management. For persistent classes, the supervisor handles all the code, and no additional line needs to be written.

Insertion and deletion

• Use the ADDLINE method to add a line.
• Use the ADELLINE method to delete a line.
• Use the ADDLINE_BEFORE, ADDLINE_AFTER, ADELLINE_BEFORE, and ADELLINE_AFTER events to add or delete lines in a specific position.

Control rules

• A consistency control on a single line must be written at the line level.
• A consistency control on several lines must be written at the parent class level.

Propagation rules

• Propagation within a line must be written at the line level.
• Propagation from the header to the line must be written at the header level.
• Propagation between lines is prohibited. Refer to Best Practices - Propagation Rules.

Line count

• The line count property is updated after a new line has been entered.
• If you need to know the number of lines during a control, count them using the ASTALIN property value (which cannot equal [V]CST_ANEWDEL or [V]CST_ADEL).

Example

The following example of code summarizes the different concepts mentioned above. Every section of this program can be considered autonomously.

• A document called MYDOCUMENT, with a key called NUMDOC, includes a collection called HISTORY that displays the list of users having modified this document. It contains the following properties:
  
  • The key of the document updated (DOCUMENT_UPD).
  • The user code (USER_UPD).
  • The last update date/time for the user (CRETIM_UPD).
  • The number of updates done by the user (NBTIMES_UPD).
  • A percentage of updates per user, computed and displayed when the document is read (PERC_UPD).
• The user update history is done by calling a dedicated method, either during the control in CRUD operations (such as the AINSERT_CONTROL_BEFORE and AUPDATE_CONTROL_BEFORE events), or through a dedicated link called in an edit facet. This method, called UPDATE_HISTORY, performs the following actions:
  
  • A user line history is added for the current user.
  • It keeps up to 10 lines in the history. If an additional line is entered, the oldest line is deleted.
  • The lines that record updates older than five years are purged, except for the current user.
  • The first line in the history corresponds to the latest update.

To handle this, the code is created at the document class level.

## The history update is done after all the other controls, and before launching the update or the creation actions.# The percentage of update number is computed after read (if creation, no history exists)$METHODSCase CURPTHWhen "HISTORY" : # Events on a collectionCase ACTIONWhen "ADDLINE_AFTER"Gosub INIT_HISTORY_LINEEndcaseWhen "" : # Global eventsCase ACTIONWhen "UPDATE_HISTORY"Gosub UPDATE_HISTORYWhen "READ_AFTER"Gosub COMPUTE_HISTORYEndcaseEndcaseReturn$INIT_HISTORY_LINEthis.DOCUMENT_UPD = this.APARENT.MYDOCthis.USER_UPD=this.ACTX.USERthis.CRETIM_UPD=timestamp$this.NBTIMES_UPD=1Return# A propagation rule is triggered on the history if document number is changed$PROPERTIESCase CURPROWhen "NUMDOC"Case ACTIONWhen "PROPAGATE"Gosub PROPAGATE_NUMDOCEndcaseEndcaseReturn# Dedicated method usually called before the creation and the update# Updates the history lines# "this" is the current document instance$UPDATE_HISTORYLocal Integer NUML, TWO_YEARS, OLDLINE, NEWLINE, NBLINES, OK, FIVE_YEARSLocal Decimal TIMESTP# Inititialize values: current timestamp value in milliseconds, number of days for the last 5 years...TIMESTP=val(timestamp$)FIVE_YEARS=(date$-gdat$(day(date$),month(date$),year(date$)-5))OK=[V]CST_AOKOLDLINE=0# Delete the line that is too old (if it is still present and not associated with the user)# Compute also in this loop OLDNUM: If not null, the user is already presentOK=0For NUML=1 To maxtab(this.HISTORY)If this.HISTORY(NUML)<>null : # The pointer can be null if a first validation has been doneIf find(this.HISTORY(NUML).ASTALIN,[V]CST_ADEL,[V]CST_ANEWDEL)=0If this.HISTORY(NUML).USER_UPD=this.ACTX.USEROLDLINE=NUMLElsif val(this.CRETIME_UPD)+FIVE_YEARS*24*3600*1000<TIMESTP : # Timestamps are in millisecondsOK=fmet this.ADELLINE("HISTORY",NUML)Break (OK<>[V]CST_AOK)EndifEndifEndifNext NUML# Handle the errorIf OK<>[V]CST_AOKASTATUS=fmet this.ASETERROR("","Cannot delete line from history"-num$(NUML),[V]CST_AERROR)ReturnEndif# Insert a line at the first position of the grid to store the most recent user updating the documentNEWLINE=fmet this.ADDLINE("HISTORY",[V]CST_AFIRSTPOS)If NEWLINE=[V]CST_ANOTDEFINEDASTATUS=fmet this.ASETERROR("","Cannot add line in history",[V]CST_AERROR)ReturnEndif# If a line already existed for the customer, update the last line and delete the previous oneIf OLDLINE<>0this.HISTORY(NEWLINE).NBTIMES_UPD=this.HISTORY(OLDLINE).NBTIMES_UPD+1OK=fmet this.ADELLINE("HISTORY",OLDLINE)Endif# Handle the errorIf OK<>[V]CST_AOKASTATUS=fmet this.ASETERROR("","Cannot delete line from history"-num$(NUML),[V]CST_AERROR)ReturnEndif# Count the number of lines in the collectionNBLINES=0For NUML=1 To maxtab(this.HISTORY)If this.HISTORY(NUML)<>null & find(this.HISTORY(NUML).ASTALIN,[V]CST_ADEL,[V]CST_ANEWDEL)=0NBLINES+=1EndifNext NUML# Delete the line having an index over 10# Here the technical property AORDER is used# But the AGETINDBYLINE method could also have been usedIf NBLINES>10OK=[V]CST_AOKFor NUML=1 To maxtab(this.HISTORY)If this.HISTORY(NUML)<>null & find(this.HISTORY(NUML).ASTALIN,[V]CST_ADEL,[V]CST_ANEWDEL)=0If this.HISTORY(NUML).AORDER>10OK=fmet this.ADELLINE("HISTORY",NUML)Break (OK<>[V]CST_AOK)EndifEndifNext NUMLEndif# Handle the errorIf OK<>[V]CST_AOKASTATUS=fmet this.ASETERROR("","Cannot delete line from history"-num$(NUML),[V]CST_AERROR)ReturnEndifReturn$PROPAGATE_NUMDOCFor NUML=1 To maxtab(this.HISTORY)If this.HISTORY(NUML)<>null & find(this.HISTORY(NUML).ASTALIN,[V]CST_ADEL,[V]CST_ANEWDEL)=0this.HISTORY(NUML).DOCUMENT_UPD = this.MYDOCEndifNext NUMLReturn# Computes the percentage of updates$COMPUTE_HISTORYLocal Integer NBLINE, TOTLINE# Count the number of lines in the collection and the totalNBLINES=0For NUML=1 To maxtab(this.HISTORY)If this.HISTORY(NUML)<>null & find(this.HISTORY(NUML).ASTALIN,[V]CST_ADEL,[V]CST_ANEWDEL)=0NBLINES+=1TOTLINE+=this.HISTORY(NUML).NBTIMES_UPDEndifNext NUML# Assign the percentagesFor NUML=1 To maxtab(this.HISTORY)If this.HISTORY(NUML)<>null & find(this.HISTORY(NUML).ASTALIN,[V]CST_ADEL,[V]CST_ANEWDEL)=0this.HISTORY(NUML).PERC_UPD=ar2(100*this.HISTORY(NUML).NBTIMES_UPD/TOTLINE)EndifNext NUMLReturn

Refer to the Classes Standard Methods Developer Guide for more information on collections.