xotcl.wu-wien.ac.at
Begin main content
Methods: Source: Variables:
[All Methods | Documented Methods | Hide Methods] [Display Source | Hide Source] [Show Variables | Hide Variables]

::xotcl::Class[i] ::xo::db::Class

Class Hierarchy of ::xo::db::Class

  • ::xotcl::Object[i]
    Meta-class:
    ::xotcl::Class[i]
    Methods for instances:
    __api_make_doc, __api_make_forward_doc, __timediff, abstract, ad_doc, ad_forward, ad_proc, appendC, arrayC, asHTML, autonameC, check, classC, cleanupC, configureC, containsC, copyC, db_0or1rowC, db_1rowC, debug, defaultmethodC, destroyC, destroy_on_cleanup, ds, evalC, existsC, extractConfigureArg, filterC, filterguardC, filtersearch, forward, hasclass, incrC, infoC, init, instvarC, invarC, isclass, ismetaclass, ismixin, isobject, istype, lappendC, log, method, mixinC, mixinguardC, moveC, msg, noinitC, objectparameter, parametercmdC, proc, procsearch, qn, requireNamespaceC, residualargsC, self, serialize, setC, set_instance_vars_defaults, show-object, substC, traceC, unknown, unsetC, uplevelC, upvarC, volatileC, vwait
    Methods to be applied on the class (in addition to the methods provided by the meta-class):
    getExitHandler, setExitHandler, unsetExitHandler
    • ::xotcl::Class[i]
      Meta-class:
      ::xotcl::Class[i]
      Parameter for instances:
      __default_metaclass (default "::xotcl::Class"), __default_superclass (default "::xotcl::Object")
      Methods for instances:
      ad_instproc, allinstances, allocC, createC, deallocC, extend_slot, infoC, instfilterC, instfilterguardC, instforward, instinvarC, instmixinC, instmixinguardC, instparametercmdC, instproc, method, newC, parameter, recreateC, slots, superclassC, unknown, uses
      Methods to be applied on the class (in addition to the methods provided by the meta-class):
      __unknown
::xo::db::Class is a meta class for interfacing with acs_object_types. acs_object_types are instances of this meta class. The meta class defines the behavior common to all acs_object_types. The behavior common to all acs_objects is defined by the class ::xo::db::Object.
Defined in packages/xotcl-core/tcl/05-db-procs.tcl

Class Relations

  • superclass: ::xotcl::Class[i]
  • subclass: ::xo::PackageMgr[i], ::xo::db::CrClass[i]
::xotcl::Class create ::xo::db::Class \
     -superclass ::xotcl::Class \
     -parameter {{abstract_p f} {auto_save false} id_column {name_method ""} \
       {object_type [self]} pretty_name pretty_plural {security_inherit_p t} sql_package_name \
       {supertype acs_object} table_name {with_table true}}

Methods

  • proc delete (public)

    ::xo::db::Class[i] delete -id id 
    Delete the object from the database

    Switches:
    -id (required)
    ::2189552 proc delete -id:required {
        ::xo::db::sql::acs_object delete -object_id $id
      }
    
  • proc delete_all_acs_objects (public)

    ::xo::db::Class[i] delete_all_acs_objects -object_type object_type 
    Delete all acs_objects of the object_type from the database.

    Switches:
    -object_type (required)
    ::2189552 proc delete_all_acs_objects -object_type:required {
        set table_name [::xo::db::Class get_table_name -object_type $object_type]
        if {$table_name ne ""} {
          db_dml delete_instances {delete from :table_name}
        }
      }
    
  • proc drop_type (public)

    ::xo::db::Class[i] drop_type -object_type object_type  \
        [ -drop_table drop_table ] [ -cascade_p cascade_p ]
    Drop the object_type from the database and drop optionally the table. This method deletes as well all acs_objects of the object_type from the database.

    Switches:
    -object_type (required)
    -drop_table (defaults to "f") (optional)
    -cascade_p (defaults to "t") (optional)
    ::2189552 proc drop_type {-object_type:required {-drop_table f} {-cascade_p t}} {
        set table_name [::xo::db::Class get_table_name -object_type $object_type]
        if {$table_name ne ""} {
          if {[catch {
    	db_dml [my qn delete_instances] "delete from $table_name"
    	if {$drop_table} {
    	  db_dml [my qn drop_table] "drop table $table_name"
    	}
          } errorMsg]} {
    	my log "error during drop_type"
          }
        }
        ::xo::db::sql::acs_object_type drop_type  -object_type $object_type -cascade_p $cascade_p
        return ""
      }
    
  • proc exists_in_db (public)

    ::xo::db::Class[i] exists_in_db -id id 
    Check, if an acs_object exists in the database.

    Switches:
    -id (required)
    Returns:
    0 or 1
    ::2189552 proc exists_in_db -id:required {
        return [::xo::db_string select_object {
          select 1 from acs_objects where object_id = :id
        } 0]
      }
    
  • proc get_class_from_db (public)

    ::xo::db::Class[i] get_class_from_db [ -object_type object_type ]
    Fetch an acs_object_type from the database and create an XOTcl class from this information.

    Switches:
    -object_type (optional)
    Returns:
    class name of the created XOTcl class
    ::2189552 proc get_class_from_db -object_type {
        # some table_names and id_columns in acs_object_types are unfortunately upper case, 
        # so we have to convert to lower case here....
        ::xo::db_1row fetch_class {
          select object_type, supertype, pretty_name, lower(id_column) as id_column, lower(table_name) as table_name
          from acs_object_types where object_type = :object_type
        }
        set classname [my object_type_to_class $object_type]
        if {![my isclass $classname]} {
          # the XOTcl class does not exist, we create it
          #my log "--db create class $classname superclass $supertype"
          ::xo::db::Class create $classname  -superclass [my object_type_to_class $supertype]  -object_type $object_type  -supertype $supertype  -pretty_name $pretty_name  -id_column $id_column  -table_name $table_name  -sql_package_name [namespace tail $classname]  -noinit
        } else {
          #my log "--db we have a class $classname"
        }
        set attributes [::xo::db_list_of_lists get_atts {
          select attribute_name, pretty_name, pretty_plural, datatype, 
          default_value, min_n_values, max_n_values
          from acs_attributes where object_type = :object_type
        }]
        
        set slots ""
        foreach att_info $attributes {
          foreach {attribute_name pretty_name pretty_plural datatype default_value
            min_n_values max_n_values} $att_info break
    
          # ignore some erroneous definitions in the acs meta model
          if {[my exists exclude_attribute($table_name,$attribute_name)]} continue
    
          set defined_att($attribute_name) 1
          set cmd [list ::xo::db::Attribute create $attribute_name  -pretty_name $pretty_name  -pretty_plural $pretty_plural  -datatype $datatype  -min_n_values $min_n_values  -max_n_values $max_n_values]
          
          if {$default_value ne ""} {
    	# if the default_value is "", we assume, no default
    	lappend cmd -default $default_value
          }
          append slots $cmd \n
        }
        if {[catch {$classname slots $slots} errorMsg]} {
          error "Error during slots: $errorMsg"
        }
    
        $classname init
        return $classname
      }
    
  • proc get_instance_from_db (public)

    ::xo::db::Class[i] get_instance_from_db -id id 
    Create an XOTcl object from an acs_object_id. This method determines the type and initializes the object from the information stored in the database. The XOTcl object is destroyed automatically on cleanup (end of a connection request).

    Switches:
    -id (required)
    Returns:
    fully qualified object
    ::2189552 proc get_instance_from_db -id:required {
        set type  [my get_object_type -id $id]
        set class [::xo::db::Class object_type_to_class $type]
        if {![my isclass $class]} {
          error "no class $class defined"
        }
        set r [$class create ::$id]
        $r db_1row get_instance [$class fetch_query $id]
        $r set object_id $id
        $r destroy_on_cleanup
        $r initialize_loaded_object
        return $r
      }
    
  • proc get_object_type (public)

    ::xo::db::Class[i] get_object_type [ -id id ]
    Return the object type for the give id.

    Switches:
    -id (optional)
    Returns:
    object_type, typically an XOTcl class
    ::2189552 proc get_object_type -id:integer,required {
        return [ns_cache eval xotcl_object_type_cache $id {
          ::xo::db_1row get_class "select object_type from acs_objects where object_id=$id"
          return $object_type
        }]
      }
    
  • proc get_table_name (public)

    ::xo::db::Class[i] get_table_name -object_type object_type 
    Get the table_name of an object_type from the database. If the object_type does not exist, the return value is empty.

    Switches:
    -object_type (required)
    Returns:
    table_name
    ::2189552 proc get_table_name -object_type:required {
        return [::xo::db_string get_table_name {
          select lower(table_name) as table_name from acs_object_types where object_type = :object_type
        } ""]
      }
    
  • proc object_type_exists_in_db (public)

    ::xo::db::Class[i] object_type_exists_in_db [ -object_type object_type ]
    Check, if an object_type exists in the database.

    Switches:
    -object_type (optional)
    Returns:
    0 or 1
    ::2189552 proc object_type_exists_in_db -object_type {
        return [::xo::db_string check_type {
          select 1 from acs_object_types where object_type = :object_type
        } 0]
      }
    
  • instproc check_table_atts (public)

    <instance of ::xo::db::Class[i]> check_table_atts
    Check table_name and id_column and set meaningful defaults, if these attributes are not provided.

    ::2189552 instproc check_table_atts {} {
        my check_default_values
        set table_name_error_tail ""
        set id_column_error_tail ""
        my instvar sql_package_name
    
        if {![my exists sql_package_name]} {
          set sql_package_name [self]
          #my log "-- sql_package_name of [self] is '$sql_package_name'"
        }
        if {[string length $sql_package_name] > 30} {
          error "SQL package_name '$sql_package_name' can be maximal 30 characters long! Please specify a shorter sql_package_name in the class definition."
        }
        if {$sql_package_name eq ""} {
          error "Cannot determine SQL package_name. Please specify it explicitely!"
        }
    
        if {![my exists table_name]} {
          set tail [namespace tail [self]]
          regexp {^::([^:]+)::} [self] _ head
          my table_name [string tolower ${head}_$tail]
          #my log "-- table_name of [self] is '[my table_name]'"
          set table_name_error_tail ", or use different namespaces/class names"
        }
    
        if {![my exists id_column]} {
          my set id_column [string tolower [namespace tail [self]]]_id
          set id_column_error_tail ", or use different class names"
          #my log "-- created id_column '[my id_column]'"
        }
    
        if {![regexp {^[[:alpha:]_][[:alnum:]_]*$} [my table_name]]} {
          error "Table name '[my table_name]' is unsafe in SQL:  Please specify a different table_name$table_name_error_tail." 
        }
    
        if {[string length [my table_name]] > 30} {
          error "SQL table_name '[my table_name]' can be maximal 30 characters long! Please specify a shorter table_name in the class definition."
        }
    
        if {![regexp {^[[:alpha:]_][[:alnum:]_]*$} [my id_column]]} {
          error "Name for id_column '[my id_column]' is unsafe in SQL:  Please specify a different id_column$id_column_error_tail" 
        }
      }
    
  • instproc create_object_type (public)

    <instance of ::xo::db::Class[i]> create_object_type
    Create an acs object_type for the current XOTcl class

    ::2189552 instproc create_object_type {} {
        my instvar object_type supertype pretty_name pretty_plural  table_name id_column name_method abstract_p
    
        my check_default_values
        my check_table_atts
    
        # The default supertype is acs_object. If the supertype
        # was not changed (still acs_object), we map the superclass 
        # to the object_type to obtain the ACS supertype.
        if {$supertype eq "acs_object"} {
          set supertype [::xo::db::Class class_to_object_type [my info superclass]]
        }
    
        ::xo::db::sql::acs_object_type create_type  -object_type $object_type  -supertype $supertype  -pretty_name $pretty_name  -pretty_plural $pretty_plural  -table_name $table_name  -id_column $id_column  -abstract_p $abstract_p  -name_method $name_method  -package_name [my sql_package_name]
      }
    
  • instproc drop_object_type (public)

    <instance of ::xo::db::Class[i]> drop_object_type \
        [ -cascade cascade ]
    Drop an acs object_type; cascde true means that the attributes are droped as well.

    Switches:
    -cascade (defaults to "true") (optional)
    ::2189552 instproc drop_object_type {{-cascade true}} {
        my instvar object_type 
        ::xo::db::sql::acs_object_type drop_type  -object_type $object_type  -cascade_p [expr {$cascade ? "t" : "f"}]
      }
    
  • instproc get_instances_from_db (public)

    <instance of ::xo::db::Class[i]> get_instances_from_db \
        [ -select_attributes select_attributes ] \
        [ -from_clause from_clause ] [ -where_clause where_clause ] \
        [ -orderby orderby ] [ -page_size page_size ] \
        [ -page_number page_number ]
    Returns a set (ordered composite) of the answer tuples of an 'instance_select_query' with the same attributes. Note, that the returned objects might by partially instantiated.

    Switches:
    -select_attributes (optional)
    -from_clause (optional)
    -where_clause (optional)
    -orderby (optional)
    -page_size (defaults to "20") (optional)
    -page_number (optional)
    Returns:
    ordered composite
    ::2189552 instproc get_instances_from_db {{-select_attributes ""} {-from_clause ""} {-where_clause ""} {-orderby ""} {-page_size 20} {-page_number ""}} {
        set s [my instantiate_objects  -object_class [self]  -sql [my instance_select_query  -select_attributes $select_attributes  -from_clause $from_clause  -where_clause $where_clause  -orderby $orderby  -page_size $page_size  -page_number $page_number  ]]
        return $s
      }
    
  • instproc instance_select_query (public)

    <instance of ::xo::db::Class[i]> instance_select_query \
        [ -select_attributes select_attributes ] [ -orderby orderby ] \
        [ -where_clause where_clause ] [ -from_clause from_clause ] \
        [ -count on|off ] [ -page_size page_size ] \
        [ -page_number page_number ]
    Returns the SQL-query to select ACS Objects of the object_type of the class.

    Switches:
    -select_attributes (optional)
    -orderby (optional)
    for ordering the solution set
    -where_clause (optional)
    clause for restricting the answer set
    -from_clause (optional)
    -count (boolean) (defaults to "false") (optional)
    return the query for counting the solutions
    -page_size (defaults to "20") (optional)
    -page_number (optional)
    Returns:
    SQL query
    ::2189552 instproc instance_select_query {{-select_attributes ""} {-orderby ""} {-where_clause ""} {-from_clause ""} {-count:boolean false} {-page_size 20} {-page_number ""}} {
        set tables [list]
        set id_column [my id_column]
    
        if {$count} {
          set select_attributes "count(*)"
          set orderby ""         ;# no need to order when we count
          set page_number  ""    ;# no pagination when count is used
        } 
    
        set all_attributes [expr {$select_attributes eq ""}]
        set join_expressions [list]
        foreach cl [concat [self] [my info heritage]] {
          #if {$cl eq "::xo::db::Object"} break
          if {$cl eq "::xotcl::Object"} break
          set tn [$cl table_name]
    
          if {$tn  ne ""} {
            lappend tables $tn
    	if {$all_attributes} {
    	  foreach {slot_name slot} [$cl array get db_slot] {
                # avoid duplicate output names
                set name [$slot name]
                if {![info exists names($name)]} {
                  lappend select_attributes [$slot attribute_reference $tn]
                }
                set names($name) 1
    	  }
    	}
            if {$cl ne [self]} {
              lappend join_expressions "$tn.[$cl id_column] = [my table_name].$id_column"
            }
          }
        }
    
        if {$page_number ne ""} {
          set limit $page_size
          set offset [expr {$page_size*($page_number-1)}]
        } else {
          set limit ""
          set offset ""
        }
    
        set sql [::xo::db::sql select  -vars   [join $select_attributes ,]  -from  "[join $tables ,] $from_clause"  -where  [string trim "[join $join_expressions { and }] $where_clause"]  -orderby $orderby  -limit $limit -offset $offset]
        return $sql
      }
    
  • instproc instantiate_objects (public)

    <instance of ::xo::db::Class[i]> 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 ] [ -initialize initialize ]
    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 (boolean) (defaults to "true") (optional)
    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 (defaults to "::xotcl::Object") (optional)
    specifies the XOTcl class, for which instances are created.
    -named_objects (boolean) (defaults to "false") (optional)
    -object_named_after (optional)
    -destroy_on_cleanup (boolean) (defaults to "true") (optional)
    -initialize (defaults to "true") (optional)
    ::2189552 instproc instantiate_objects {{-dbn ""} {-sql ""} {-full_statement_name ""} {-as_ordered_composite:boolean true} {-object_class "::xotcl::Object"} {-named_objects:boolean false} {-object_named_after ""} {-destroy_on_cleanup:boolean true} {-initialize true}} {
    
        if {$object_class eq ""} {set object_class [self]}
        if {$sql eq ""} {set sql [my 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 [my id_column]
          }
        }
    
        db_with_handle -dbn $dbn db {
          set selection [db_exec select $db $full_statement_name $sql]
          while {1} {
            set continue [ns_db getrow $db $selection]
            if {!$continue} break
            if {$named_objects} {
              set object_name ::[ns_set get $selection $object_named_after]
              set o [$object_class create $object_name]
            } else {
              set o [$object_class new]
            }
            if {$as_ordered_composite} {
              $__result add $o
            } else {
              if {$destroy_on_cleanup} {
                $o destroy_on_cleanup
              }
              lappend __result $o
            }
            foreach {att val} [ns_set array $selection] {$o set $att $val}
            if {[$o exists object_type]} {
              # set the object type if it looks like managed from XOTcl
              if {[string match "::*" [set ot [$o set object_type]] ]} {
                $o class $ot
              }
            }
            if {$initialize && [$o istype ::xo::db::Object]} {
    	  if {![$o exists package_id]} {
    	    ns_log error "$o has no package_id but [$o exists object_package_id]"
    	    if {[$o exists object_package_id]} {$o set package_id [$o set object_package_id]}
    	  }
              if {[catch {$o initialize_loaded_object} errorMsg]} {
    	    ns_log error "$o initialize_loaded_object => [$o info vars] -> $errorMsg"
    	  }
            }
            #my log "--DB more = $continue [$o serialize]" 
          }
        }
    
        return $__result
      }
    
  • instproc new_persistent_object (public)

    <instance of ::xo::db::Class[i]> new_persistent_object \
        [ -package_id package_id ] [ -creation_user creation_user ] \
        [ -creation_ip creation_ip ] args [ args... ]
    Create a new instance of the given class, configure it with the given arguments and insert it into the database. The XOTcl object is destroyed automatically on cleanup (end of a connection request).

    Switches:
    -package_id (optional)
    -creation_user (optional)
    -creation_ip (optional)
    Parameters:
    args
    Returns:
    fully qualified object
    ::2189552 instproc new_persistent_object {-package_id -creation_user -creation_ip args} {
        my get_context package_id creation_user creation_ip
        db_transaction {
          set id [my new_acs_object  -package_id $package_id  -creation_user $creation_user  -creation_ip $creation_ip  ""]
          #[self class] set during_fetch 1
          if {[catch {eval my create ::$id $args} errorMsg]} {
    	my log "Error: $errorMsg, $::errorInfo"
          }
          #[self class] unset during_fetch
          my initialize_acs_object ::$id $id
          ::$id insert
        }
        ::$id destroy_on_cleanup
        return ::$id
      }
    
  • instproc object_types (public)

    <instance of ::xo::db::Class[i]> object_types \
        [ -subtypes_first on|off ]
    Return the type and subtypes of the class, on which the method is called. If subtypes_first is specified, the subtypes are returned first.

    Switches:
    -subtypes_first (boolean) (defaults to "false") (optional)
    Returns:
    list of object_types
    ::2189552 instproc object_types {{-subtypes_first:boolean false}} {
        return [::xo::db_list get_object_types  [my object_types_query -subtypes_first $subtypes_first]]
      }
    

Instances

::xo::db::Object[i], ::xo::db::apm_parameter[i], ::xo::db::sql::acs[i], ::xo::db::sql::acs_activity[i], ::xo::db::sql::acs_attribute[i], ::xo::db::sql::acs_event[i], ::xo::db::sql::acs_group[i], ::xo::db::sql::acs_log[i], ::xo::db::sql::acs_message[i], ::xo::db::sql::acs_object[i], ::xo::db::sql::acs_object_type[i], ::xo::db::sql::acs_object_util[i], ::xo::db::sql::acs_permission[i], ::xo::db::sql::acs_privilege[i], ::xo::db::sql::acs_reference[i], ::xo::db::sql::acs_rel[i], ::xo::db::sql::acs_rel_type[i], ::xo::db::sql::acs_sc_binding[i], ::xo::db::sql::acs_sc_contract[i], ::xo::db::sql::acs_sc_impl[i], ::xo::db::sql::acs_sc_impl_alias[i], ::xo::db::sql::acs_sc_implementation[i], ::xo::db::sql::acs_sc_msg_type[i], ::xo::db::sql::acs_sc_operation[i], ::xo::db::sql::acs_user[i], ::xo::db::sql::admin_rel[i], ::xo::db::sql::apm[i], ::xo::db::sql::apm_application[i], ::xo::db::sql::apm_package[i], ::xo::db::sql::apm_package_type[i], ::xo::db::sql::apm_package_version[i], ::xo::db::sql::apm_parameter_value[i], ::xo::db::sql::apm_service[i], ::xo::db::sql::application_group[i], ::xo::db::sql::authority[i], ::xo::db::sql::category[i], ::xo::db::sql::category_link[i], ::xo::db::sql::category_synonym[i], ::xo::db::sql::category_tree[i], ::xo::db::sql::composition_rel[i], ::xo::db::sql::content_extlink[i], ::xo::db::sql::content_folder[i], ::xo::db::sql::content_item[i], ::xo::db::sql::content_item_search[i], ::xo::db::sql::content_keyword[i], ::xo::db::sql::content_revision[i], ::xo::db::sql::content_search[i], ::xo::db::sql::content_symlink[i], ::xo::db::sql::content_template[i], ::xo::db::sql::content_type[i], ::xo::db::sql::doc[i], ::xo::db::sql::file_storage[i], ::xo::db::sql::image[i], ::xo::db::sql::journal_entry[i], ::xo::db::sql::membership_rel[i], ::xo::db::sql::notification[i], ::xo::db::sql::notification_delivery_method[i], ::xo::db::sql::notification_interval[i], ::xo::db::sql::notification_reply[i], ::xo::db::sql::notification_request[i], ::xo::db::sql::notification_type[i], ::xo::db::sql::party[i], ::xo::db::sql::party_approved_member[i], ::xo::db::sql::person[i], ::xo::db::sql::recurrence[i], ::xo::db::sql::rel_constraint[i], ::xo::db::sql::rel_segment[i], ::xo::db::sql::rss_gen_subscr[i], ::xo::db::sql::search_observer[i], ::xo::db::sql::site_node[i], ::xo::db::sql::site_node_object_map[i], ::xo::db::sql::subsite_callback[i], ::xo::db::sql::template_demo_note[i], ::xo::db::sql::time_interval[i], ::xo::db::sql::timespan[i], ::xo::db::sql::timezone[i], ::xo::db::sql::util[i], ::xo::db::sql::xorb_servicecontract[i], ::xo::db::sql::xorb_serviceimplementation[i]

Methods: Source: Variables:
[All Methods | Documented Methods | Hide Methods] [Display Source | Hide Source] [Show Variables | Hide Variables]