ORG.oclc.db
Class Db

java.lang.Object
  |
  +--ORG.oclc.db.Db

Direct Known Subclasses:

DbDeleted, DbNewton, DbRemoteZ

public abstract class Db

extends Object

Db is an abstract classes which defines methods that need to be implemented by an object in order to be a Z39.50 server.

Field Summary

static int	CLOSED
protected Object	dbNames Object naming database.
protected int	dbVersion
protected static boolean	dumpConfigInfo Global flag indicating whether configuration information should dumped to the Server Log files.
protected static IniFileSection	globals Global variables used by all Db objects.
static String[]	modeNames
static int	OPEN
protected static Object	opsClient The OpsClient object from the server started on random hosts.
protected Db[]	parents
protected Sorts	sortMap Available sorts for this Db.
static int	UPDATE
protected int	users
static int	WAITINGTOCLOSE

Constructor Summary

protected

Db() Db cannot be instantiated because it is an abstract class.

Method Summary

abstract void	accessAllowed(Object dbUserData) Determines whether the user is authorized to search the database and throws the appropriate exception indicating whether some action needs to be taken.
abstract void	accessControl(Object accessControlResponse, Object dbUserData) Process the information from an AccessControl response to set user specific authorization information.
protected void	browse() Increments browse transaction count.
abstract TermInfo[]	browse(String query, int preferredPosition, int numTerms, DataDir Z39attributesPlusTerm, DataDir resultSetAttributes, int stepSize, Object dbUserData) Perform a browse.
protected Key[]	buildSortKeys(String hitlist, String[] keys, int[] order, Object dedupCriteria, Object userData) Return sort keys for the records in the hitlist.
abstract void	close() close this Db.
void	closewhenidle()
abstract void	connect(Object userInformation, Object dbUserData) Create a connection to this Db for a user.
static String[]	dbnames()
protected void	deleteHitlist() Increments deleteHitlist transaction count.
abstract void	deleteHitlist(String hitlist, Object dbUserData) Delete the specified hitlist.
abstract void	disconnect(Object dbUserData) Destroy a connection to this Db for a user.
abstract ExtSvcData	extsvc(ExtSvcData esData, ExtSvcHandler esHandler, Object dbUserData) Performs an Extended Services request.
protected static String	filterName(String name) Filter the dbname of blanks.
abstract TermComponentPostings[]	getComponentResults(String hitlist, Object dbUserData) Get the database component term postings summaries for the specified hitlist.
static Db	getDb(String[] DbList) Get a Db object for this database name.
static String	getDbNames(String[] DbList) Convert a list of database names into a single name.
abstract DbResults[]	getDbResults(String hitlist, Object dbUserData) Get the database search summaries for the specified hitlist.
static Enumeration	getDbs()
static IniFileSection	getGlobals()
String	getName()
static int	getOpenedFilesCount() Get the number of opened Files count.
static int	getOutstandingCount()
String	getStats()
boolean	hasUsers() Check if any users are associated with this Db.
protected abstract boolean	init(IniFile inifile, String which) Initialize this Db object.
abstract Object	initDbUserData(String sessionId, Object access, Log log, Object userDbMap) Creates a database User data object for searching the database - Each database has it's own unique DbUserData object.
int	numUsers()
abstract boolean	OK() Check if the Db is open and ready for requests.
protected static Db	openDb(IniFile ini, String dbSection) Open a database.
static void	openDbs(IniFile ini, String databaseSection, boolean verbose) Open all databases listed in the databaseSection of the IniFile.
abstract int	postings(String hitlist, Object dbUserData) Get postings for a specified hitlist.
protected void	present() Increments present transaction count.
abstract DbPresentData[]	present(String hitlist, int startPoint, int numRecs, String elementSetName, String syntax, Object dbUserData) Get the specified records from the specified hitlist.
boolean	rolldatabase(IniFile inifile, String inifilesection)
int	rolldatabaseusers()
protected void	search() Increments search transaction count.
abstract int	search(String query, String hitlist, boolean replaceFlag, DataDir Z39attributesPlusTerm, boolean doRestrictorSummary, Object additionalSearchInfo, Object dbUserData) Perform a search.
void	setOps(Object opsClient) Save a reference to an operations client object.
static void	setSearchMode(String dbname, int mode)
static Db	SetupDatabase(Db[] dbs, String name) Use this to create a new merged Db from an array of existing Dbs.
static Db	SetupDatabase(IniFile inifile, String which) Use this to create a Db object.
protected void	sort() Increments sort transaction count.
protected Object[]	sort(String hitlist, String[] keys, int[] order, Object dupCriteria, Object userData) Sort the hitlist according to the keys and return a list of offsets.
abstract void	sort(String hitlist, String sortedList, String[] keys, int[] order, boolean fUseSortAttributes, boolean sortAccrossDbs, Object dupCriteria, Object userData) Sort the hitlist according to the keys.
protected abstract boolean	supportsScan() Does this Db support scan requests?
protected abstract boolean	supportsSort() Does this Db support sort requests?
protected abstract void	unsort(String hitlist, Object userData) Unsort the hitlist.
void	updateOpenedFiles(int count) Update the opened files count.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dbNames

protected Object dbNames

Object naming database. If this is not a String, then the implementation should override getName() to return a String of the object.

sortMap

protected Sorts sortMap

Available sorts for this Db.

parents

protected Db[] parents

dbVersion

protected int dbVersion

users

protected int users

globals

protected static IniFileSection globals

Global variables used by all Db objects.

dumpConfigInfo

protected static boolean dumpConfigInfo

Global flag indicating whether configuration information should dumped to the Server Log files.

opsClient

protected static Object opsClient

The OpsClient object from the server started on random hosts.

CLOSED

public static int CLOSED

OPEN

public static int OPEN

UPDATE

public static int UPDATE

WAITINGTOCLOSE

public static int WAITINGTOCLOSE

modeNames

public static String[] modeNames

Constructor Detail

Db

protected Db()

Db cannot be instantiated because it is an abstract class. This constructor is used by the classes that extend Db.

Method Detail

SetupDatabase

public static final Db SetupDatabase(IniFile inifile,
                                     String which)
                              throws Exception

Use this to create a Db object. It reads in the inifile, loads the specified class and creates the Db object.

Parameters:

inifile - Contains 'ZBaseDbType=classname' to load Db object

which - Section in inifile to look for type and other information.

Throws:

Exception - can be thrown if there is any error loading a database

SetupDatabase

public static final Db SetupDatabase(Db[] dbs,
                                     String name)

Use this to create a new merged Db from an array of existing Dbs.

getStats

public String getStats()

Returns:

String containing counts for search, present and browse requests.

getOutstandingCount

public static int getOutstandingCount()

Returns:

int number of outstanding requests.

getName

public String getName()

Returns:

String containing name of this database.

filterName

protected static String filterName(String name)

Filter the dbname of blanks.

Returns:

String

getOpenedFilesCount

public static final int getOpenedFilesCount()

Get the number of opened Files count.

updateOpenedFiles

public void updateOpenedFiles(int count)

Update the opened files count.

Parameters:

the - number of files to add to the count

setOps

public void setOps(Object opsClient)

Save a reference to an operations client object.

Parameters:

opsClient - the ops client object.

present

protected final void present()

Increments present transaction count.

search

protected final void search()

Increments search transaction count.

sort

protected final void sort()

Increments sort transaction count.

browse

protected final void browse()

Increments browse transaction count.

deleteHitlist

protected final void deleteHitlist()

Increments deleteHitlist transaction count.

initDbUserData

public abstract Object initDbUserData(String sessionId,
                                      Object access,
                                      Log log,
                                      Object userDbMap)

Creates a database User data object for searching the database - Each database has it's own unique DbUserData object.

Parameters:

sessionId - assigned by something else

access - the object containing access info to connect to an access server

log - the Log object for the user for tracing

Returns:

userDbMap Object containing all the user's database information objects.

accessAllowed

public abstract void accessAllowed(Object dbUserData)
                            throws AccessControl,
                                   Diagnostic1

Determines whether the user is authorized to search the database and throws the appropriate exception indicating whether some action needs to be taken.

Parameters:

dbUserData - user data object containing hitlists

Throws:

AccessControl - if an authorization is required for the database and one is not currently available.

postings

public abstract int postings(String hitlist,
                             Object dbUserData)
                      throws Diagnostic1

Get postings for a specified hitlist.

Parameters:

hitlist - result set name

dbUserData - user data object containing hitlists

Returns:

postings

Throws:

Diagnostic1 - if the hitlist cannot be located

init

protected abstract boolean init(IniFile inifile,
                                String which)
                         throws Exception

Initialize this Db object.

Parameters:

inifile - for parameters

which - section name for inifile for this Db

Returns:

true if successful

Throws:

Exception - if the Db could not be initialized

supportsScan

protected abstract boolean supportsScan()

Does this Db support scan requests?

Returns:

true

supportsSort

protected abstract boolean supportsSort()

Does this Db support sort requests?

Returns:

true

present

public abstract DbPresentData[] present(String hitlist,
                                        int startPoint,
                                        int numRecs,
                                        String elementSetName,
                                        String syntax,
                                        Object dbUserData)
                                 throws Exception,
                                        Diagnostic1

Get the specified records from the specified hitlist.

Parameters:

hitlist - result set name

startPoint - starts at 1

numRecs - to retrieve

elementSetName - view of record to retrieve

syntax - in which to return record

dbUserData - user data containing hitlists

Returns:

array of BerString records

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

search

public abstract int search(String query,
                           String hitlist,
                           boolean replaceFlag,
                           DataDir Z39attributesPlusTerm,
                           boolean doRestrictorSummary,
                           Object additionalSearchInfo,
                           Object dbUserData)
                    throws Exception,
                           Diagnostic1,
                           AccessControl,
                           PartialResults

Perform a search.

Parameters:

query - type 0 query or null if this is not type 0

hitlist - result set name to create

replaceFlag - can this hitlist overwrite a previous one?

Z39attributesPlusTerm - non-type 0 query

doRestrictorSummary - flag to return a summary of records

additionalSearchInfo - the Z39.50 additional Search Info field

dbUserData - user data containing hitlists

Returns:

postings count of search

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

AccessControl - exception when a db autho/password required to continue.

PartialResults - for a DbMerge created on the fly, one (or more) of the parts had an error

browse

public abstract TermInfo[] browse(String query,
                                  int preferredPosition,
                                  int numTerms,
                                  DataDir Z39attributesPlusTerm,
                                  DataDir resultSetAttributes,
                                  int stepSize,
                                  Object dbUserData)
                           throws Exception,
                                  Diagnostic1,
                                  AccessControl,
                                  PartialResults

Perform a browse.

Parameters:

query - starting term

preferredPosition - of the query term in the returned list

numTerms - to return

Z39attributesPlusTerm - term plus starting point attributes

resultSetAttributes - result set attributes if they are different from the starting point attributes

stepSize - number of terms between terms

dbUserData - user data containing hitlists

Returns:

array of TermInfo terms

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

AccessControl - exception when a db autho/password required to continue.

PartialResults - for a DbMerge created on the fly, one (or more) of the parts had an error

extsvc

public abstract ExtSvcData extsvc(ExtSvcData esData,
                                  ExtSvcHandler esHandler,
                                  Object dbUserData)
                           throws Exception,
                                  Diagnostic1,
                                  AccessControl

Performs an Extended Services request.

Parameters:

function - the ES function - see Z39.50 api

packageType - the type of ES request

esTask - the ES task package

userId - the ES userId

description - the ES description field.

packageName - the ES package name

waitAction - the ES wait action value

Returns:

DataDir containing the response task package

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

AccessControl - exception when a db autho/password required to continue.

deleteHitlist

public abstract void deleteHitlist(String hitlist,
                                   Object dbUserData)
                            throws Exception,
                                   Diagnostic1

Delete the specified hitlist.

Parameters:

hitlist - the one to delete

dbUserData - user data containing hitlists

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

OK

public abstract boolean OK()

Check if the Db is open and ready for requests.

Returns:

true

getDbResults

public abstract DbResults[] getDbResults(String hitlist,
                                         Object dbUserData)

Get the database search summaries for the specified hitlist.

Parameters:

hitlist - result set name

dbUserData - user data containing hitlists

Returns:

array of DbResults[] for this hitlist

getComponentResults

public abstract TermComponentPostings[] getComponentResults(String hitlist,
                                                            Object dbUserData)

Get the database component term postings summaries for the specified hitlist.

Parameters:

hitlist - result set name

dbUserData - user data containing hitlists

Returns:

array of TermComponentPostings[] for this hitlist

accessControl

public abstract void accessControl(Object accessControlResponse,
                                   Object dbUserData)

Process the information from an AccessControl response to set user specific authorization information.

Parameters:

accessControlResponse - object containing the access control response

dbUserData - user data containing hitlists

close

public abstract void close()

close this Db.

hasUsers

public boolean hasUsers()

Check if any users are associated with this Db.

Returns:

true

numUsers

public int numUsers()

connect

public abstract void connect(Object userInformation,
                             Object dbUserData)
                      throws Diagnostic1

Create a connection to this Db for a user.

Parameters:

userInformation - the userInformation data from the Z3950 Init request

dbUserData - the user's database information for searching the database.

disconnect

public abstract void disconnect(Object dbUserData)

Destroy a connection to this Db for a user.

Parameters:

dbUserData - created by connect

sort

public abstract void sort(String hitlist,
                          String sortedList,
                          String[] keys,
                          int[] order,
                          boolean fUseSortAttributes,
                          boolean sortAccrossDbs,
                          Object dupCriteria,
                          Object userData)
                   throws Exception,
                          Diagnostic1

Sort the hitlist according to the keys.

Parameters:

hitlist - result set name

sortedList - result set name for sorted results

keys - sort key parameters

order - ascending or descending

fUseSortAttributes - flag to sort by use attributes

sortAccrossDatabases - flag to indicate to tell the ZBase that the results should be the sort of all the records from all the databases in the group vs. having the sorts be within each db not merged together where true indicates to sort accross database boundaries.

dupCriteria - the dedup criteria to use for a dedup sort. for each record.

userData - user data containing hitlists

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

unsort

protected abstract void unsort(String hitlist,
                               Object userData)

Unsort the hitlist. Go back to the original results.

Parameters:

hitlist - result set name userData user data containing hitlists

buildSortKeys

protected Key[] buildSortKeys(String hitlist,
                              String[] keys,
                              int[] order,
                              Object dedupCriteria,
                              Object userData)
                       throws Exception,
                              Diagnostic1

Return sort keys for the records in the hitlist.

Parameters:

hitlist - result set name

keys - sort key parameters

order - ascending or descending

userData - user data containing hitlists

Returns:

array of Keys

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

sort

protected Object[] sort(String hitlist,
                        String[] keys,
                        int[] order,
                        Object dupCriteria,
                        Object userData)
                 throws Exception,
                        Diagnostic1

Sort the hitlist according to the keys and return a list of offsets.

Parameters:

hitlist - result set name

keys - sort key parameters

order - ascending or descending

dupCriteria - the dedup criteria to use for a dedup sort. for each record.

userData - user data containing hitlists

Returns:

array of ints that represent offsets in the original hitlist

Throws:

Exception - this was probably an I/O error or a coding error

Diagnostic1 - if the request is not logically correct

getDbNames

public static String getDbNames(String[] DbList)

Convert a list of database names into a single name. The names are put in lowercase, sorted and duplicates are deleted. The resulting list is combined into a blank separated list to be the new database name.

Parameters:

DbList - list of database names

Returns:

normalized name for total list

getDb

public static Db getDb(String[] DbList)

Get a Db object for this database name. If the Db does not exist, try to create it from a list of known Db objects.

Parameters:

DbList - list of database names

Returns:

Db object or null if the db does not exist and cannot be created

openDb

protected static Db openDb(IniFile ini,
                           String dbSection)

Open a database.

Parameters:

ini - configuration file

dbSection - section containing database parameters

openDbs

public static void openDbs(IniFile ini,
                           String databaseSection,
                           boolean verbose)

Open all databases listed in the databaseSection of the IniFile.

Parameters:

ini - configuration file

databaseSection - section containing list of databases

verbose - flag indicating whether to dump configuration information to the logs

dbnames

public static String[] dbnames()

Returns:

array of all database names that have been opened

getDbs

public static Enumeration getDbs()

Returns:

Enumeration of all opened databases

setSearchMode

public static void setSearchMode(String dbname,
                                 int mode)

closewhenidle

public void closewhenidle()

rolldatabase

public boolean rolldatabase(IniFile inifile,
                            String inifilesection)

rolldatabaseusers

public int rolldatabaseusers()

getGlobals

public static IniFileSection getGlobals()