WWWWWW

Current Directory: /usr/local/share/man/man3
Viewing File: /usr/local/share/man/man3/HDB::Object.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HDB::Object 3"
.TH HDB::Object 3 "2005-01-23" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HDB::Object \- Base class for persistent Class::HPLOO objects.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for persistent Class::HPLOO objects.
.PP
This will automaticallt make Class::HPLOO classes persistent in any \s-1DB\s0
handled by \s-1HDB\s0.
.PP
This persistence framework was built by a group of modules that handles specific
parts of the problem:
.IP "Class::HPLOO" 4
.IX Item "Class::HPLOO"
The class declaration and attribute handler.
.IP "HDB::Object" 4
.IX Item "HDB::Object"
The object persistence and class proxy.
.IP "\s-1HDB\s0" 4
.IX Item "HDB"
The \s-1DB\s0 connection and \s-1SQL\s0 communication for each \s-1DB\s0 type.
.PP
All of this will create a very automatic way to create persistent objects over a
relational \s-1DB,\s0 what is perfect for fast and easy creation of good systems.
For Web Systems this framework is automatically embeded into \s-1HPL\s0,
where you can count with a lot of resources for fast and powerful creations for
the Web.
.SH "USAGE"
.IX Header "USAGE"
Here's an example of a class built with HDB::Object persistence.
.PP
.Vb 1
\&  use Class::HPLOO ;
\&  
\&  class User extends HDB::Object {
\&  
\&    use HDB::Object ;
\&  
\&    attr( user , pass , name , int age ) ;
\&    
\&    sub User( $user , $pass , $name , $age ) {
\&      $this\->{user} = $user ;
\&      $this\->{pass} = $pass ;
\&      $this\->{name} = $name ;
\&      $this\->{age} = time ;
\&    }
\&  
\&  }
.Ve
.PP
\&\fBYou can see that is completly automatic and you don't need to care about the
serialization or even about the \s-1DB\s0 connection, tables and column types.\fR
.SH "METHODS"
.IX Header "METHODS"
.SS "load (\s-1CONDITIONS\s0)"
.IX Subsection "load (CONDITIONS)"
Loads an object that exists in the database.
.PP
\&\fI\s-1CONDITIONS\s0\fR can be a sequence of \s-1WHERE\s0 conditions for \s-1HDB:\s0
.PP
.Vb 1
\&  my $users_x = load User(\*(Aqid == 123\*(Aq) ;
\&  
\&  my @users = load User(\*(Aqid <= 10\*(Aq , \*(Aqid == 123\*(Aq , \*(Aqname eq "joe"\*(Aq) ;
.Ve
.PP
If \fI\s-1CONDITIONS\s0\fR is \s-1NOT\s0 paste, if wantarray it will return all the objects in the table, or it will return only the 1st:
.PP
.Vb 1
\&  my $user1 = load User() ;
\&  
\&  my @all_users = load User() ;
.Ve
.SS "hdb"
.IX Subsection "hdb"
Return the \s-1HDB\s0 object that handles the \s-1DB\s0 connection.
.SS "hdb_dump_table"
.IX Subsection "hdb_dump_table"
Dump all the table content, returning that as a string.
.SS "hdb_table_exists"
.IX Subsection "hdb_table_exists"
Retrun \s-1TRUE\s0 if the table for the HDB::Object was already created.
.SS "hdb_create_table"
.IX Subsection "hdb_create_table"
Create the table for the HDB::Object if it doesn't exists.
.SS "hdb_obj_changed"
.IX Subsection "hdb_obj_changed"
Return \s-1TRUE\s0 when the object was changed and need to be updated in the \s-1DB.\s0
.SS "hdb_max_id"
.IX Subsection "hdb_max_id"
Return the max id in the object table.
.SS "hdb_delete"
.IX Subsection "hdb_delete"
Delete the object from the database.
.SS "hdb_save"
.IX Subsection "hdb_save"
Save the object in the database.
.PP
\&\fI** Note that you don't need to call this method directly, since when
the object is destroied from the memory it will be saved automatically.\fR
.SS "hdb_clean_unref"
.IX Subsection "hdb_clean_unref"
This will automatically clean objects from this table if they doesn't have
references in the database from another object. So, only call this if
you have a colection of objects that are referenced by others or you
will lose all the objects from the table:
.PP
.Vb 1
\&  Users::Level\->hdb_clean_unref ;
.Ve
.PP
You also can define the constant \fI\s-1AUTO_CLEAN_UNREF\s0\fR to automatically clean
unreferenced objects:
.PP
.Vb 4
\&  class Users::Level extends HDB::Object {
\&    use constant AUTO_CLEAN_UNREF => 1 ;
\&    ...
\&  }
.Ve
.SS "hdb_referenced_ids"
.IX Subsection "hdb_referenced_ids"
Return the IDs that have a reference to it.
.SH "DESTROY and AUTO SAVE OBJECT"
.IX Header "DESTROY and AUTO SAVE OBJECT"
The object will be automatically saved when the object is destroied.
.PP
So if you want to use this automatically save resource you can't overload the
sub \s-1DESTROY,\s0 or at least should call the super method:
.PP
.Vb 2
\&  class User extends HDB::Object {
\&    ...
\&    
\&    sub DESTROY {
\&      $this\->SUPER::DESTROY ;
\&      ... # your destroy stuffs.
\&    }
\&  }
.Ve
.SH "OBJECT REFERENCES"
.IX Header "OBJECT REFERENCES"
\&\fIHDB::Object\fR will try to handle automatically attributes that make references
to other objects or list of objects.
.PP
When an atribute make a reference to an object that extends \fIHDB::Object\fR,
only the \s-1ID\s0 to the object will be saved, making a reference to the \s-1ID\s0
of the object table.
.PP
If an object doesn't extends \fIHDB::Object\fR it will be serialized, using Storable,
and stored in the coloumn value.
.PP
When an attribute have a list of objects, a reference table is created automatically:
.PP
.Vb 1
\&  attr( array Date::OBject dates )
.Ve
.SH "OBJECT PROXY"
.IX Header "OBJECT PROXY"
The Object Proxy mechanism was inspirated on Class::LazyLoad. The main idea
is that the object won't be created unless it's accessed. The proxy will be used only
when the object is loaded from the \s-1DB,\s0 not when you create a new object. So, when
you load an object from the \s-1DB,\s0 actually the \s-1DB\s0 will be accessed only when you use the
object.
.PP
An Object Proxy is very important to save memory and \s-1DB\s0 access, since if we don't
use a proxy is possible to have an object that loads all the \s-1DB\s0 in the memory due
it's object tree.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1HPL\s0, \s-1HDB\s0, Class::HPLOO, Class::LazyLoad.
.SH "AUTHOR"
.IX Header "AUTHOR"
Graciliano M. P. <gm@virtuasites.com.br>
.PP
I will appreciate any type of feedback (include your opinions and/or suggestions). ;\-P
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
F1l3 Manager
