[Koha-devel] Repetitious behavior repeatedly

[Andrew Arensburger]

On Tue, Oct 01, 2002 at 01:32:49PM +0200, paul POULAIN wrote:
> Nathan Gray wrote:
> 
> >I believe what you are considering is object-oriented programming,
> >which can make a lot of sense, if you build your objects correctly.
> >You decide which information is allowed to be stored in the object,
> >and which methods (functions) will be handled internally by the
> >object.  Then you just pass around one variable, usually called
> >'$self'.  When you want a dbh, you could run:
> >
> >  my $dbh = $self->dbh;
> >
> That's it ! Great idea. Thus, there will be only a few things to change 
> in koha.
> Every script starts with
> my $param_object = buildparam->new();
> 
> Every C4 sub is called with
> $result = C4Function($param_object,$other_param1, $other_param2,...);
> 
> And every C4 sub needs only to have 2 lines rewritten :
> sub MySub();
> my ($param,$other1, $other2) = @_;
> my $dbh = $param->dbh;
> 
> instead of
> sub MySub();
> my ($dbh,$other1, $other2) = @_;

	I agree that this is a good idea, but I think the API could be
better.
	95+% of the time, a script needs to:
	1) Read the config file
	2) Open a connection to the database
	3) Read any locally-stored tables (stopwords, branches, etc.)
	4) Do whatever the script is supposed to do
	5) Close the connection to the database

Steps 1-3 can be done in &C4::Context::import, so that the script only
needs to have

	use C4::Context;
	# ...Do useful stuff...

Step 5 can be done in an END{} block in C4::Context.

	In the vast majority of cases, the script will only have one
context (configuration, connection to database, theme, etc.), so from
the script-writer's perspective, it'd be nice not to have to worry
about those details.
	&C4::Context::import can create a new connection to the
database and store it in its own variable; then, when some other
function needs the database handle, it can use a class method (not an
object method) to fetch it:

	use C4::Context;
	...
	my $dbh = &C4::Context::db_handle();
	$dbh->prepare(...);

(And, of course, a bunch of other C4::Context methods for retrieving
other information from the current context.)
This will handle 95% of the cases, without cluttering up the API
needlessly.
	As for the other 5%: C4::Context can have methods for
manipulating the context:

	use C4::Context;	# Allocates a default context
	...
	my $special_context = C4::Context->new("/etc/koha2.conf");
				# Allocate a specialized context

	# Look up a book in the normal context
	@books = &catalog_lookup($biblionumber);

	# Look up a book in the specialized context
	C4::Context->set_context($special_context);
	@books = &catalog_lookup($biblionumber);
	C4::Context->restore_context();

This way, simple scripts remain simple, and complex scripts become
possible.

> >The 'dbh' method would know how to get a new database handle, or would
> >return the existing one, if it has already made a connection.
> >
> Very nice idea too. With this one, we fill, for example stopword list 
> only when ->stopwordlist() is called : no unuseful DB readings.
> Note that the DB handle is so necessary that i think this one should 
> always be created when object is created.

	You're probably right, but if the database handle is opened in
&C4::Context::import, then this can be changed later.
	Another reason for having a method that returns a database
handle is error-checking: if the handle was closed for whatever reason
(e.g., the database server crashed), then the handle access method can
try to reopen it (e.g., contact a backup server). But this is for the
far future, for now.

> >You could very easily create a 'prepare' method in self, that would in
> >turn run 'prepare' on the dbh.
> >  sub prepare {
> >      my $self = shift;
> >      my $query = shift || return;
> >      my $dbh = $self->dbh || return;
> >      my $sth = $dbh->prepare($query);
> >      unless ($sth) {
> >          warn $dbh->errstr;
> >      }
> >      return $sth;
> >  }

	Hurm. I wouldn't do this, because it would seem to imply that
C4::Context is a subclass of DBI::db, which isn't the case.

> >Each method would handle its own error handling, when appropriate.
> >Adding methods for 'param' and 'stopwords' would also be really easy.
> >Let me know if you need any help, if you decide to go this route.  I
> >now write most of my code in an object-oriented style, because I find
> >it much easier to keep track of where everything is.  Then you can
> >also inherit methods from other objects, and all sorts of fun stuff
> >(perhaps down the road a ways).

	I like a lot of things about OO, but I'm not fanatical about
it. The main thing it has going for it is encapsulation: it allows you
to hide unnecessary details from the programmer. Methods also give you
a fair amount of control over what happens (e.g., reconnecting to the
database if the connection was broken).

> I'm very poor at Perl-OOP, so any help is greatly welcomed ;-)

	Take a look at part 2 of
http://www.ooblick.com/text/perl/

\begin{soapbox}
	The reason I've been going on and on about the API is that,
IMHO, it is currently too hard for a potential contributor to get
started with Koha: right now, it's a jumble of undocumented functions
that go together in non-obvious ways, with no roadmap for new
contributors. There is precious little documentation in the release
tarball, and while there is some documentation elsewhere (e.g., the
Wiki), it isn't mentioned in the release notes.
	Koha is open source precisely so that people outside of the
core development team can contribute to it. As such, it's in the
project's interest to make it easy for people to contribute. In my
experience, most people don't want to spend a long time hacking on any
given project; they just want to fix one annoying bug and move on to
something else. These people will spend an hour or two looking at the
code; if they can identify and fix the bug, then they'll send in a
patch. Otherwise, they'll send in a bug report without a patch. Or, if
they're not committed to this package yet, they'll switch a different
one.
	In other words, the easier Koha is to hack, the more people
will contribute.
	See also: http://freshmeat.net/articles/view/238/ , in
particular the "Open Source Projects" section.
\end{soapbox}

-- 
Andrew Arensburger                      This message *does* represent the
arensb at ooblick.com                      views of ooblick.com
"Penser ne suffit pas: il faut penser à quelque chose."  -- Jules Renard