<class>DocDB.Database</class> implements the DocDB ObjectScript User Database API. More...

Inheritance diagram for Database:

[legend]

Collaboration diagram for Database:

[legend]

Public Attributes
	ClassName
	The name of the class that implements the Database. More...

	DocumentType
	DocumentType is the type class of the Doc property or one of (JSON, XML). More...

	Name
	The name of the database. More...

	Resource
	The Resource required to access this Database. More...

	SqlNameQualified
	This is the SQL Schema.Table name as constructed during class compile. More...

Private Member Functions
_.DocDB.Database	Clear (databaseName)
	Clear() - Remove all documents from the current Database. More...

	CreateProperty (_.Library.String propertyName, _.Library.String propertyType, _.Library.String propertyExpression, unique)
	CreateProperty. More...

	DeleteDocument (_.Library.Integer documentID)
	DeleteDocument. More...

	DeleteDocumentByKey (_.Library.String keyName, _.Library.String keyValue)
	DeleteDocumentByKey. More...

_.DocDB.Database	DropProperty (_.Library.String propertyName)
	DropProperty. More...

_.Library.DynamicAbstractObject	FindDocuments (_.Library.DynamicAbstractObject restrictionRequest, _.Library.DynamicAbstractObject projectionRequest, _.Library.DynamicObject optionsRequest)

_.DocDB.Database	FromJSON (_.Library.RawString jsonValue)

_.Library.DynamicAbstractObject	GetDocument (_.Library.Integer documentID)
	GetDocument. More...

_.Library.DynamicAbstractObject	GetDocumentByKey (_.Library.String keyName, _.Library.String keyValue)
	GetDocumentByKey. More...

_.DocDB.Document	SaveDocument (_.Library.RawString request, _.Library.Integer documentID)

_.DocDB.Document	SaveDocumentByKey (_.Library.RawString request, _.Library.String keyName, _.Library.String keyValue)

_.Library.Integer	Size ()
	Return the size of the database where size is the number of documents.

_.Library.RawString	ToJSON (_.Stream.Object destination)
	Serialize the database and its content as JSON. More...

Static Private Member Functions
_.DocDB.Database	CreateDatabase (_.Library.String databaseName, _.Library.String documentType, _.Library.String resource)
	Create a new database. More...

_.Library.DynamicArray	DropAllDatabases ()

_.Library.Boolean	DropDatabase (_.Library.String databaseName)

_.SQL.StatementResult	ExecuteQuery (_.Library.RawString sql, _.Library.RawString parameter)
	Accepts an SQL statement and a variable number of parameter values. More...

_.Library.DynamicArray	GetAllDatabases ()
	Return an array (<class>Library.DynamicArray</class>) containing the names of all of the Databases defined in the current namespace.

_.DocDB.Database	GetDatabase (databaseName)
	Retrieve the Database whose name is databaseName. More...

Additional Inherited Members
Public Member Functions inherited from Persistent
_.Library.Status	AcquireLock (_.Library.String locktype)
	Acquires a lock for the current instance. More...

_.Library.Status	LoadData (_.Library.String id)
	LoadData() - loads an object from storage. More...

_.Library.Status	OnAfterSave (_.Library.Boolean insert)
	This callback method is invoked by the <METHOD>Save</METHOD> method to. More...

_.Library.Status	OnBeforeSave (_.Library.Boolean insert)
	This callback method is invoked by the <METHOD>Save</METHOD> method to. More...

_.Library.Status	OnOpen ()
	This callback method is invoked by the <METHOD>Open</METHOD> method to. More...

_.Library.Status	OnReload ()
	This callback method is invoked by the <METHOD>Reload</METHOD> method to. More...

_.Library.Status	OnRollBack ()
	This callback method is invoked by the <METHOD>Save</METHOD> method to. More...

_.Library.Status	ReleaseLock (_.Library.String locktype)
	Releases a lock for the current instance. More...

_.Library.Status	SaveData (_.Library.String id)
	SaveData() - saves an object to disk, checks uniqueness and referential More...

Public Member Functions inherited from SwizzleObject
_.Library.Status	OnJournalObject (_.Library.Integer tranid, _.Library.Integer jrnid, _.Library.String filter)
	This callback method is invoked by the <METHOD>JournalObject</METHOD> method to. More...

Public Member Functions inherited from RegisteredObject
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...

_.Library.Status	OnClose ()
	This callback method is invoked by the <METHOD>Close</METHOD> method to. More...

_.Library.Status	OnConstructClone (_.Library.RegisteredObject object, _.Library.Boolean deep, _.Library.String cloned)
	This callback method is invoked by the <METHOD>ConstructClone</METHOD> method to. More...

_.Library.Status	OnNew ()
	This callback method is invoked by the <METHOD>New</METHOD> method to. More...

_.Library.Status	OnValidateObject ()
	This callback method is invoked by the <METHOD>ValidateObject</METHOD> method to. More...

Static Public Member Functions inherited from Persistent
_.Library.Status	DeleteData (_.Library.String id, _.Library.Integer concurrency)
	This method is normally generated by the storage class for persistent classes using. More...

_.Library.Status	KillExtentData (_.Library.Boolean killstreams)
	KillExtentData() - kills extent data in storage. More...

_.Library.Status	OnAfterBuildIndices (_.Library.String indexlist)
	This callback method is invoked by the <METHOD>BuildIndices</METHOD> method after all work is completed. More...

_.Library.Status	OnAfterDelete (_.Library.ObjectIdentity oid)
	This callback method is invoked by the <METHOD>Delete</METHOD> method to. More...

_.Library.Status	OnAfterPurgeIndices (_.Library.String indexlist)
	This callback method is invoked by the <METHOD>PurgeIndices</METHOD> method after all work is completed. More...

_.Library.Status	OnBeforeBuildIndices (_.Library.String indexlist)

_.Library.Status	OnBeforePurgeIndices (_.Library.String indexlist)

_.Library.Status	OnDelete (_.Library.ObjectIdentity oid)
	This callback method is invoked by the <METHOD>Delete</METHOD> method to. More...

Static Public Attributes inherited from Persistent
	XCOMPACTANCESTRY
	XCOMPACTANCESTRY can be set to a string to replace the value of the %CLASSNAME property (x__classname field) More...

	DATALOCATIONGLOBAL = None
	Global name containing master map data for this class. More...

	DEFAULTGLOBAL = None

	DSCONDITION = None
	DSCONDITION is the expression that will be evaluated before deciding whether certain actions must be taken. More...

	DSINTERVAL = None
	DSINTERVAL is the number of seconds between one DSTIME value and the next. More...

	DSTIME = None
	If the DSTIME parameter is set to AUTO then the most recent filing operation in the current DSTIME value. More...

	EXTENTQUERYSPEC = None
	The EXTENTQUERYSPEC parameter defines the properties to be retrieved in. More...

	EXTENTSIZE = None
	The EXTENTSIZE parameter is used to inform the SQL Query Optimizer More...

	GUIDENABLED = None
	If this parameter is set to 1 then a GUID will be assigned (to the GUID property) to each new object. More...

	IDENTIFIEDBY = None
	The IDENTIFIEDBY parameter can optionally be set to the name. More...

	MANAGEDEXTENT = None
	The MANAGEDEXTENT parameter can be set to 0 (zero) to cause the Extent Manager. More...

	READONLY = None
	READONLY = 1 means that objects can be created, opened but not saved or deleted. More...

	ROWLEVELSECURITY = None
	ROWLEVELSECURITY = 1 \| <property> means that row level security is active and the list More...

	SQLPREVENTFULLSCAN = None
	SQLPREVENTFULLSCAN = 1 means an attempt to prepare a query that will result in a full scan More...

	STORAGEDEFAULT = None
	STORAGEDEFAULT defines the default storage allocation to use for properties in this class. More...

	USEEXTENTSET = None

	VERSIONCLIENTNAME = None
	VERSIONCLIENTNAME can be set to a valid CLIENTNAME (see property CLIENTNAME) value. More...

	VERSIONPROPERTY = None
	VERSIONPROPERTY = <property> means that the <property> in memory will be compared to. More...

Static Public Attributes inherited from SwizzleObject
	DEFAULTCONCURRENCY = None
	DEFAULTCONCURRENCY is the default value for the concurrency formal argument. More...

	JOURNALSTREAM = None
	If OBJJOURNAL is true then the value of the JOURNALSTREAM parameter defines whether or not. More...

	OBJJOURNAL = None
	if OBJJOURNAL is TRUE then inserts, updates and deletes will be logged in ^OBJ.JournalT More...

Static Public Attributes inherited from RegisteredObject
	CAPTION = None
	Optional name used by the Form Wizard for a class when generating forms. More...

	JAVATYPE = None
	The Java type to be used when exported.

	PROPERTYVALIDATION = None
	This parameter controls the default validation behavior for the object. More...

Detailed Description

<class>DocDB.Database</class> implements the DocDB ObjectScript User Database API.

<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.77 [en] (Windows NT 5.0; U) [Netscape]"> <style type="text/css"> table.todo { background-color:yellow; border:1px solid red; } table.todo tr td { vertical-align:top; border:1px solid red; } </style> <title>DocDB</title> </head> <body>

DocDB ObjectScript User Database API

This class implements the public DocDB ObjectScript User Database API.

A Database is a set of Documents, implemented by a objects persistent class that extends <class>DocDB.Document</class>.

Databases are explicitly created by calling <method>CreateDatabase</method>. A previously created Database can be retrieved by calling the <method>GetDatabase</method>.

A Document is inserted into a Database by executing <method>SaveDocument</method>, passing in the document value as a string containing a valid serialized document, or an instance of the type class. The default type class is <class>Library.DynamicAbstractObject</class> and the default serialization is JSON. An existing Document can be replaced by passing in the documentID. If a documentID is provided and that document does not exist then an exception is thrown.

SaveDocument() returns an oref referencing the newly created document. If an error is encountered by SaveDocument() an exception is thrown.

Other methods to access documents are <method>GetDocument</method> and <method>DeleteDocument</method>. There are also ByKey versions of GetDocument, DeleteDocument and SaveDocument.

Database Functions to be implemented: FindDocuments Return a set of all Documents from the Database that match the provided selection criteria. The form of the selection criteria is a list of simple predicates applied to defined properties joined with AND (we may need OR but IN is probably sufficient). The set of predicates supported initially includes Equal, GT, LT, GTE, LTE, and IN. Accepts Database Name, a definition of the structure of the returned documents, and the selection criteria. QueryDatabase(sql-like query spec) Add a new function to allow for SQL-like SELECT query.

Member Function Documentation

◆ Clear()

_.DocDB.Database Clear ( databaseName )

private

Clear() - Remove all documents from the current Database.

The current Database oref is returned to allow chaining.

◆ CreateDatabase()

_.DocDB.Database CreateDatabase	(	_.Library.String	databaseName,
		_.Library.String	documentType,
		_.Library.String	resource
	)

staticprivate

Create a new database.

If a database with the name databaseName already exists then an exception is thrown. The return

value is an OREF referencing the newly created Database instance in memory.

◆ CreateProperty()

CreateProperty	(	_.Library.String	propertyName,
		_.Library.String	propertyType,
		_.Library.String	propertyExpression,
			unique
	)

private

CreateProperty.

Add a new property to the Database class. Accepts Database Name, Property Name, Property Type, an optional Expression used to derive the property value and an optional UNIQUE indicator. If UNIQUE is specified, then an index to support uniqueness is automatically created if one does not already exist. All properties created through this function will be implicitly indexed.

◆ DeleteDocument()

DeleteDocument ( _.Library.Integer documentID )

private

DeleteDocument.

Remove a document from the currently visible extent of the Database class. Accepts Database Name, Document ID. Returns the deleted Document.

◆ DeleteDocumentByKey()

DeleteDocumentByKey	(	_.Library.String	keyName,
		_.Library.String	keyValue
	)

private

DeleteDocumentByKey.

Remove a document identified by KeyPropertyName = KeyValue from the currently visible extent of the Database class. Accepts Database Name, KeyPropertyName and KeyValue. Returns the deleted Document.

◆ DropAllDatabases()

_.Library.DynamicArray DropAllDatabases ( )

staticprivate

WARNING!! This is a destructive call.

Drop all Databases defined in the current namespace. User data is deleted.

◆ DropDatabase()

_.Library.Boolean DropDatabase ( _.Library.String databaseName )

staticprivate

WARNING!! This is a destructive call.

Drop the Database and remove its extent. User data is deleted.

◆ DropProperty()

_.DocDB.Database DropProperty ( _.Library.String propertyName )

private

DropProperty.

Remove a property from the Database class. Accepts a Property Name. The current Database oref is returned to allow chaining.

◆ ExecuteQuery()

_.SQL.StatementResult ExecuteQuery	(	_.Library.RawString	sql,
		_.Library.RawString	parameter
	)

staticprivate

Accepts an SQL statement and a variable number of parameter values.

Returns a SQL.StatementResult.

◆ FindDocuments()

_.Library.DynamicAbstractObject FindDocuments	(	_.Library.DynamicAbstractObject	restrictionRequest,
		_.Library.DynamicAbstractObject	projectionRequest,
		_.Library.DynamicObject	optionsRequest
	)

private

Retrieve documents that match the restrictionRequest restriction. The set of properties included in the result is defined by projectionRequest. Find options can be specified in the optionsRequest argument. The format of these arguments is either a <class>DynamicAbstractObject</class> oref or a string containing JSON.

restrictionRequest - This can be either a predicate or an array of predicates. A predicate is an array with three elements, the first is the property to be restricted, the second is the value the property is compared to and an optional third element is the comparison operator. The comparison operator defaults to "=". The list of supported comparison operators includes =, !=, <, >, <=, >=, <>, STARTSWITH, IN, NULL, and NOT NULL. When multiple predicates are specified they are combined using AND. Properties included in the restriction must be defined in the Database.

projectionRequest - an array of properties to select from the Database. If not specified then the projection will include DocumentId, LastModified and Doc. The properties included in the projectionRequest must be explicitly defined in the Database.

optionsRequest - is an object containing the requested options. At this time, the only option supported is limit. If options.limit is specified then it is the maximum number of matching documents retrieved from the database.

The return value is a <class>Library.DynamicArray</class> whose elements correspond to objects as defined by projectionRequest.

        SAMPLES>set result = db.FindDocuments(["Name","N","%STARTSWITH"],["Name"],{"limit":5})             

        SAMPLES>w result.ToJSON()                                                                          
        {"sqlcode":100,"message":null,"content":[{"Name":"Nebraska"},{"Name":"Nevada"},{"Name":"New Hampshire"},{"Name":"New Jersey"},{"Name":"New Mexico"}]}

◆ FromJSON()

_.DocDB.Database FromJSON ( _.Library.RawString jsonValue )

private

FromJSON() - accepts a stream, a string containing JSON, a stream oref or a string containing a file URI. The contents of jsonValue are then inserted into the current database. This method return an oref referencing the database to support stringing method calls.

If a file URI is passed then a file stream is instantiated and the translation table set to UTF-8. If the file is not encoded as UTF-8 then the user must instantiate a stream object before calling $fromJSON() and set the translation table to the appropriate value.

◆ GetDatabase()

_.DocDB.Database GetDatabase ( databaseName )

staticprivate

Retrieve the Database whose name is databaseName.

If a Database identified by that name does not exist then an

exception is thrown. The return value is an oref referencing the Database object in memory.

◆ GetDocument()

_.Library.DynamicAbstractObject GetDocument ( _.Library.Integer documentID )

private

GetDocument.

Return the Document from the Database with the specified ID. If no document with that ID is found then an exception is thrown.

◆ GetDocumentByKey()

_.Library.DynamicAbstractObject GetDocumentByKey	(	_.Library.String	keyName,
		_.Library.String	keyValue
	)

private

GetDocumentByKey.

Return the Document from the Database that matches the key value provided. Key Property Name, Key Property Value. Returns Document.

◆ SaveDocument()

_.DocDB.Document SaveDocument	(	_.Library.RawString	request,
		_.Library.Integer	documentID
	)

private

SaveDocument() accepts a document value and an optional documentID. The document value is either an instance of the DocumentType class or a serialized value in the format expected by the DocumentType class. The default serial format is JSON. If documentID is specified then the document identified by that value is replaced by the provided document value. If a document with that ID does not exist then an exception is thrown. If no documentID then the provided document value is inserted into the Database. This method returns the instance of the Database class that was inserted or replaced.

    USER>set car = cars.SaveDocument({"make":"Ford","model":"Flatbed","year":"1938","location":{"city":"Winslow","state":"Arizona"})

This method throws an exception if an error is encountered.

◆ SaveDocumentByKey()

_.DocDB.Document SaveDocumentByKey	(	_.Library.RawString	request,
		_.Library.String	keyName,
		_.Library.String	keyValue
	)

private

SaveDocumentByKey()

◆ ToJSON()

_.Library.RawString ToJSON ( _.Stream.Object destination )

private

Serialize the database and its content as JSON.

If destination is not passed then the output is either sent to the

current device or returned as a string.

destination is optional. There are a number of possibilities:
(1) Parameter destination is not defined and the method is called via 'DO'. In this case the JSON string is written to the current output device.
(2) Parameter destination is not defined and the method is called as an expression. In this case the JSON string becomes the value of the expression.
(3) Parameter destination is defined. If it is Stream object then the JSON string will be written to the stream. If destination is not an object and is not null then it is presumed to be a fully qualified file specification. In that case, a <class>Stream.FileCharacter</class> stream is created, linked to that file and the JSON string is written to that stream. On completion, this stream is saved. The full path to the file must be defined. If destination is an object but is not an instance of Stream.Object then an exception will be thrown.

Member Data Documentation

◆ ClassName

ClassName

The name of the class that implements the Database.

◆ DocumentType

DocumentType

DocumentType is the type class of the Doc property or one of (JSON, XML).

JSON is the default DocumentType.

◆ Name

Name

The name of the database.

This value must be a valid class name but it does not need to be package-qualified.

If no package qualifier is present then a system default package, 'ISC.DM', will be used.

◆ Resource

Resource

The Resource required to access this Database.

◆ SqlNameQualified

SqlNameQualified

This is the SQL Schema.Table name as constructed during class compile.

If the class is edited directly and later recompiled

then this value could be stale. Perhaps add a projection to the DocDB.Document class to verify this.

Public Attributes

Private Member Functions

Static Private Member Functions

Additional Inherited Members

Detailed Description

DocDB ObjectScript User Database API

Member Function Documentation

◆ Clear()

◆ CreateDatabase()

◆ CreateProperty()

◆ DeleteDocument()

◆ DeleteDocumentByKey()

◆ DropAllDatabases()

◆ DropDatabase()

◆ DropProperty()

◆ ExecuteQuery()

◆ FindDocuments()

◆ FromJSON()

◆ GetDatabase()

◆ GetDocument()

◆ GetDocumentByKey()

◆ SaveDocument()

◆ SaveDocumentByKey()

◆ ToJSON()

Member Data Documentation

◆ ClassName

◆ DocumentType

◆ Name

◆ Resource

◆ SqlNameQualified