Skip to content

Documentation
Documentation
Commit 15cd5ff2 by Tom Laudeman
Options

Update DBUtil API specs to match code

parent 81394cd7
Showing with 131 additions and 70 deletions
Specifications/DBUtil API.md
...@@ -13,139 +13,200 @@ There is an interactive schema web site: [Schema web site](http://shannonvm.vill ...@@ -13,139 +13,200 @@ There is an interactive schema web site: [Schema web site](http://shannonvm.vill
### New DBUtil and initialization ### New DBUtil and initialization
When creating a DBUtil object, you must supply the application user credentials in the form of the numberic When creating a DBUtil object, DBUtil currently calls $this->getAppUserInfo('system') to determine the user id
user id and numeric role. and role id. This function simply reads the database for user 'system'. When we have an authentiation and
authorization system, application code will supply the user information to DBUtil.
DBUtil will automatically, internally mint new version and constellation main_id as necessary. For batch DBUtil will automatically, internally mint new version and constellation main_id as necessary. For constellation
inserts you should create a single DBUtil object and use it for all inserts of every record in the inserts you should create a single DBUtil object and use it for all inserts of every record in the
batch. Passing in a constellation with no ID or version and asking for an "insert" operation will result in a batch. Passing in a constellation with no ID or version and asking for an "insert" operation will result in a
new ID being minted. In other words, for a new constellation written to the database for the first time, a new new ID being minted. In other words, for a new constellation written to the database for the first time, a new
version will be minted if none exists. version will be minted if none exists.
If a version exists in the current DBUtil object, it will be used for all operations during the life of the A new version is minted for each constellation written. While we could use the same version during the life of
DBUtil object. This is intentional. While the database is not appreciably effected by minting large numbers of an instance of DBUtil, it was decided to mint fresh versions. Programmer reading the database records need to
versions, it does make the data harder for humans to read and debug. For example, a programmer trying to be aware of this, and always check version_history.main_id and version_history.id (aka version).
figure out a dozen operations that take place from a single session will have an easier time if all those
operations share a version number.
### Constellation ID discovery ### Constellation ID discovery
Methods to discover the ID or ARK of existing constellations needs work. DBUtil must have a constellation ID Methods to discover the ID or ARK of existing constellations need work, and are evolving as use cases
in order to read a constellation from the database. Presumably, some search or browse function(s) will exist emerge. DBUtil must have a constellation ID in order to read a constellation from the database. Presumably,
that returns a list of constellation ID. The function will have some constraints so that a manageable list some search or browse function(s) exist that return a list of constellation ID. With some constraints a
will be return, and not all 4.5 million records. manageable length list will be return, and not all 4.5 million records.
W support reading old versions of a constellation via allVersion() which returns a list of prior version
numbers for a given constellation ID. readConstellation() takes a version number argument.
In the future we will support reading old versions of a constellation. In that case, some function must return
a list of prior version numbers for a given constellation ID. Starting now, readConstellation() takes a version
number argument, but the only available version number is the most current. (As of Mar 2 2016.)
### Reading and writing constellations ### Reading and writing constellations
Constellation insert, update, or delete is controlled by the getOperation() of the constellation and each Constellation insert, update, or delete is controlled by the getOperation() of the constellation and each
component object. To save a constellation, call writeConstellation() with the constellation object, a string component object. To save a constellation, call writeConstellation() with the constellation object, and a
for status, and a string for the history note. To retrieve a constellation, call readConstellation() with string for the history note. The version history status is detemined via heuristic in the code, and the status
can be set via writeConstellationStatus(). To retrieve a constellation, call readConstellation() with
constellation ID (aka main_id, $mainID) and version number. constellation ID (aka main_id, $mainID) and version number.
We can use readConstellation() for any version numbe. Requirements for reading old versions are We can use readConstellation() for any version numbe. Requirements for reading old versions are
incomplete. Companion functions will retrieve ID and version, but for the most part, they version number is incomplete. Companion functions will retrieve ID and version, but for the most part, they version number is
only the most recent. Only allVersions() returns a full list of versions for a given ID. only the most recent. Only allVersion() returns a full list of versions for a given ID.
See function signatures and calls below. See function signatures and example calls below.
$cObj is a constellation object $cObj constellation object
$note is a string $note string
$mainID is a constellation ID, an integer $mainID constellation ID, an integer
$version is a version number, an integer $version version number, an integer
$arkID is an ARK, a string. $arkID ARK, a string.
$appUserID is a numeric user identifier $appUserID numeric user identifier
Status is a (more or less?) controlled vocabulary. Examples include: 'published', 'needs review', 'rejected', $status constellation status from a controlled vocabulary (more or less?). Examples include: 'published', 'needs review', 'rejected',
'being edited', 'bulk ingest'. 'locked editing', 'bulk ingest'.
``` ```
public function writeConstellation($cObj, $status, $note) // public function, write a constellation to the db, where "write" is taken broadly
$cObj = writeConstellation($cObj, $note)
public function readConstellation($mainID, $version) // public function, return a constellation read from the db
$cObj = readConstellation($mainID, $version)
<
// public function, return the published constellation by ARK
$cObj = readPublishedConstellationByARK($arkID);
// public function, return the published constellation by ID
$cObj = readPublishedConstellationByID($mainID);
list($mainID, $version) = publishedConstellationByARK($arkID); // public function, return the list of constellations I'm editing
// uses $this->appUserID in the DBUtil object
$cObjList = editConstellationList();
list($mainID, $version) = publishedConstellationByID($mainID); $status = 'locked editing';
$newVersion = writeConstellationStatus($mainID, $status, 'optional arg, version note');
list($mainID, $version) = editingConstellationByARK($arkID); $status = readConstellationStatus($mainID);
$status = readConstellationStatus($mainID, $version);
list($mainID, $version) = editingConstellationByID($mainID);
$idVersionList = editList($appUserID); // private function, return id and version for each constellation I'm editing, private?
// Relies on the $appUserID property in DBUtil, and thus does not take an argument.
$idVersionList = editList();
$idVersionList = array( $idVersionList = array(
array('main_id' => 1, 'version' => 2), array('main_id' => 1, 'version' => 2),
array('main_id' => 3, 'version' => 2), array('main_id' => 3, 'version' => 2),
array('main_id' => 4, 'version' => 5)); array('main_id' => 4, 'version' => 5));
function loadDash($appUserID) // This is the actual function to return all constellations with status 'locked editing'.
// Eventually this will support other status args.
function listConstellationsLockedToUser($status=null)
{ {
$idVersionList = editList($appUserID); $infoList = $this->editList();
if ($infoList)
$constellationList = array();
foreach ($idVersionList as $iver)
{ {
$cObj = readConstellation($iver['main_id'], $iver['version']); $constellationList = array();
array_push($constellationList, $cObj); foreach ($infoList as $idVer)
{
$cObj = $this->readConstellation($idVer['main_id'], $idVer['version']);
array_push($constellationList, $cObj);
}
return $constellationList;
} }
return false;
} }
$versionList = allVersions($mainID); $versionList = allVersion($mainID);
``` ```
The SNAC dashboard will do the logical equivalent of calling editList() followed by calling public function readConstellation($mainID, $version)
readConstellation() for each entry in $idVersionList. A list of constellations results. The dashboard web page
is populated from the big list of constellations. See function loadDash() in the example above. Returns a full constellation, or false upon failure. The UI can be built from the full constellation as
necessary. This is better than having functions specifically only returning partial data for the UI, but full
data for other uses. The functions that return ID and version work alongside readConstellation() as part of a
small tool kit.
public function writeConstellation($argObj, $note)
publishedConstellationByARK($arkID), publishedConstellationByID($mainID) Writes a constellation to the database, returning the same constellation with ID and versions as
appropriate. It will probably crash if the first argument is not a constellation. The constellation must pass
validation tests which writeConstellation() calls before doing any other work.
public function readPublishedConstellationByARK($arkID)
public function readPublishedConstellationByID($mainID)
Given an ARK/ID, return the current publicly available constellation ID and version. This will only return the Given an ARK/ID, return the current publicly available constellation ID and version. This will only return the
current published version. Have equivalent functions for constellations locked-for-edit aka editing. The current published version. Returns a single constellation or false upon failure.
"editing" will only return a list that the user has permissions to edit, and that means constellations locked
by that user. Admins can change the lock to another user, but we will not allow two users access to edit the Functions return the most recent version so that a user can continue editing where they left off. By
same constellation. definition, a locked-for-edit constellation is not public.
editList($appUserID) public function listConstellationsLockedToUser($status=null)
Given a user, get a list of the constellations that are currently "checked out" to that user. In other words, The SNAC dashboard will call listConstellationsLockedToUser() or the logical equivalent, which returns a list
constellations that user is editing. Return a list of constellation objects. of constellations. The dashboard web page is populated from this list of constellations. The user who has the
lock, or admins can change the lock to another user, but we will not allow two users edit the same
constellation.
We may want a function that returns the X most recently updated constellations, where X is a parameter. That We may want a function that returns the X most recently updated constellations, where X is a parameter. That
would also be useful on the dashboard. Will this only return constellations locked by the user, or does this would also be useful on the dashboard. We are already planning for listConstellationsLockedToUser() to take a
list any constellation? Are these only constellations being edited, or are they published? Or a mix of status parameter, which will be usefor for the dashboard.
locked-for-edit and published?
There are several functions that only return mainID and version (but not a full constellation) The application public function readConstellationStatus($mainID, $version=null)
programmer calls readConstellation() to read the full constellation. This mix and match approach is more
flexible than a hoarde of functions which variously return: an id, lists of id, a version, lists of version, a Read the status for constellation ID $mainID, with optional $version arg. If no version then it defaults to
single constellation, or lists of constellation. the most recent version, deleted or not (logically) since 'deleted' is one of the status values. Returns false
on failure.
public function writeConstellationStatus($mainID, $status, $note="")
Modify the status of a constellation. Returns the new version number for the status update, or false on
failure. Cannot set a status to 'deleted', but can modify a deleted status to some other value. Only known
status values are accepted.
```
private $statusList = array('published' => 1,
'needs review' => 1,
'rejected' => 1,
'locked editing' => 1,
'bulk ingest' => 1,
'deleted' =>1);
```
Valid status values are stored in a private var in DBUtil.php.
public function allVersion($mainID)
Returns all versions (in order, from lowest to highest) in a list for a given ID. This is a utility function
available to build user interfaces for diff of two versions, or reversion to a previous version.
There are several functions that only return mainID and version (but not a full constellation). After getting
mainID and version, the application programmer calls readConstellation() to read the full constellation. This
mix and match approach is more flexible than a hoarde of functions which variously return: an id, lists of id,
a version, lists of version, a single constellation, or lists of constellation.
### Private functions
Currently, functions which return lists of mainID and version are private to DBUtil. These granular, low-ish
level functions may be useful for application programmers, but since the use case is currently unclear, we
have made these functions private.
Many other functions in DBUtil have no use case outside the class and are private.
private function editList()
Return a list of the mainID and version that are currently "locked editing" for the user. DBUtil determines
who is the current user. Long term, the code calling DBUtil will probably feed the user id to DBUtil.
readConstellation() returns a full constellation, and the UI can be built from that as necessary. This is
better than having functions specificly only returning partial data for the UI, but full data for other
uses. The functions that return ID and version work alongside readConstellation() as part of a small tool kit.
Functions return the most recent version so that a user can continue editing where they left off. By
definition, a locked-for-edit constellation is not public. By having a number of functions that only return a
mainID and version (or a list of mainID and version) the UI and dashboard programmers can use those in
combination with functions that return full constellations as the programmers wish.
The special allVersions() returns all versions (in order from lowest to highest) in a list for a given
ID. This is a utility function available to build user interfaces for diff of two versions, and reversion to a
previous version.
### Utility functions ### Utility functions
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment