xo::db::Class instproc instantiate_objects (public)

 <instance of xo::db::Class> instantiate_objects [ -dbn dbn ] \
    [ -sql sql ] [ -full_statement_name full_statement_name ] \
    [ -as_ordered_composite on|off ] [ -object_class object_class ] \
    [ -named_objects on|off ] \
    [ -object_named_after object_named_after ] \
    [ -destroy_on_cleanup on|off ] [ -keep_existing_objects on|off ] \
    [ -ignore_missing_package_ids on|off ] [ -initialize initialize ]

Defined in /var/www/openacs.org/packages/xotcl-core/tcl/05-db-procs.tcl

Retrieve multiple objects from the database using the given SQL query and create XOTcl objects from the tuples.

Switches:

-dbn (optional)

-sql (optional)

The SQL query to retrieve tuples. Note that if the SQL query only returns a restricted set of attributes, the objects will be only partially instantiated.

-full_statement_name (optional)

-as_ordered_composite (optional, boolean, defaults to "true")

return an ordered composite object preserving the order. If the flag is false, one has to use "info instances" to access the resulted objects.

-object_class (optional, defaults to "::xotcl::Object")

specifies the XOTcl class, for which instances are created.

-named_objects (optional, boolean, defaults to "false")

If this flag is true, the value of the id_column is used for the name of the created objects (object will be named e.g. ::13738). Otherwise, objects are created with the XOTcl "new" method to avoid object name clashes.

-object_named_after (optional)

-destroy_on_cleanup (optional, boolean, defaults to "true")

If this flag is true, the objects (and ordered composite) will be automatically destroyed on cleanup (typically after the request was processed).

-keep_existing_objects (optional, boolean, defaults to "false")

-ignore_missing_package_ids (optional, boolean, defaults to "false")

-initialize (optional, defaults to "true")

can be used to avoid full initialization, when a large series of objects is loaded. Per default, these objects are initialized via initialize_loaded_object, when the are of type ::xo::db::Object

Testcases:

xowiki_test_cases

Source code:

if {$object_class eq ""} {set object_class [self]}
if {$sql eq ""} {set sql [:instance_select_query]}
if {$as_ordered_composite} {
  set __result [::xo::OrderedComposite new]
  if {$destroy_on_cleanup} {$__result destroy_on_cleanup}
} else {
  set __result [list]
}
if {$named_objects} {
  if {$object_named_after eq ""} {
    set object_named_after [:id_column]
  }
}

set sets [uplevel [list ::xo::dc sets -dbn $dbn dbqd..[self proc] $sql]]
foreach selection $sets {
  if {$named_objects} {
    set object_name ::[ns_set get $selection $object_named_after]
    if {[nsf::is object $object_name]} {
      set o $object_name
      set new 0
    } else {
      set o [$object_class create $object_name]
      set new 1
    }
  } else {
    set new 0
    set o [$object_class new]
  }
  if {$as_ordered_composite} {
    $__result add $o
  } else {
    if {$destroy_on_cleanup} {
      $o destroy_on_cleanup
    }
    lappend __result $o
  }

  if {!$new && $keep_existing_objects} {
    #ns_log notice "+++ instantiate_objects keep existing object $o"
    continue
  }
  $o mset [ns_set array $selection]
  ns_set free $selection

  if {[$o exists object_type]} {
    #
    # Set the object type if it looks like managed from XOTcl.
    #
    set object_type [$o set object_type]
    if {[string match "::*" $object_type]} {
      $o class $object_type
    }
  }
  if {$initialize && [$o istype ::xo::db::Object]} {
    if {![$o exists package_id]} {
      if {[$o exists object_package_id]} {
        $o set package_id [$o set object_package_id]
      } elseif {!$ignore_missing_package_ids} {
        ns_log warning "[namespace tail [$o info class]] $o has no package_id and no object_package_id"
      }
    }
    ad_try {
      $o initialize_loaded_object
    } on error {errorMsg} {
      set context [lmap var {name item_id revision_id} {
        if {![$o exists $var]} continue
        set _ "$var [$o set $var]"
      }]
      ns_log error "$o initialize_loaded_object [join $context]"  "=> [lsort [$o info vars]] -> $errorMsg"
    }
  }
  #:log "--DB more = $continue [$o serialize]"
}

return $__result

XQL Not present:

Generic, PostgreSQL, Oracle