Commit 81394cd7 by Tom Laudeman

Update prose about args and return values

parent 9d275a8f
...@@ -16,22 +16,28 @@ There is an interactive schema web site: [Schema web site](http://shannonvm.vill ...@@ -16,22 +16,28 @@ There is an interactive schema web site: [Schema web site](http://shannonvm.vill
When creating a DBUtil object, you must supply the application user credentials in the form of the numberic When creating a DBUtil object, you must supply the application user credentials in the form of the numberic
user id and numeric role. user id and numeric role.
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 batch
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. A new version will be minted if none exists. If a version exists, it will be used for all new ID being minted. In other words, for a new constellation written to the database for the first time, a new
operations during the life of the DBUtil object. This is intentional. While the database is not appreciably version will be minted if none exists.
effected by minting large numbers of versions, it does make the data harder for humans to read and debug.
If a version exists in the current DBUtil object, it will be used for all operations during the life of the
DBUtil object. This is intentional. While the database is not appreciably effected by minting large numbers of
versions, it does make the data harder for humans to read and debug. For example, a programmer trying to
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
This mechanism needs work. DBUtil needs a constellation ID in order to read a constellation from the Methods to discover the ID or ARK of existing constellations needs work. DBUtil must have a constellation ID
database. Presumably, some function will exist in DBUtil that takes some constraints and returns a list of in order to read a constellation from the database. Presumably, some search or browse function(s) will exist
constellation ID. that returns a list of constellation ID. The function will have some constraints so that a manageable list
will be return, and not all 4.5 million records.
In the future we will support reading old versions of a constellation. In that case, discovery must return the In the future we will support reading old versions of a constellation. In that case, some function must return
constellation ID as well as version number. At that time, readConstellation() will need an update to take a a list of prior version numbers for a given constellation ID. Starting now, readConstellation() takes a version
version number argument. Low level SQL code already takes version number. 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
...@@ -39,11 +45,25 @@ version number argument. Low level SQL code already takes version number. ...@@ -39,11 +45,25 @@ version number argument. Low level SQL code already takes version number.
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, a string
for status, and a string for the history note. To retrieve a constellation, call readConstellation() with for status, and a string for the history note. To retrieve a constellation, call readConstellation() with
constellation ID (aka main_id, $mainID). constellation ID (aka main_id, $mainID) and version number.
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
only the most recent. Only allVersions() returns a full list of versions for a given ID.
See function signatures and calls below.
$cObj is a constellation object
$note is a string
$mainID is a constellation ID, an integer
$version is a version number, an integer
Current implementation of readConstellation() only supports reading the most recent version. Requirements for $arkID is an ARK, a string.
reading old versions are incomplete, but could be a simple as supplying readConstellation() with a version
number. $appUserID is a numeric user identifier
Status is a (more or less?) controlled vocabulary. Examples include: 'published', 'needs review', 'rejected', Status is a (more or less?) controlled vocabulary. Examples include: 'published', 'needs review', 'rejected',
'being edited', 'bulk ingest'. 'being edited', 'bulk ingest'.
...@@ -69,27 +89,38 @@ $idVersionList = array( ...@@ -69,27 +89,38 @@ $idVersionList = array(
array('main_id' => 3, 'version' => 2), array('main_id' => 3, 'version' => 2),
array('main_id' => 4, 'version' => 5)); array('main_id' => 4, 'version' => 5));
$constellationList = array(); function loadDash($appUserID)
foreach ($idVersionList as $iver)
{ {
$cObj = readConstellation($iver['main_id'], $iver['version']); $idVersionList = editList($appUserID);
array_push($constellationList, $cObj);
$constellationList = array();
foreach ($idVersionList as $iver)
{
$cObj = readConstellation($iver['main_id'], $iver['version']);
array_push($constellationList, $cObj);
}
} }
$versionList = allVersions($mainID); $versionList = allVersions($mainID);
// I don't think we need this if we universally return id and version
public function readConstellation($mainID)
``` ```
The SNAC dashboard will do the logical equivalent of calling editList() followed by calling
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.
publishedConstellationByARK($arkID), publishedConstellationByID($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. Have equivalent functions for constellations locked-for-edit aka editing. The
"editing" will only return a list that the user has permissions to edit, and that means constellations locked "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 by that user. Admins can change the lock to another user, but we will not allow two users access to edit the
same constellation. same constellation.
editList($appUserID)
Given a user, get a list of the constellations that are currently "checked out" to that user. In other words, Given a user, get a list of the constellations that are currently "checked out" to that user. In other words,
constellations that user is editing. Return a list of constellation objects. constellations that user is editing. Return a list of constellation objects.
...@@ -98,15 +129,14 @@ would also be useful on the dashboard. Will this only return constellations lock ...@@ -98,15 +129,14 @@ would also be useful on the dashboard. Will this only return constellations lock
list any constellation? Are these only constellations being edited, or are they published? Or a mix of list any constellation? Are these only constellations being edited, or are they published? Or a mix of
locked-for-edit and published? locked-for-edit and published?
Most functions return mainID and version. The application programmer calls readConstellation() to read the There are several functions that only return mainID and version (but not a full constellation) The application
full constellation. This mix and match approach is more flexible than a hoarde of functions some of which programmer calls readConstellation() to read the full constellation. This mix and match approach is more
return an id, lists of id, a version, lists of version, a single constellation, or lists of constellation. 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.
Should functions return just enough data for the UI, or should the return a list of full constellations? readConstellation() returns a full constellation, and the UI can be built from that as necessary. This is
That's a tricky question. I would say let's just return full constellations. They might not all get used by better than having functions specificly only returning partial data for the UI, but full data for other
us, but I can see that as a pretty cool REST API feature for others. I'm thinking the WebUI will probably use uses. The functions that return ID and version work alongside readConstellation() as part of a small tool kit.
a name and the ID. But remember, that function needs to get the current version for that user, which might
not be public yet.
Functions return the most recent version so that a user can continue editing where they left off. By 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 definition, a locked-for-edit constellation is not public. By having a number of functions that only return a
...@@ -114,7 +144,8 @@ mainID and version (or a list of mainID and version) the UI and dashboard progra ...@@ -114,7 +144,8 @@ mainID and version (or a list of mainID and version) the UI and dashboard progra
combination with functions that return full constellations as the programmers wish. 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 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 diff and reversion user interfaces. 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