kdl.prox.db
Class DB

java.lang.Object
  kdl.prox.db.DB

public final class DB
extends java.lang.Object

The top-level object-oriented view of a Proximity Three database hosted on Monet. All the methods are static. To use, first call open(), and then refer to the static class's methods. Call close() when done.

Field Summary

static java.lang.String	CONT_ATTR_NST_NAME
static java.lang.String	CONT_NST_NAME
static java.lang.String	LINK_ATTR_NST_NAME
static java.lang.String	LINK_NST_NAME
static java.lang.String	OBJ_ATTR_NST_NAME
static java.lang.String	OBJ_NST_NAME
static int	SCHEMA_MAJOR_VERSION Schema version.
static int	SCHEMA_MINOR_VERSION

Method Summary

static NST	attachLinkAttribute(NST toTable, java.lang.String onColumn, java.lang.String attrName)
static NST	attachObjectAttribute(NST toTable, java.lang.String onColumn, java.lang.String attrName)
static void	beginScope()
static void	clearDB() Called by methods that want empty a database.
static void	close()
static void	commit() Commits any dirty (modified) BATs that haven't been saved.
static NST	createLinks(NST fromTo) Receives an NST with from and to columns, with oids of objects that need to be connected, and it creates links between them.
static Container	createNewTempContainer() Utility akin to File.createTempFile(), returns a new temporary container in a standard 'system' location.
static void	deleteAllData()
static void	deleteLinks(java.lang.String filterDef) Deletes links specified in filterDef, and their attribute values
static void	deleteObjects(java.lang.String filterDef) Deletes objects specified in the filterDef.
static void	deleteTempContainers() Deletes all temporary containers created by createNewTempContainer().
static java.lang.String	description()
static void	endScope()
static java.lang.String	generateTempContainerName() Called by createNewTempContainer(), returns a candidate random name for a new temporary container.
static NST	getAttrsForItems(NST itemsNST, Attributes attrs, java.lang.String filterDef) Overload that returns getAttrsForItems only with attributes specified in the filter string.
static NST	getAttrsForItems(NST itemsNST, Attributes attrs, java.lang.String filterDef, java.lang.String extraAttrsList) Given an NST with items and an Attribute, it joins the NST with the tables for the requested item and returns a new NST with columns for all the attrs.
static Container	getContainer(java.lang.String containerPath)
static Attributes	getContainerAttrs()
static NST	getContainerNST()
static Attributes	getLinkAttrs()
static NST	getLinkNST()
static NST	getLinks(java.lang.String filterDef) Returns an NST with the links that match a given condition on attributes and internal columns such as id, o1_id, o2_id.
static NST	getLinks(java.lang.String filterDef, java.lang.String attrList)
static Attributes	getObjectAttrs()
static NST	getObjectNST()
static NST	getObjects(java.lang.String filterDef) Returns an NST with the objects that match a given condition on attributes and internal columns such as id.
static NST	getObjects(java.lang.String filterDef, java.lang.String attrList)
static NST	getObjectsConnectedTo(int itemId) Returns the list of objects that are connected to itemId Connected means in o2_id of links where o1_id = itemID, and reverse
static java.util.List	getProxNSTNames() Returns a lst with the names of the Proximity NSTs
static Container	getRootContainer()
static java.util.List	getSchemaLog() Returns this database's schema log, which is an ordered history of the schema versions and the dates they were applied.
static Container	getTempParentContainer() Called by createNewTempContainer(), returns the temporary 'system' container that is to hold randomly-named child containers.
static void	initEmptyDB() Called by methods that want to initialize an empty database, i.e., one with no Proximity tables.
static int	insertLink(int o1OID, int o2OID) Row-level method that creates a new link and returns its OID.
static void	insertLink(int linkOID, int o1OID, int o2OID) Row-level method that creates a new link and returns its OID.
static int	insertObject() Row-level method that creates a new object and returns its OID.
static void	insertObject(int objectOID) Row-level method that creates a new object and returns its OID.
static boolean	isLinkExists(int linkId)
static boolean	isObjectExists(int objId)
static boolean	isOpen()
static boolean	isProxNSTBatName(java.lang.String nstName)
static boolean	isProxNSTName(java.lang.String nstName) Returns true if the name passed in corresponds to one of Proximity's NSTs.
static boolean	isProxTablesDefined()
static boolean	isProxTablesEmpty()
static java.util.List	ls() Returns a list of all the top-level NSTs in the system.
static void	open(java.lang.String hostAndPort) Splits hostAndPort into consituent parts and calls other constructor.
static void	open(java.lang.String hostAndPort, boolean isNoSchemaCheck)
static void	populateDB(java.lang.String fileName) Populates the DB with information from a file.

Methods inherited from class java.lang.Object

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

Field Detail

CONT_ATTR_NST_NAME

public static final java.lang.String CONT_ATTR_NST_NAME

See Also:

Constant Field Values

CONT_NST_NAME

public static final java.lang.String CONT_NST_NAME

See Also:

Constant Field Values

LINK_ATTR_NST_NAME

public static final java.lang.String LINK_ATTR_NST_NAME

See Also:

Constant Field Values

LINK_NST_NAME

public static final java.lang.String LINK_NST_NAME

See Also:

Constant Field Values

OBJ_ATTR_NST_NAME

public static final java.lang.String OBJ_ATTR_NST_NAME

See Also:

Constant Field Values

OBJ_NST_NAME

public static final java.lang.String OBJ_NST_NAME

See Also:

Constant Field Values

SCHEMA_MAJOR_VERSION

public static final int SCHEMA_MAJOR_VERSION

Schema version. History (please keep up-to-date):

~2003-08-01: 1.0 (initial schema) 2003-10-07: 1.1 (removed support for subgraph item attributes) 2003-10-07: 1.2 (added link_id column to LINK_NST) 2003-10-31: 1.3 (change from nested BATs to STR tables) 2003-11-04: 1.4 (prox_schema_log table now has head of type date) 2004-04-07: 1.5 (dropped isShared column in prox_container) 2004-12-16: 1.6 (dropped subg column in container, added object and link cols, and container id)

See Also:

Constant Field Values

SCHEMA_MINOR_VERSION

public static final int SCHEMA_MINOR_VERSION

See Also:

Constant Field Values

Method Detail

attachLinkAttribute

public static NST attachLinkAttribute(NST toTable,
                                      java.lang.String onColumn,
                                      java.lang.String attrName)

attachObjectAttribute

public static NST attachObjectAttribute(NST toTable,
                                        java.lang.String onColumn,
                                        java.lang.String attrName)

beginScope

public static void beginScope()

clearDB

public static void clearDB()

Called by methods that want empty a database. Often paired with calls to initEmptyDB(). Removes all BATs from database. WARNING! This method will remove all your data.

See Also:

initEmptyDB()

close

public static void close()

commit

public static void commit()

Commits any dirty (modified) BATs that haven't been saved. Also called by close().

createLinks

public static NST createLinks(NST fromTo)

Receives an NST with from and to columns, with oids of objects that need to be connected, and it creates links between them. For any column in the NST whose name begins with attr_, this method will create/append the corresponding link attribute with the values in the table. For example, a fromTo NST with columns [from, to, attr_link_type, xx] will take the values from attr_link_type and save them in the link attribute link_type

Returns an NST with the link ids

Parameters:

fromTo: - an NST with two columns, named from and to, with the end points for the links, and possibly othher columns with name attr_*

Returns:

the original NST, but with a link_id column, listing the links that were created

createNewTempContainer

public static Container createNewTempContainer()

Utility akin to File.createTempFile(), returns a new temporary container in a standard 'system' location.

Returns:

deleteAllData

public static void deleteAllData()

deleteLinks

public static void deleteLinks(java.lang.String filterDef)

Deletes links specified in filterDef, and their attribute values

Parameters:

filterDef -

deleteObjects

public static void deleteObjects(java.lang.String filterDef)

Deletes objects specified in the filterDef. Deletes attribute values for those objects as well, and all links to/from those objects. NOTE: Use with caution, as links are also deleted!

Parameters:

filterDef -

deleteTempContainers

public static void deleteTempContainers()

Deletes all temporary containers created by createNewTempContainer().

description

public static java.lang.String description()

generateTempContainerName

public static java.lang.String generateTempContainerName()

Called by createNewTempContainer(), returns a candidate random name for a new temporary container. May or may not be unused. Based on File.generateFile().

Returns:

a string with temp_ followed by a random number

endScope

public static void endScope()

getAttrsForItems

public static NST getAttrsForItems(NST itemsNST,
                                   Attributes attrs,
                                   java.lang.String filterDef)

Overload that returns getAttrsForItems only with attributes specified in the filter string.

Parameters:

itemsNST - the items for which to get attributes

attrs - the attributes structure where values are stored

filterDef - a filter to apply to the resulting NST

Returns:

an NST with the objects/links columns, plus a column for each attribute in the filterDef.

See Also:

getAttrsForItems(kdl.prox.dbmgr.NST, kdl.prox.db.Attributes, java.lang.String)

getAttrsForItems

public static NST getAttrsForItems(NST itemsNST,
                                   Attributes attrs,
                                   java.lang.String filterDef,
                                   java.lang.String extraAttrsList)

Given an NST with items and an Attribute, it joins the NST with the tables for the requested item and returns a new NST with columns for all the attrs. The resulting NST has the internal columns from the itemsNST table, plus all attributes mentioned in the filterDef and extraAttrsList.

Examples:

object_type = 'movie' or object_type = 'person' link_type = 'directed_in' and o1_id = 13 and link_color = 'red'

The joins are performed as left outer joins, retaining nil values in the NST. To eliminate nil values, add conditions such as 'link_color != nil'

Parameters:

itemsNST - the items for which to get attributes

attrs - the attributes structure where values are stored

extraAttrsList - a comma-separated list of names of attributes that should be included in the NST

filterDef - a filter to apply to the resulting NST

Returns:

an NST with the objects/links columns, plus a column for each requested attribute. Contains nil values

getContainer

public static Container getContainer(java.lang.String containerPath)

getContainerAttrs

public static Attributes getContainerAttrs()

getContainerNST

public static NST getContainerNST()

getLinkAttrs

public static Attributes getLinkAttrs()

getLinkNST

public static NST getLinkNST()

getLinks

public static NST getLinks(java.lang.String filterDef)

Returns an NST with the links that match a given condition on attributes and internal columns such as id, o1_id, o2_id. See DB#getItems

getLinks

public static NST getLinks(java.lang.String filterDef,
                           java.lang.String attrList)

getObjectAttrs

public static Attributes getObjectAttrs()

getObjectNST

public static NST getObjectNST()

getObjects

public static NST getObjects(java.lang.String filterDef)

Returns an NST with the objects that match a given condition on attributes and internal columns such as id. See DB#getItems

getObjects

public static NST getObjects(java.lang.String filterDef,
                             java.lang.String attrList)

getObjectsConnectedTo

public static NST getObjectsConnectedTo(int itemId)

Returns the list of objects that are connected to itemId Connected means in o2_id of links where o1_id = itemID, and reverse

Parameters:

itemId -

Returns:

an NST with an id column

getProxNSTNames

public static java.util.List getProxNSTNames()

Returns a lst with the names of the Proximity NSTs

getRootContainer

public static Container getRootContainer()

Returns:

my root Container

getSchemaLog

public static java.util.List getSchemaLog()

Returns this database's schema log, which is an ordered history of the schema versions and the dates they were applied. For now simply returns a descriptive String for each log entry. The List is empty if there is no schema log BAT.

Returns:

List containing one String for each log entry. each String contains the date and version. empty if no schema log table found

getTempParentContainer

public static Container getTempParentContainer()

Called by createNewTempContainer(), returns the temporary 'system' container that is to hold randomly-named child containers. Currently we simply use a 'tmp' container under the root.

Returns:

initEmptyDB

public static void initEmptyDB()

Called by methods that want to initialize an empty database, i.e., one with no Proximity tables. Often paired with calls to clearDB().

Assumes that the database has been clear'ed (ie, that the prox_* tables do not exist). If that condition is not true, then an error will be generated and some BATs might stay as permanent but not referenced to by any other BATs or variables.

See Also:

clearDB()

insertLink

public static int insertLink(int o1OID,
                             int o2OID)

Row-level method that creates a new link and returns its OID. This overload creates the link with an arbitrary ID.

Parameters:

o1OID -

o2OID -

Returns:

new link's ID

insertLink

public static void insertLink(int linkOID,
                              int o1OID,
                              int o2OID)

Row-level method that creates a new link and returns its OID. This overload creates the link with the passed ID.

Parameters:

linkOID -

o1OID -

o2OID -

insertObject

public static int insertObject()

Row-level method that creates a new object and returns its OID. This overload creates the object with an arbitrary ID.

Returns:

new object's ID

insertObject

public static void insertObject(int objectOID)

Row-level method that creates a new object and returns its OID. This overload creates the object with the passed ID.

Parameters:

objectOID -

isLinkExists

public static boolean isLinkExists(int linkId)

isObjectExists

public static boolean isObjectExists(int objId)

isProxNSTBatName

public static boolean isProxNSTBatName(java.lang.String nstName)

Parameters:

nstName -

Returns:

true if nstName is one of the non-NST BATs in getProxNSTNames()

isProxNSTName

public static boolean isProxNSTName(java.lang.String nstName)

Returns true if the name passed in corresponds to one of Proximity's NSTs.

isProxTablesDefined

public static boolean isProxTablesDefined()

Returns:

true if the top-level Proximity tables are all defined, regardless of whether they're empty or not. returns false o/w

See Also:

getProxNSTNames()

isProxTablesEmpty

public static boolean isProxTablesEmpty()

Returns:

true if all of the top-level Proximity tables are defined and empty. returns false o/w. NB: not particularly fast

isOpen

public static boolean isOpen()

ls

public static java.util.List ls()

Returns a list of all the top-level NSTs in the system. Considers BATs that do not begin with tmp_ nor bat_ (nor mapi_ nor monet_) and are persistent.

open

public static void open(java.lang.String hostAndPort)

Splits hostAndPort into consituent parts and calls other constructor. If the port number is <= NEW_MONET_PORT_LIMIT (40000) then use the new Monet protocol otherwise, use the old Monet (4.6.2) protocol

Parameters:

hostAndPort -

open

public static void open(java.lang.String hostAndPort,
                        boolean isNoSchemaCheck)

populateDB

public static void populateDB(java.lang.String fileName)

Populates the DB with information from a file.

Parameters:

fileName -

See Also:

PopulateDB