CVS: phpweather/doc/src phpweather.texi,1.1,1.2

[Martin G. <gim...@us...>]

Update of /cvsroot/phpweather/phpweather/doc/src
In directory sc8-pr-cvs1:/tmp/cvs-serv27251/doc/src

Modified Files:
	phpweather.texi 
Log Message:
Old uncommitted edits...


Index: phpweather.texi
===================================================================
RCS file: /cvsroot/phpweather/phpweather/doc/src/phpweather.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- phpweather.texi	26 Aug 2002 12:46:57 -0000	1.1
+++ phpweather.texi	27 Dec 2002 22:19:21 -0000	1.2
@@ -324,21 +324,30 @@
 @cindex Database backends, differences
 
 @noindent
-PHP Weather works by retrieving weather reports called
-METARs. It takes some time to get the METARs, so
-you'll be interested in using a local database as a cache. PHP Weather
-supports several different databases:
+PHP Weather works by retrieving weather reports called METARs. It
+takes some time to get the METARs, so you'll be interested in using a
+local database as a cache. All database backends support the same
+features (see @ref{Required Backend Functions} for details) but differ
+in speed. Your version of PHP might also lack support for some of the
+backends. PHP Weather supports the following databases backends:
 
 @table @code
 
 @item null
-This is the default ``database'', but it isn't really a database. It
-pretends to cache the METARs, but in reallity it just throws
-them away. This means that PHP Weather will have to fetch them from
-the NWS again each time.
+This is the default ``database'' backend, but it isn't really a
+database. It pretends to cache the METARs, but in reallity it just
+throws them away. This means that PHP Weather will have to fetch them
+from the NWS again each time.
+
+This makes the @code{null} backend the slowest backend if you
+repeadaly need the same METAR, e.g. if you show the current weather
+for a fixed location on your homepage. But it's just as quick (or
+slow, depending on how you view things) as the other backends when it
+comes to showing the weather for a random station. So if that's your
+usage-pattern, then you might like this backend.
 
 @item pw_mysql
-You can use the popular @uref{http://www.mysql.com/, MySQL} relational
+You can use the @uref{http://www.mysql.com/, MySQL} relational
 database with PHP Weather.
 
 @item pw_pgsql
@@ -391,7 +400,40 @@
 files, please use that instead and tell us so that we can update the
 manual.
 
-You can change the output produced by PHP Weather.
+@node Required Functions in a Backend
+@section Required Functions in a Backend
+@cindex database, functions
+
+@noindent
+All database backends have to support a common set of methods --- if
+PHP had support for @emph{interfaces}, then we would require them to
+implement a database interface. Because of the lack of interfaces in
+the PHP language we're left with this description of what a database
+backend has to satisfy.
+
+All database backends are defined in their own class which is a
+subclass of the @code{pw_db_common} class. If we pretend that we have
+a @code{pw_db_foo} database backend, then it must implement
+the following methods:
+
+@defmethod pw_db_foo get_type
+This should return the type of the backend, @samp{foo} in our case.
+@end defmethod
+
+@defmethod pw_db_foo connect
+This is called by every other method that wants to ensure that the
+database is up and running. The method should cache the result of this
+operation as it will be called several times.
+@end defmethod
+
+@defmethod pw_db_foo disconnect
+This disconnects from the database.
+@end defmethod
+
+@defmethod pw_db_foo insert_metar $station $metar $timestamp
+Inserts a METAR into the database.
+@end defmethod
+
 
 @node Using PHP Weather
 @chapter Using PHP Weather