The Elko Repository Protocols

The Repository

The Repository is an Elko server that provides persistent storage for objects. Context servers can be configured to use either a local repository that they access directly or to communicate with a Repository server. The protocols described here are for the latter case.

A Repository understands two different JSON message protocols. These correspond to the two kinds of actors who may wish to communicate with a Repository: other servers seeking to retrieve or store persistent objects, and administrators. Each of the ports that a Repository listens for connections on can be configured to support either or both of these protocols.

Each of these protocols is associated with a particular object ref to which messages should be addressed:

• rep for object repository access.
• admin for administrator messages.

Repository Protocol

The repository protocol is used by clients who wish to access the persistent objects that the Repository manages.

get

This message requests the retrieval of the persistent state of one or more objects.

• what is an array of object request descriptors specifying the objects whose retrieval is sought.
• tag is an optional tag string that, if given, will be sent back with the response(s), to help the client match up requests and responses.

An object request descriptor takes the form:

where:

• ref is the reference string identifying the object sought.
• contents is an optional boolean flag that, if true, indicates that any objects contained by the requested object (any objects in the entire containment hierarchy rooted at the object, in fact) should also be retrieved. If omitted it defaults to false.

The Repository will reply with a message of the form:

where:

• results is an array of object descriptors, one for each object that was requested (directly or indirectly) in the original get message.
• tag echoes the tag from the get request, if there was one, or will be omitted if the original get also omitted it.

An object descriptor takes the form:

where:

• ref is the reference string identifying the object.
• obj is representation of the state of the object. The details of this will, of course, vary depending upon what kind of object it is. This will be absent if the object could not be retrieved.
• failure is an error message string indicating the reason why the Repository was unable retrieve the object. This will only appear in failure cases.

put

This message requests the Repository to store the new persistent state of one or more objects.

• what is an array of object descriptors containing the states of the objects that are to be stored. These object descriptors take the form documented above in the description of the get request.
• tag is an optional tag string that, if given, will be sent back with the response(s), to help the client match up requests and responses.

Storage is atomic over the full collection of objects transmitted in the put request. That is, the persistent states of all specified objects are updated or none are.

Note that there is no explicit "create" operation. Simply issue a put for an object not currently stored. The Repository will reply with a message of the form:

where:

• results is an array of result descriptors, one for each object whose storage was requested in the original put message.
• tag echoes the tag from the put request, if there was one, or will be omitted if the original put also omitted it.

A result descriptor takes the form:

where:

• ref is a reference string identifying the object the result pertains to.
• failure is an error message string indicating the reason why the Repository was unable store the object. This will only appear in failure cases.

remove

This message requests the Repository to delete the persistent state of one or more objects.

• refs is an array of object reference strings identifying the objects to be deleted.
• tag is an optional tag string that, if given, will be sent back with the response(s), to help the client match up requests and responses.

The Repository will reply with a message of the form:

where:

• results is an array of result descriptors, one for each object whose deletion was requested in the original put message. These result descriptors take the form documented above in the description of the put request.
• tag echoes the tag from the put request, if there was one, or will be omitted if the original put also omitted it.

Admin Protocol

The Repository admin protocol is used to administer the Repository server.

reinit

This message instructs the Repository to reinitialize itself.

shutdown

This message instructs the Repository to shut itself down.

where:

• kill is an optional flag that if true orders an abrupt termination of the server. Normally, a server will empty its message queues, checkpoint any active state, and perform an orderly shutdown. However, if the kill flag is true, it will exit immediately without stopping to clean things up. The value defaults to false if the parameter is omitted.