NAME

Quiq::Database::Row::Object - Datensatz als Objekt

BASE CLASS

Quiq::Database::Row

DESCRIPTION

Ein Objekt der Klasse repräsentiert einen Datensatz.

METHODS

Konstructor

new() - Konstruktor

Synopsis

$row = $class->new($db,@keyVal); # [1]
$row = $class->new(\@titles,\@values,@keyVal); # [2]
$row = $class->new(\@titles,@keyVal); # [3]
$row = $class->new(@keyVal); # [4]

Description

Instantiiere ein Datensatz-Objekt mit den Kolumnen @titles und den Kolumnenwerten @values und liefere eine Referenz auf dieses Objekt zurück.

Attributmethoden

exists() - Prüfe, ob Datensatz-Attribut existiert

Synopsis

$bool = $row->exists($key);

Description

Liefere "wahr", wenn Datensatz-Attribut $key existiert, anderfalls "falsch".

get() - Liefere Datensatz-Attributwerte

Synopsis

$val = $row->get($key);
@vals = $row->get(@keys);

Description

Liefere die Datensatz-Attributwerte zu den angegebenen Schlüsseln. In skalarem Kontext liefere keine Liste, sondern den Wert des ersten Schlüssels.

Ein Datensatz-Wert kann der Wert einer Kolumne oder das Ergebnis einer Berechnung sein.

try() - Liefere Wert oder undef

Synopsis

$val = $row->try($key);

Description

Liefere den Wert des Attributs $key, falls es existiert, sonst undef.

set() - Setze Datensatz-Attribute

Synopsis

$row->set(@keyVal);

Description

Setze die angegebenen Datensatz-Attribute. Es wird eine Exception ausgelöst, wenn ein Attribut zu setzen versucht wird, das nicht existiert. Die Methode liefert keinen Wert zurück.

init() - Initialisieren Datensatz-Attribute aus Objekt

Synopsis

$row->init($obj);

Description

Setze die Datensatz-Komunen in $row auf die Werte der Attribute in $obj. Eine Kolumne wird nur gesetzt, wenn $obj für sie einen Wert hat, d.h. das Attribut muss existieren und es muss einen von '' und undef verschiedenen Wert haben.

Die Methode liefert keinen Wert zurück.

initFromCgi() - Initialisieren Datensatz-Attribute aus CGI-Objekt

Synopsis

$row->initFromCgi($cgi);

Description

Wie init(), nur dass ein CGI-Objekt per Methode param() befragt wird.

addAttribute() - Füge Datensatz-Attribute hinzu

Synopsis

$row->addAttribute(@keys);

Description

Füge die Attribute @keys zum Datensatz hinzu, sofern noch nicht existent. Die Methode liefert keinen Wert zurück.

removeColumn() - Entferne Datensatz-Kolumne(n)

Synopsis

$row->removeColumn(@keys);

Description

Entferne die Kolumnen @keys aus dem Datensatz. Die Methode liefert keinen Wert zurück.

add() - Setze Datensatz-Attribute forciert

Synopsis

$row->add(@keyVal);

Alias

setValue()

Description

Forciere das Setzen der Datensatz-Attribute @keyVal, d.h. erzeuge ein Datensatz-Attribut, falls es nicht existiert. Die Methode liefert keinen Wert zurück.

memoize() - Füge Datensatz-Attribute mit berechnetem Wert hinzu

Synopsis

$val = $row->memoize($key,$sub);

Description

Existiert das Datensatz-Attribut $key, liefere seinen Wert. Andernfalls berechne dessen Wert mittels der anonymen Subroutine $sub und speichere ihn auf dem Attribut.

getSet() - Methode zum Liefern/Setzen eines einzelnen Datensatz-Attributs

Synopsis

$val = $row->getSet($key);
$val = $row->getSet($key,$val);

Examples

• Implementierung einer einfachen Attributmethode

  Dies setzt voraus, dass das Attribut vorhanden ist. Falls dies nicht der Fall ist, kann es mit $row->add(xxx=>$val) eingeführt werden. Diese Form der Attributmethode wird von selbst per AUTOLOAD erzeugt, braucht also nicht implementiert werden

  sub xxx {
      return shift->getSet(xxx=>@_);
  }

• Eine Attributmethode, die eine Liste oder eine Arrayreferenz liefert

  sub xxx {
      my $self = shift;
      # @_: $arr
      my $arr = $self->getSet(xxx=>@_);
      return wantarray? @$arr: $arr;
  }

rowStatus() - Liefere/Setze Datensatzstatus

Synopsis

$rowStatus = $row->rowStatus;
$rowStatus = $row->rowStatus($rowStatus);

Description

Liefere/Setze den Status des Datensatzes. Der Status beschreibt den Änderungsstand des Datensatzes hinsichtlich seiner Kolumnenwerte.

Folgende Status sind definiert:

'0' (unverändert)

Der Datensatz wurde von der Datenbank selektiert und nicht modifiziert.

'U' (modifiziert)

Der Datensatz wurde von der Datenbank selektiert und durch eine der Attributmethoden modifiziert.

'I' (neu)

Der Datensatz wurde durch new() erzeugt. Er existiert auf der Datenbank nicht.

'D' (zu löschen)

Der Datensatz wurde zum Löschen markiert. Dies geschah durch Aufruf von $row->rowStatus('D'). Mit dem nächsen Aufruf von $row->save($db); wird die Löschoperation auf der Datenbank ausgeführt.

titles() - Liefere Kolumnentitel

Synopsis

$titleA|@titles = $row->titles; # [1]
$titleA|@titles = $class->titles($db); # [2]

Description

1. Liefere die Liste der Kolumentitel des Datensatzes, entweder als Referenz (Skalarkontext) oder als Array (Listkontext).

2. Liefere die Liste der Kolumnentitel der Datensatz-Klasse.

isModified() - Prüfe, ob Kolumne modifiziert wurde

Synopsis

$bool = $row->isModified($title);

Description

Liefere 1, wenn die Kolumnen $title modifiziert wurde, andernfalls 0.

modifiedColumns() - Liefere die Liste der geänderten Kolumnen

Synopsis

@keys|$keyA = $row->modifiedColumns;
@pairs|$pairA = $row->modifiedColumns(-withValue=>1);

Options

-columns => @colSpec (Default: alle Kolumnen)

Einschränkung auf die angegebenen Kolumnen. Ist als Kolumnenname eine Arrayreferenz

[$key=>$retKey]

angegeben, wird Kolumne $key geprüft, aber $retKey als Kolumnenname geliefert. Dies ist bei View-Datensätzen nützlich, wenn $row ein View-Datensatz ist, aber ein Tabellen-Datensatz manipuliert werden soll und die Kolumnennamen differieren.

-withValue => $bool (Default: 0)

Liefere nicht nur die Kolumnennamen, sondern auch deren Wert. Die Methode liefert in dem Fall die Datensatz-Änderungen als Schlüssel/Wert-Paare.

Example

Generiere eine SET-Klausel für ein UPDATE-Statement aus einem View-Datensatz, dessen Kolumnen teilweise anders beannt sind, als die der zu aktualierenden Tabelle:

@setClause = $row->modifiedColumns(
    -columns=>[
        lieferantid,
        [lieferantenartikelnr=>'liefernr'],
        [ekpreis=>'preis_ek'],
    ],
    -widthValues=>1,
);

setClauseFromModifiedRow() - Liefere SET-Klausel über geänderten Kolumnen

Synopsis

@clauses|$clauseA = $row->setClauseFromModifiedRow(@columns);

See Also

modifiedColumns()

Example

Auf einen View-Datensatz wurden Werte geschrieben. Wir wissen nicht, welche Information sich geändert hat. Die Methode setClauseFromModifiedRow() liefert uns die SET-Klausel für ein UPDATE:

@setClause = $row->setClauseFromModifiedRow(
    [lieferantenid=>'lieferantid'],
    [lieferantenartikelnr=>'liefernr'],
    [ekpreis=>'preis_ek'],
    [lieferantenid1=>'lieferantid_1'],
    [lieferantenartikelnr1=>'liefernr_1'],
    [ekpreis1=>'preis_ek_1'],
    [lieferantenid2=>'lieferantid_2'],
    [lieferantenartikelnr2=>'liefernr_2'],
    [ekpreis2=>'preis_ek_2'],
);
$db->update('shopartikellieferanteninfo',
    @setClause,
    -where,artikelid => $artId,
);

Wurde keine der Kolumnen geändert, liefert setClauseFromModifiedRow() eine leere Liste und $db->update() ist eine Nulloperation.

absorbModifications() - Absorbiere Datensatz-Änderungen

Synopsis

$row->absorbModifications;

Description

Setze den Datensatz-Status auf 0 (unverändert) und lösche den Änderungs-Hash. Nach Aufruf der Methode sind alle vorangegangenen Änderungen am Datensatz nicht mehr feststellbar.

Die Methode kann benutzt werden, um Datenkorrekturen, z.B. durch normalizeNumber(), verschwinden zu lassen.

See Also

$tab->absorbModifications()

modificationInfo() - Liefere Information über Datensatz-Änderungen

Synopsis

$str = $row->modificationInfo;

Eltern-Datensätze

parentExists() - Prüfe, ob Eltern-Datensatz existiert

Synopsis

$row = $row->parentExists($type);

Description

Prüfe, ob ein Eltern-Datensätze vom Typ $type existiert. Falls ja, liefere wahr, andernfalls falsch.

addParent() - Füge Eltern-Datensatz hinzu

Synopsis

$row->addParent($type,$parentRow);

Description

Füge Datensatz $parentRow als Eltern-Datensatz vom Typ $type hinzu. Die Referenz wird als schwache Referenz gekennzeichnet.

getParent() - Liefere Eltern-Datensatz

Synopsis

$parentRow = $row->getParent($type);

Description

Liefere den Eltern-Datensatz vom Typ $type. Existiert keine Elterndatensatz vom Typ $type, liefere undef.

Kind-Datensätze

childTypeExists() - Prüfe, ob Kind-Datensatz-Typ existiert

Synopsis

$bool = $row->childTypeExists($type);

Description

Prüfe, ob Kind-Datensätze des Typs $type zum Datensatz hinzugefügt werden können. Falls ja, liefere wahr, andernfalls falsch.

addChildType() - Füge Kind-Datensatz-Typ hinzu

Synopsis

$tab = $row->addChildType($type,$rowClass,\@titles);

Description

Bevor Kind-Datensätze einem Datenstatz zugeordnet werden können, muss ein entsprechendes ResultSet-Objekt hinzugefügt werden. Dieses wird per $type angesprochen. Z.B. liefert

$tab = $row->getChilds($type);

die Menge der zugeordenten Kind-Objekte vom Typ $type.

addChild() - Füge Kind-Datensatz hinzu

Synopsis

$row->addChild($type,$childRow);

Description

Füge Datensatz $childRow als Kinddatensatz vom Typ $type hinzu.

getChilds() - Liefere Kind-Datensätze

Synopsis

@rows|$rowT = $row->getChilds($type);

Description

Liefere die Kind-Datensätze vom Typ $type.

Subklassen-Methoden

Die folgenden Methoden implementieren die abstrakten Methoden der Basisklasse Quiq::Database::Row. Die Methoden hat die Klasse mit der Klasse Quiq::Database::Row::Array gemeinsam.

asArray() - Liefere Datensatz als Array

Synopsis

$arr|@arr = $row->asArray;

Description

Liefere den Datensatz als Array, entweder in Form einer Referenz (Skalarkontext) oder als Array von Werten (Listkontext).

asString() - Liefere Datensatz als Zeichenkette

Synopsis

$str = $row->asString;
$str = $row->asString($colSep);

Description

Liefere den Datensatz als Zeichenkette. Per Default werden die Kolumnen per TAB getrennt. Der Trenner kann mittels $colSep explizit angegeben werden.

copy() - Kopiere Datensatz

Synopsis

$newRow = $row->copy;

Description

Erstelle eine Kopie des Datensatzes $row und liefere eine Referenz auf die Kopie zurück.

Die Kopie ist identisch zum Original, bis darauf, dass der Daten-Hash und der Änderungs-Hash kopiert werden:

Daten-Hash.........................: kopiert
Referenz auf Titel-Liste...........: identisch
Datensatz-Status...................: identisch
Änderungs-Hash.....................: kopiert
Referenz auf Kind-Datensätze-Hash..: identisch
Referenz auf Eltern-Datensätze-Hash: identisch

isRaw() - Liefere, ob Klasse Raw-Datensätze repräsentiert

Synopsis

$bool = $row->isRaw;

Sonstiges

asRecord() - Liefere Datensatz in Record-Darstellung

Synopsis

$str = $row->asRecord(@opt);

Options

-color => $a

AnsiColor-Objekt.

-indent => $n (Default: 4)

Tiefe der Einrückung der Werte.

-null => $str (Default: 'NULL')

Gibt an, welcher Wert für einen Nullwert ausgegeben wird. Ist -null undef, wird das Attribut nicht ausgegeben (weder Name noch Wert). Ist $null ein Leerstring (''), wird nur der Wert nicht ausgegeben.

Description

Liefere den Datensatz in mehrzeiliger Record-Darstellung. Die Darstellung hat den Aufbau:

<key1>:
    <val1>
<key2>:
    <val2>
...

copyData() - Kopiere Attributwerte von Datensatz zu Datensatz

Synopsis

$row->copyData($row0,@opt);

Options

-ignore => \@keys (Default: [])

Übergehe die Attribute @keys, d.h. kopiere die Werte dieser Attribute nicht.

-dontCopyNull => $bool (Default: 0)

Kopiere keine Nullwerte, d.h. im Falle eines Nullwerts in Datensatz $row0 bleibt der Attributwert in $row erhalten. Mögliche Erweiterung: Liste von Kolumnennamen.

Description

Setze die Datensatz-Attribute in $row auf deren Werte in $row0. Attribute, die in $row0 nicht vorkommen, werden nicht gesetzt. Die Methode liefert keinen Wert zurück.

Die Methode ist nützlich, wenn ein Datensatz auf der Datenbank aktualisiert werden soll und dessen neue Werte auf einem anderen Datensatz stehen.

save() - Aktualisiere Datensatz auf Datenbank

Synopsis

$cur = $row->save($db);

Description

Aktualisiert den Datensatz $row gemäß seines Status auf der Datenbank $db und liefere das Resultat der Statement-Ausführung zurück.

Welche Datenbankoperation konkret ausgeführt wird, ergibt sich aus dem Status des Datensatzes.

Statuswerte

'0' (unverändert)

Es wird keine Datenbankoperation ausgeführt.

'U' (modifiziert)

Es wird eine Update-Operation auf der Datenbank ausgeführt, d.h. es wird die Methode $row->update() gerufen.

'I' (neu)

Es wird eine Insert-Operation auf der Datenbank ausgeführt, d.h. es wird die Methode $row->insert() gerufen.

['D' (zu löschen)]

Es wird eine Delete-Operation auf der Datenbank ausgeführt, d.h. es
wird die Methode $row->delete() gerufen.

weaken() - Erzeuge schwache Referenz

Synopsis

$ref = $row->weaken($key);
$ref = $row->weaken($key=>$ref);

Description

Mache die Referenz von Schlüssel $key zu einer schwachen Referenz und liefere sie zurück. Ist eine Referenz $ref als Parameter angegeben, setze die Referenz zuvor.

DML Statements

select() - Liefere Datensätze der Klasse

Synopsis

$tab|@rows|$cur = $class->select($db,@select,@opt);

Options

-cursor => $bool (Default: 0)

Liefere Cursor statt Liste der Datensätze.

-tableClass => $tableClass (Default: undef)

Name der Klasse, die die Ergebnismenge speichert.

lookup() - Liefere Datensatz der Klasse

Synopsis

$row|@vals = $class->lookup($db,@select,@opt);

Options

-sloppy => $bool (default: 0)

Wirf keine Exception, wenn der Datensatz nicht existiert, sondern undef (Skalarkontext) bzw. eine leere Liste (Listkontext).

value() - Liefere Kolumnenwert

Synopsis

$val = $class->value($db,@select,@opt);

Options

Siehe $db->value().

Kompatibilität

toSbit() - Generiere Sbit-Datensatz

Synopsis

$sbitRow = $row->toSbit($sbitClass);

Arguments

$sbitClass

Datensatz-Klasse der Sbit-Klassenbibliothek

Returns

Referenz auf Sbit-Datensatz

Description

Generiere aus Datensatz $row einen Sbit-Datensatz der Klasse $sbitClass und liefere diesen zurück.

Details

Die Methode ist nützlich, wenn über die Klassenbibliothek selektiert, aber die weitere Verarbeitung über Klassen auf Basis der Sbit-Klassenbibliothek erfolgt.

Autoload

AUTOLOAD() - Generiere Attributmethode

Synopsis

$val = $row->AUTOLOAD;
$val = $row->AUTOLOAD($val);

Description

Generiere Attributmethode, rufe diese auf und liefere den Attributwert.

VERSION

1.222

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Quiq

perl -MCPAN -e shell
install Quiq