Document Repository
The following diagram shows the architecture for the document repository project.
The Document Repository provides a unified mechanism for managing various types of persistent components in the Bali Nebula™ including:
- documents - general documents formatted using the Bali Document Notation™ which can be saved and updated
- contracts - digitally notarized documents that cannot be updated or deleted
- messages - documents that are posted to a message bag by one task and retrieved and processed by another task
- events - documents that represent something that happened that might be of interest to other parties that will be notified when an event that they are interested in has been published
For detailed information about digitally notarized documents (i.e. contracts) visit the Bali Digital Notary™ project.
The following UML class diagram provides details interface supported by the document repository.
The DocumentRepository class uses a StorageModule to handles the actual storage of the documents. The
diagram also shows the attributes maintained by the three main catalog types that show up in the functions
listed in the document repository interface. An example of each of these types follows.
A document may be cited using a document citation which references the document's unique tag and version number along with a digest of the entire contents of the document:
[
$protocol: v2
$tag: #SLYAY2QY683429NF2AASXKGG8FGWFLLL
$version: v1
$digest: '
W1W237N65W2LSDWK0D1D124WADA7GZ0N3Y4T0ZKR5JAQYDVRWRHN3S55288Z
D6HSKBGRFD08CCW6HWJHTR0N4M9A81M03J52Y6KJBF0
'
]($type: /bali/notary/Citation/v1)
The digest ensures that the document has not been modified since it was cited. Modifying even a single character in the original document will result in a completely different digest so any modification, accidental or otherwise can easily be detected.
The above document citation might refer to a document that looks like this:
[
$name: "Jane Doe"
$age: 30
$email: <mailto:jane.doe@acme.org>
](
$type: /acme/types/Profile/v1
$tag: #SLYAY2QY683429NF2AASXKGG8FGWFLLL
$version: v1
$permissions: /bali/permissions/public/v1
$previous: none
)
Each document is parameterized with information about its type, its unique tag and version string, the permissions required to access it, and a document citation to a previous version if one exists. An updated version of this document might look like this:
[
$name: "Jane Doe"
$age: 29
$email: <mailto:jane.doe@acme.org>
](
$type: /acme/types/Profile/v1
$tag: #SLYAY2QY683429NF2AASXKGG8FGWFLLL
$version: v1.1
$permissions: /bali/permissions/public/v1
$previous: [
$protocol: v2
$tag: #SLYAY2QY683429NF2AASXKGG8FGWFLLL
$version: v1
$digest: '
W1W237N65W2LSDWK0D1D124WADA7GZ0N3Y4T0ZKR5JAQYDVRWRHN3S55288Z
D6HSKBGRFD08CCW6HWJHTR0N4M9A81M03J52Y6KJBF0
'
]($type: /bali/notary/Citation/v1)
)
Notice that the $previous attribute now contains a document citation to the first version of the
document.
Documents can be digitally notarized and saved to the document repository as signed contracts. Once saved in the document repository that version of the signed contract cannot be changed or deleted. The signed contract containing the previous document might look something like this:
[
$protocol: v2
$timestamp: <2020-06-02T16:38:18.765>
$account: #MBMGTMPYTBCK0N4F8YX8D8GR16GRDNGL
$document: [
$name: "Jane Doe"
$age: 29
$email: <mailto:jane.doe@acme.org>
](
$type: /acme/types/Profile/v1
$tag: #SLYAY2QY683429NF2AASXKGG8FGWFLLL
$version: v1.1
$permissions: /bali/permissions/public/v1
$previous: [
$protocol: v2
$tag: #SLYAY2QY683429NF2AASXKGG8FGWFLLL
$version: v1
$digest: '
W1W237N65W2LSDWK0D1D124WADA7GZ0N3Y4T0ZKR5JAQYDVRWRHN3S55288Z
D6HSKBGRFD08CCW6HWJHTR0N4M9A81M03J52Y6KJBF0
'
]($type: /bali/notary/Citation/v1)
)
$certificate: [
$protocol: v2
$tag: #BGRB9GJ124VCDY7RPBD3WKY1K40H1SGK
$version: v1
$digest: '
VVFGQT8J23KPWKH7ZMZ3T0NLN7HZSR43L0P2JD2FHP09177A385390RS2JK6
6RZ1FKBBTJQBXHD3DN6P0Z4DPN1NFF1FQZDSGQ8RYX8
'
]($type: /bali/notary/Citation/v1)
$signature: '
VK9C7Q3LN0A2X1W4Q1WPJJ4W9FK2Q8Z0VR6TLXXY68YZZMXMNL5XX33FT38A
4ZFS86G73R56MPWDP73GB63FVXJ2ZJYJBRZYFY4KA00
'
]($type: /bali/notary/Contract/v1)
Notice that the entire document is embedded in the contract. The $signature attribute in the contract
is a digital signature of the entire contract that was created using the owner of the contract's private
notary key. The $certificate attribute is a document citation to the public notary certificate that
may be used to verify the authenticity of the digital signature. These two attributes ensure that once
a contract has been notarized it cannot be modified later on. Also, the owner of the contract cannot
claim that she did not notarize it.
With the three catalog types discussed above in mind, we can now look at how they are used by the functions defined in the interface to the document repository class.
The following provides a brief description of each document related function listed in the interface for the document repository:
-
createDocument(type, permissions, template)- This function creates a new document of the specified type and with the specified permissions. The specified attributes are used to seed the initial attributes for the new document. The new document is returned as the result. -
saveDocument(document)- This function saves the specified document in the document repository. If a document with the same tag and version string already exists in the repository it is overwritten by the specified document. A citation to the specified document is returned as the result. -
discardDocument(citation)- This function discards from the document repository the document cited by the specified document citation. The function returns a result describing whether or not any document matching the citation was discarded. -
retrieveDocument(citation)- This function retrieves from the document repository the cited document. The document is returned as the result, or if the document does not exist, then nothing is returned. -
signContract(name, document)- This function digitally notarizes the specified document and saves it as a contract in the document repository under the specified name. Nothing is returned from this function. -
checkoutContract(name, level)- This function checks out a copy of the contract associated with the specified name from the document repository. If a version level is specified, the version string of the new document will have been incremented at that level. Otherwise, the version string will have been incremented at the highest level in the current version string. The new document is returned as the result. -
retrieveContract(name)- This function retrieves from the document repository the contract associated with the specified name. The contract is returned as the result, or if the contract does not exist, then nothing is returned.
Traditionally, messages are placed in queues by one set of tasks and removed and operated on by another set of tasks. The messages are retrieved in "first in, first out" (FIFO) order. However, in a globally distributed environment like the Bali Nebula™, the order in which messages are posted is somewhat relative, as is the order in which they are retrieved. So the queue model is not really appropriate for the document repository's handling of messages. Instead, the repository manages message bags. Messages are posted to a bag by one task and retrieved from the bag by another task.
The document repository follows the Tuple Space approach developed by David Gelernter in 1986 and extended later with a leasing model within JavaSpaces™ by Sun Microsystems™. What these models call a space, the document repository simply calls a bag. Messages can be put into a bag, and then pulled out from the bag in random order.
The following provides a brief description of each message related function listed in the interface for the document repository:
-
createBag(name, permissions, capacity, lease)- This function creates a new message bag with the specified name and with the specified permissions for accessing the bag. The maximum capacity of the bag, and the number of seconds before the lease on each retrieved message expires may also be specified. Nothing is returned from this function. -
postMessage(bag, message)- This function posts the specified message to the named message bag. Once posted, the message becomes available to other tasks for retrieval and processing. Nothing is returned from this function. -
messageCount(bag)- This function returns the current number of messages that are available for retrieval from the named message bag. -
retrieveMessage(bag)- This function retrieves from the named message bag a randomly selected message. The task that retrieved the message then has the number of seconds specified in the lease to finish processing the message and either accept it or reject it before the lease expires and the message is automatically returned to the bag and made available to other tasks. -
acceptMessage(message)- This function allows a task to let the document repository know that it is done processing the specified message which it previously retrieved from the repository. The repository will then cancel the lease on the message and permanently remove it from the bag. Nothing is returned from this function. -
rejectMessage(message)- This function allows a task to let the document repository know that it was unable to complete processing of the specified message which it previously retrieved from the repository. The task may have added or updated attributes of the message so a new version of the message is placed back in the bag. The updated message is then available for retrieval. Nothing is returned from this function.
The following provides a brief description of the event related function listed in the interface for the document repository:
-
publishEvent(event)- This function publishes to the event notification mechanism within the document repository the specified event. Any tasks interested in this type of event will be notified of it asynchronously. Nothing is returned from this function.