rhdb-admin Backend Abstraction Layer -- Programmer's Guide
==========================================================

Neil Padgett <npadgett@redhat.com>
Original Version: March 20, 2002
Rev. 1.1 (Last updated April 2, 2002)

A tip
=====

Don't print this. It will be changing, so it'd likely be a waste of
paper.

About this Guide
================

This guide documents the methods available from each handle type in
the backend abstraction layer. For an overview of the backend
abstraction layer, see the document "An Overview of the rhdb-admin
Backend Abstraction Layer."


A note about "references"
=========================

A "reference" for the purposes of this document, when used in context
as a data type, refers to the name of a pseudo-anonymous object. (The
name is machine generated.) The name is guaranteed only to be valid in
the caller's scope. Unless otherwise mentioned the caller is
responsible for disposing of this object after use.


A note about "system objects"
=============================

The various list procedures (getTableList) will also have an analog
for listing the system internal DB objects of the same type
(i.e. getSystemTableList.) However, to handle objects from either
list, the same handle, a TableHandle, is used. There are no specific
handle object types used to handle system DB objects.


ClusterCollection
=================

Factory for: Cluster

Description: Collection of connection information for all database
clusters known to the system.

copy { object: objectname }:
     Copy constructor

registerCluster { clusterName: string, clusterArgs: string }:
		Add a cluster to the collection.

unregisterCluster { clusterName }:
		  Remove a cluster from the collection.

getClusterList {}:
	       Return a list of names of clusters in the collection.

getArgList {}:
	   Return a list of the connection arguments to collect to the
	   clusters in the collection.

(The argList and the clusterList are parallel lists -- that is,
elements 0 in ArgList corresponds to element 0 in ClusterList. You'll
see this concept of parallel lists a lot.)

getArgListByCluster { name: string}:
		    Returns the connection arguments list for a 

getClusterObject {name : string}:
		 Returns a reference for a new cluster object which
		 handles the cluster named in the parameter.

streamOut { filename: string} :
	  Streams the object to disk (to file filename)

streamIn { filename : string} :
	 Stream the object in from disk (from file filename)



Cluster
=======

Factory for: GroupHandle, UserHandle, DatabaseHandle

getDatabaseHandle {dbname : string }:
		  Returns a reference for a new DatabaseHandle object
		  which handles the database named in the parameter.

getSQLInteractorSystemDB {}:
			 Returns an SQLInteractor (used for performing
			 SQL queries) with a connection to
			 template1. This should only be used by the
			 database backend abstraction layer.

getDatabaseList {} :
		Returns a list of all databases in the cluster.

getUserHandle { userName : string }: 
	      Returns a reference for a new UserHandle object which
	      handles the user named in the parameter.

getGroupHandle { groupName : string }:
	       Returns a reference for a new GroupHandle object which
	       handles the group named in the parameter.

getUserList {}:
	    Returns a list of all users in the cluster.

getGroupList {}:
	     Returns a list of all groups in the cluster.

getBackendVersion {}:
		  Returns a string describing the backend version of
		  the cluster.

getName {}:
	Returns the nickname of a given cluster.


DatabaseHandle
==============

Factory for: TableHandle, ViewHandle, SequenceHandle, FunctionHandle
DataTypeHandle

getSQLInteractor {}:
			Returns an SQLInteractor (used for performing
			SQL queries) with a connection to
			the handled database. This should only be used by the
			database backend abstraction layer.

getSQLInteractorSystemDB {}:
			 Returns an SQLInteractor (used for performing
			 SQL queries) with a connection to
			 template1. This should only be used by the
			 database backend abstraction layer.

getTableHandle { tableName : string}:
	       Returns a reference for a new TableHandle object which
	       handles the table named in the parameter.

getViewList {}:
	    Returns a list of the names of views in the database.

getSystemViewList {}:
		  Returns a list of system views in the database.

getViewHandle { viewName : string }:
	      Returns a reference for a new ViewHandle object which
	      handles the view named in the parameter.

getSequenceHandle { sequenceName : string }:
		  Returns a reference for a new SequenceHandle object
		  which handles the sequence named in the parameter.

getFunctionList {}:
		Retuns a list of functions in the database.
N.B: System functions are currently not separated from other functions
		(i.e. there is no getSystemFunctionList) -- this will
		change.

getFunctionHandle { functionName : string}:
		  Returns a reference for a new FunctionHandle object
		  which handles the function named in the parameter.

getDataTypeHandle { dataTypeName : string}:
		  Returns a reference for a new DataTypeHandle object
		  which handles the data type named in the parameter.

getSystemDataTypeList {}:
		      Returns a list of all system data types valid in the
		      database.

getDataTypeList {}:
		Returns a list of all user data types valid in the
		database.

getSystemTableList {}:
		   Returns a list of all system tables in the current
		   database.

validate {}:
	 Returns a boolean indicating true if the database handle
	 currently has a a database backend object attached to
	 it. (i.e. there is something being handled)

drop {}:
     Drops a database.

create { args }:
       Create a database using the given args. This function is
       currently not defined completely. (TODO)

getName {}:
	Returns the name of the currently handled database.


ColumnHandle
============

Factory for: TableHandle, ViewHandle, SequenceHandle, FunctionHandle
DataTypeHandle

validate {}: Analogous.

drop {}: Analogous.

create { args }: Create a user using the given args. This function is
       currently not defined completely. (TODO)	    

getName {}: Analogous.

getDataType {}: Returns a data type handle for the data type associated with
	     the column. This is inconsistent, and should probably be changed
	     to return the data type name akin to 
	     FunctionHandle::getReturnDatatype.

getIndexHandle { indexName }: Returns an index handle for a named index which 
	       includes the handled column. This is a deprecated convenience
	       method.

TableHandle
===========

validate {}: Analogous.

drop {}: Analogous.

create { args }:  Create a table using the given args. This function is
       currently not defined completely. (TODO)	    

getName {}: Analogous.

getOwner {}: Returns the username of the table owner.

getRowCountEstimate {}: Returns an estimate of the number of rows in the
		    collect. (Collected by a vacuum.)

getSizeInPagesEstimate {}: Returns an estimate of the size of the table in
		       pages. (Collected by a vacuum.)

getInheritedTablesCount {}: Returns a count of the number of tables inheriting
			from this table. (TODO.)

getACLList {}: Returns a list of the users / groups with access to this table.
	   This function is currently not defined completely. (TODO)	    

getColumnList {} : Analogous.

getColumnHandle { columnName }: Analogous.

getIndexList {}: Analogous.

getIndexHandle { indexName }: Analogous.

getTriggerList {}: Analogous.

getTriggerHandle { triggerName }: Analogous.

getRuleList {}: Analogous.

getRuleHandle { ruleName }: Analogous.

ViewHandle
==========

validate { } : Analogous.

drop { }: Analogous.

create { }: Create a view using the given args. This function is
       currently not defined completely. (TODO)	   

getName { }: Analogous.

getOwner { }: Analogous.

getDefinition { }: Returns the query that defines the view.

getColumnList { }: Returns a list of the columns in a view.

SequenceHandle
==============

validate {}: Analogous.

drop {}: Analogous.

create {}: Create a sequence using the given args. This function is
       currently not defined completely. (TODO)

getName {}: Analogous.

getOwner {}: Analogous.

getDataType {}: Returns a data type handle for a datatype object corresponding	to the datatype of the sequence.

FunctionHandle
==============

validate { }: Analogous.

drop {}: Analogous.

create {}: Create a function using the given args. This function is
       currently not defined completely. (TODO)

getName {}: Analogous.

getOwner {}: Analogous.

getReturnTypename {}: Returns the name of the data type returned by the
		  function.

isCachable {}: Reports true if the backend considers it can cache the return
	     value of the function.

isStrict {}: Reports the value of proisstrict from pg_proc for the function.

getArgCount {}: Returns a count of the number of arguments the function has.

getArgTypenameByIndex { index }: Returns the name of the data
		      type of the indexed argument.

getFunctionSignatureByOID { oid databaseHandle }: Returns the function
			   signature of a given function, by its OID. A
			   database handle for the desired database is
			   needed. 

getFunctionOIDBySignature { signature databaseHandle }: The inverse of 
			  getFunctionSignatureByOID.

DataTypeHandle
==============



UserHandle
==========

validate {} : Analogous.

drop {}: Analogous.

create {}:

getName {}: Analogous

getUserID {}: Get the user ID of the user.

getCanCreateDB {}: Whether or not the user can create databases.

getIsSuperuser {}: Whether or not the user is a super user.

getCanUpdateSystemCatalogs {}: Whether or not the user can update system
			   catalogues.

getPasswordExpiryDate {}: The expiry data of the user's password.

GroupHandle
===========

TriggerHandle
=============

IndexHandle
===========

RuleHandle
==========
