<HTML>
<HEAD>
<TITLE>Class::PObject - Perl extension for programming persistent objects</TITLE>
<LINK REV="made" HREF="mailto:root@mesg18.100mwh.com">
</HEAD>

<BODY>

<A NAME="__index__"></A>
<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#name">NAME</A></LI>
	<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
	<LI><A HREF="#warning">WARNING</A></LI>
	<LI><A HREF="#description">DESCRIPTION</A></LI>
	<LI><A HREF="#programming style">PROGRAMMING STYLE</A></LI>
	<UL>

		<LI><A HREF="#defining objects">DEFINING OBJECTS</A></LI>
		<LI><A HREF="#creating new objects">CREATING NEW OBJECTS</A></LI>
		<LI><A HREF="#storing objects">STORING OBJECTS</A></LI>
		<LI><A HREF="#loading objects">LOADING OBJECTS</A></LI>
		<LI><A HREF="#removing objects">REMOVING OBJECTS</A></LI>
		<LI><A HREF="#defining methods other than accessors">DEFINING METHODS OTHER THAN ACCESSORS</A></LI>
		<LI><A HREF="#error handling">ERROR HANDLING</A></LI>
	</UL>

	<LI><A HREF="#todo">TODO</A></LI>
	<UL>

		<LI><A HREF="#test, test and test">TEST, TEST AND TEST</A></LI>
		<LI><A HREF="#driver specs">DRIVER SPECS</A></LI>
		<LI><A HREF="#more flexible load()">MORE FLEXIBLE <CODE>LOAD()</CODE></A></LI>
		<LI><A HREF="#global desctructor">GLOBAL DESCTRUCTOR</A></LI>
	</UL>

	<LI><A HREF="#driver specs notes">DRIVER SPECS NOTES</A></LI>
	<LI><A HREF="#developer notes">DEVELOPER NOTES</A></LI>
	<LI><A HREF="#see also">SEE ALSO</A></LI>
	<LI><A HREF="#author">AUTHOR</A></LI>
	<LI><A HREF="#see also">SEE ALSO</A></LI>
</UL>
<!-- INDEX END -->

<HR>
<P>
<H1><A NAME="name">NAME</A></H1>
<P>Class::PObject - Perl extension for programming persistent objects</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<P>We can create a person object like so:</P>
<PRE>
  use Class::PObject</PRE>
<PRE>
  pobject Person =&gt; {
    columns =&gt; ['id', 'name', 'email'],
    datasource =&gt; 'data/person'
  };</PRE>
<P>Or even:</P>
<PRE>
  package Person;</PRE>
<PRE>
  pobject {
    columns =&gt; ['id', 'name', 'email''
    datasource =&gt; 'data/person'
  };</PRE>
<P>The above Person can be now used like so:</P>
<PRE>
  my $person = new Person();</PRE>
<PRE>
  $person-&gt;name('Sherzod');
  $person-&gt;email('sherzodr@cpan.org');</PRE>
<PRE>
  my $new_id = $person-&gt;save();</PRE>
<P>We can  read the above saved Person later, make necessary changes and save back:</P>
<PRE>
  $person = Person-&gt;load($new_id);
  $person-&gt;name('Sherzod Ruzmetov (The Geek)');</PRE>
<PRE>
  $person-&gt;save();</PRE>
<P>We can load all the objects with the following code:</P>
<PRE>
  my @people = Person-&gt;load();
  for ( my $i=0; $i &lt; @people; $i++ ) {
    my $person = $people[$i];
    printf(&quot;[%02d] %s &lt;%s&gt;\n&quot;, $person-&gt;id, $person-&gt;name, $person-&gt;email);
  }</PRE>
<P>or we can load all the objects with name 'Sherzod' and sort the list by name in descending order,
and limit the results to only the first 3 objects:</P>
<PRE>
  my @people = Person-&gt;load({name=&gt;&quot;Sherzod&quot;}, {sort=&gt;'name', direction=&gt;'desc', limit=&gt;3});</PRE>
<P>We can also retrieve records by offset:</P>
<PRE>
  my @people = Person-&gt;load(undef, {offset=&gt;10, limit=&gt;10});</PRE>
<P>
<HR>
<H1><A NAME="warning">WARNING</A></H1>
<P>This is 'alpha' release. I mainly want to hear some ideas, criticism and suggestions from people.
Look at TODO section for more details.</P>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>Class::PObject is a class representing a persistent object.  Such objects can be stored into disk,
or even initialized from the disk.</P>
<P>If it is easier for you, just think of a persistent object as a single record of a relational database:</P>
<PRE>
  mysql&gt; select * from song;
  +-----+----------------+--------+----------+
  | id  | title          | artist | album_id |
  +-----+----------------+--------+----------+
  | 217 | Yagonam O'zing | Sevara |        1 |
  +-----+----------------+--------+----------+</PRE>
<P>The above record of a song can be represented as a persistent object. Using Class::PObject, you can defined this
object like so:</P>
<PRE>
  pobject Song =&gt; {
    columns =&gt; ['id', 'title', 'artist', 'album_id']
  };</PRE>
<PRE>
  my $song = new Song(title=&gt;&quot;Yagonam O'zing&quot;, artist=&gt;&quot;Sevara&quot;, album_id=&gt;1);</PRE>
<P>All the disk access is performed through its drivers, thus allowing your objects truly transparent database
access. Currently supported drivers are 'mysql', 'file' and 'csv'. More drivers can be added, and I believe will be added.</P>
<P>
<HR>
<H1><A NAME="programming style">PROGRAMMING STYLE</A></H1>
<P>The style of Class::PObject is very similar to that of <A HREF="/Class/Struct.html">the Class::Struct manpage</A>. Instead of exporting 'struct()', however,  Class::PObject exports 'pobject()'. Another visual difference is the way you define your arguments. In Class::PObject, each property of the class is represented as one column.</P>
<P>
<H2><A NAME="defining objects">DEFINING OBJECTS</A></H2>
<P>Object can be created in several ways. You can create the object in its own .pm file with the following syntax:</P>
<PRE>
  package Article;</PRE>
<PRE>
  pobject {
    columns =&gt; ['id', 'title', 'date', 'author', 'source', 'text']
  };</PRE>
<P>Or you can also create an in-line object - from within your any programs with more  explicit declaration:</P>
<PRE>
  pobject Article =&gt; {
    columns =&gt; ['id', 'title', 'date', 'author', 'source', 'text']
  };</PRE>
<P>Effect of the above two examples is identical - Article object. By default, Class::PObject will fall back to 'file' driver if you do not specify any drivers. So the above Article object could also be redefined more explicitly as:</P>
<PRE>
  pobject Article =&gt; {
    columns =&gt; \@columns,
    driver =&gt; 'file'
  };</PRE>
<P>The above examples are creating temporary objects. These are the ones stored in your system's temporary location. So if you want more 'permanent' objects, you should also declare its datasource:</P>
<PRE>
  pobject Article =&gt; {
    columns =&gt; \@columns,
    datasource =&gt; 'data/articles'
  };</PRE>
<P>Now, the above article object will store its objects into data/articles folder.</P>
<P>Class declarations are tightly dependant to the type of driver being used, so we'll leave the rest of the declaration to specific drivers. In this document, we'll concentrate more on the user interface of the Class::PObject - something not dependant on the driver.</P>
<P>
<H2><A NAME="creating new objects">CREATING NEW OBJECTS</A></H2>
<P>After you define an object, as described above, now you can create instances of those objects. Objects are created with <CODE>new()</CODE> - constructor method. To create an instance of the above Article object, we do:</P>
<PRE>
  $article = new Article();</PRE>
<P>The above syntax will create an empty Article object. We can now fill 'columns' of this object one by one:</P>
<PRE>
  $article-&gt;title(&quot;Persistent Objects with Class::PObject&quot;);
  $article-&gt;date(&quot;Sunday, June 08, 2003&quot;),
  $article-&gt;author(&quot;Sherzod B. Ruzmetov&quot;);
  $article-&gt;source(&quot;lost+found (<A HREF="http://author.handalak.com">http://author.handalak.com</A>)&quot;);
  $article-&gt;text(&quot;CONTENTS OF THE ARTICLE GOES HERE&quot;);</PRE>
<P>Another way of filling in objects, is by passing column values to the constructor - new():</P>
<PRE>
  $article = new Article(title  =&gt;  &quot;Persistent Objects with Class::PObject&quot;,
                         date   =&gt;  &quot;Sunday, June 08, 2003&quot;,
                         author =&gt;  &quot;Sherzod Ruzmetov&quot;,
                         source =&gt;  &quot;lost+found (<A HREF="http://author.handalak.com&quot">http://author.handalak.com&quot</A>; );</PRE>
<PRE>
  $article-&gt;text(&quot;CONTENTS OF THE ARTICLE GO HERE&quot;);</PRE>
<P>Notice, above example is initializing all the properties of the object except for 'text' in the constructor,
and initializing 'text' separately. You can use any combination, as long as you are satisfied.</P>
<P>
<H2><A NAME="storing objects">STORING OBJECTS</A></H2>
<P>Usually, when you create the objects and fill them with data, they are in-memory data structures, and not
attached to any disk device. It's when you call <CODE>save()</CODE> method of those objects when they become so. To store
the above article into disk:</P>
<PRE>
  $article-&gt;save();</PRE>
<P><CODE>save()</CODE> method returns newly created object id on success, undef on failure. So you may want to check its
return value to see if it succeeded:</P>
<PRE>
  my $new_id = $article-&gt;save() or die &quot;couldn't store the article&quot;;</PRE>
<P>Note: we'll talk more about handling exceptions in later sections.</P>
<P>
<H2><A NAME="loading objects">LOADING OBJECTS</A></H2>
<P>No point of storing stuff if you can't retrieve them when you want. Class::PObject objects support <CODE>load()</CODE> method which allows you do that. You can retrieve objects in many ways. The easiest, and the most efficient way of loading an object from the disk is by its id:</P>
<PRE>
  my $article = Article-&gt;load(1251);</PRE>
<P>the above code is retrieving an article with id 1251. You can now either display the article on your web page:</P>
<PRE>
  printf(&quot;&lt;h1&gt;%s&lt;/h1&gt;&quot;,  $article-&gt;title);
  printf(&quot;&lt;div&gt;By %s&lt;/div&gt;&quot;, $article-&gt;author);
  printf(&quot;&lt;div&gt;Posted on %s&lt;/div&gt;&quot;, $article-&gt;date);
  printf(&quot;&lt;p&gt;%s&lt;/p&gt;&quot;, $article-&gt;text);</PRE>
<P>or you can make some changes, say, change its title and save it back:</P>
<PRE>
  $article-&gt;title(&quot;Persistent Objects in Perl made easy with Class::PObject&quot;);
  $article-&gt;save();</PRE>
<P>Other ways of loading objects can be by passing column values, in which case the object will retrieve all the objects from the database matching your search criteria:</P>
<PRE>
  my @articles = Article-&gt;load({author=&gt;&quot;Sherzod Ruzmetov&quot;});</PRE>
<P>The above code will retrieve all the articles from the database written by ``Sherzod Ruzmetov''. You can specify more criteria to narrow your search down:</P>
<PRE>
  my @articles = Article-&gt;load({author=&gt;&quot;Sherzod Ruzmetov&quot;, source=&gt;&quot;lost+found&quot;});</PRE>
<P>The above will retrieve all the articles written by ``Sherzod Ruzmetov'' and with source ``lost+found''. We can of course, pass no arguments to load(), in which  case all the objects of the same type will be returned.</P>
<P>Elements of returned @array are instances of Article objects. We can generate the list of all the articles with the following syntax:</P>
<PRE>
  my @articles = Article-&gt;load();
  for my $article ( @articles ) {
    printf(&quot;[%02d] - %s - %s - %s\n&quot;, $article-&gt;id, $article-&gt;title, $article-&gt;author, $article-&gt;date);
  }</PRE>
<P><CODE>load()</CODE> also supports second set of arguments used to do post-result filtering. Using these sets you can sort the results by any column, retrieve first n number of results, or do incremental retrievals. For example, to retrieve first 10 articles with the highest rating (assuming our Article object supports 'rating' property):</P>
<PRE>
  my @favorites = Article-&gt;load(undef, {sort=&gt;'rating', direction=&gt;'desc', limit=&gt;10});</PRE>
<P>The above code is applying descending ordering on rating column, and limiting the search for first 10 objects. We could also do incremental retrievals. This method is best suited for web applications, where you can present ``previous/next'' navigation links and limit each listing to some number:</P>
<PRE>
  my @articles = Article-&gt;load(undef, {offset=&gt;10, limit=&gt;10});</PRE>
<P>Above code retrieves records 10 through 20.</P>
<P>
<H2><A NAME="removing objects">REMOVING OBJECTS</A></H2>
<P>Objects created by Class::PObject support method called ``remove()'' and ``remove_all()''. ``remove()'' is an object method, can used only to remove one object at a time. ``remove_all()'' removes all the objects of the same type, thus a little more scarier.</P>
<P>Note, that all the objects can still be removed with  ``remove()'' method, without any need for more explicit ``remove_all()''. So why two methods? On some drivers, removing all the objects at once is more efficient than removing objects one by one. Perfect example is 'mysql' driver.</P>
<P>To remove an article with id 1201, we first need to create the object of that article by loading it:</P>
<PRE>
  # we first need to load the article:
  my $article = Article-&gt;load(1201);
  $article-&gt;remove();</PRE>
<P><CODE>remove()</CODE> will return any true value indicating success, undef on failure.</P>
<PRE>
  $article-&gt;remove() or die &quot;couldn't remove the article&quot;;</PRE>
<P>remove_all(), on the other hand, is a static class method:</P>
<PRE>
  Article-&gt;remove_all();</PRE>
<P>
<H2><A NAME="defining methods other than accessors">DEFINING METHODS OTHER THAN ACCESSORS</A></H2>
<P>If you are defining the object in its own class file, you can extend the class with custom
methods. For example, assume you have a User object, which needs to be authenticated before
they can access certain parts of the web site. It may be a good idea to add ``authenticate()'' method
into your User class, which either returns the User object if he/she is logged in properly, or returns
undef.</P>
<PRE>
  package User;</PRE>
<PRE>
  pobject {
    columns     =&gt; ['id', 'login', 'psswd', 'email'],
    datasource  =&gt; 'data/users'
  };</PRE>
<PRE>
  sub authenticate {
    my $class = shift;
    my ($cgi, $session) = @_;</PRE>
<PRE>
    # if the user is already logged in, return the object:
    if ( $session-&gt;param('_logged_in') ) {
      return $class-&gt;load({id=&gt;$session-&gt;param('_logged_in')});
    }</PRE>
<PRE>
    # if we come this far, we'll try to initialize the object with CGI parameters:
    my $login     = $cgi-&gt;param('login')    or return undef;
    my $password  = $cgi-&gt;param('password') or return undef;</PRE>
<PRE>
    # if we come this far, both 'login' and 'password' fields were submitted in the form:
    my $user = $class-&gt;load({login=&gt;$login, psswd=&gt;$password});</PRE>
<PRE>
    # if the user could be loadded, we set the session parameter to his/her id
    if ( defined $user ) {
      $session-&gt;param('_logged_in', $user-&gt;id);
    }
    return $user;
  }</PRE>
<P>Now, we can check if the user is logged into our web site with the following code:</P>
<PRE>
  use User;</PRE>
<PRE>
  my $user = User-&gt;authenticate($cgi, $session);
  unless ( defined $user ) {
    die &quot;You need to login to the website before you can access this page!&quot;;
  }</PRE>
<PRE>
  printf(&quot;&lt;h2&gt;Hello %s&lt;/h2&gt;&quot;, $user-&gt;login);</PRE>
<P>Notice, we're passing CGI and CGI::Session objects to authenticate. You can do it differently depending
on the tools you're using.</P>
<P>
<H2><A NAME="error handling">ERROR HANDLING</A></H2>
<P>Objects created with Class::PObject tries never to die(), and lets the programer to decide what to do on failure, (unless of course, you insult it with wrong syntax).</P>
<P>Methods that may fail are the one to do with disk access, namely, save(), load(), <CODE>remove()</CODE> and remove_all(). So it's advised that you check these methods' return values before you assume any success. If an error occurs, the above methods will return undef. More verbose error message will be accessible through <CODE>error()</CODE> method. In addition, <CODE>save()</CODE> method should always return the object id, either newly created, or updated.</P>
<PRE>
  my $new_id = $article-&gt;save();
  unless ( defined $new_id ) {
    die &quot;couldn't save the article: &quot; . $article-&gt;error();
  }</PRE>
<PRE>
  Article-&gt;remove_all() or die &quot;couldn't remove objects:&quot; . Article-&gt;error;</PRE>
<P>
<HR>
<H1><A NAME="todo">TODO</A></H1>
<P>Following are the lists of features and/or fixes that need to be applied before considering
the library ready for production environment. The list is not exhaustive. Feel free to add your
suggestions.</P>
<P>
<H2><A NAME="test, test and test">TEST, TEST AND TEST</A></H2>
<P>The library should be tested more.</P>
<P>
<H2><A NAME="driver specs">DRIVER SPECS</A></H2>
<P>Currently driver specifications are not very well documented. Need to spend more time to come up
with more intuitive and comprehensive specification.</P>
<P>
<H2><A NAME="more flexible load()">MORE FLEXIBLE <CODE>LOAD()</CODE></A></H2>
<P><CODE>load()</CODE> will not be all we need until it supports at least simple joins. Something similar to the
following may do:</P>
<PRE>
  @articles = Article-&gt;load(join =&gt; ['ObjectName', \%terms, \%args]);</PRE>
<P>I believe it's something to be supported by object drivers, that's where it can be performed more efficiently.</P>
<P>
<H2><A NAME="global desctructor">GLOBAL DESCTRUCTOR</A></H2>
<P>Class::PObjects try to cache the driver object for more extended periods than current object's scope permits them
to. So a ``global'' DESTROY should be applied to prevent memory leaks or other unfavorable consequences, especially under persistent environments, such as mod_perl or GUI environments.</P>
<P>At this point, I don't have how to implement it the best way.</P>
<P>
<HR>
<H1><A NAME="driver specs notes">DRIVER SPECS NOTES</A></H1>
<P><A HREF="/Class/PObject/Driver.html">the Class::PObject::Driver manpage</A></P>
<P>
<HR>
<H1><A NAME="developer notes">DEVELOPER NOTES</A></H1>
<P>coming soon...</P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P><A HREF="/Class/PObject.html">the Class::PObject manpage</A>, <A HREF="/Class/PObject/Driver/mysql.html">the Class::PObject::Driver::mysql manpage</A>,
<A HREF="/Class/PObject/Driver/file.html">the Class::PObject::Driver::file manpage</A></P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Sherzod Ruzmetov &lt;<A HREF="mailto:sherzod@cpan.org">sherzod@cpan.org</A>&gt;</P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P><EM>perl</EM>.</P>

</BODY>

</HTML>
