stasher::client->getdir(): enumerate objects in the repository

#include <iostream>
#include <stasher/client.H>

void showhier(int argc, char **argv)
	stasher::client client=stasher::client::base::connect();

	stasher::getdirresults results=client->getdir(argc < 2 ? "":argv[1]);

	if (results->status != stasher::req_processed_stat)
		throw EXCEPTION(x::tostring(results->status));

	for (auto &direntry:results->objects)
		std::cout << direntry << std::endl;

int main(int argc, char **argv)
	try {
		showhier(argc, argv);
	} catch (const x::exception &e)
		std::cerr << e << std::endl;

	return 0;

stasher::client->getdir()'s parameter is a hierarchy name, and an empty string specifies the top-level hierarchy. stasher::client->getdir()'s returns a stasher::getdirresults, which is an x::ref to a reference-counted object with two members. status reports the request's status. objects is a std::set<std::string> containing a list of all objects in the specified hierarchy:

$ ./showhier
$ ./showhier constants

Names that end with a / specify a subhierarchy. In this example, there are three objects in the repository. helloword, constants/e, constants/pi. Passing an empty hierarchy name, specifying the top-level hierarchy, returns a std::set<std::string> with helloworld because it's the only object in the top level of the hierarchy. There's also a constants/ in the returned list, indicating an existence of objects in a sub-hierarchy.

Of course, by the time the client asks for the list of objects in the constants subhierarchy, something else might've deleted them. This is not an error, the request simply returns an empty list.


The above example shows that the returned std::set<std::string> reflects complete object names. A getdir("constants") returns constants/e and constants/pi, rather than e and pi.

Repository namespace views

It's important to note that the client's view of the object repository is usually filtered. The object repository server's configuration typically limits the client's view to some portion of the actual object repository. This is further explained in the documentation for the stasher interactive tool.

stasher's default server configuration puts all clients, except those ones specifically configured otherwise, into the sandbox hierarchy. For the example in this section, the actual objects would actually be sandbox/helloworld, sandbox/constants/e and sandbox/constants/pi.

An administrative connection (not used by applications, and is not described here, see class documentation for more information), gets the actual object hierarchy namespace, with full object names. This example shows the client's perspective, which is confined to the sandbox hierarchy. So from the client's perspective, it sees helloworld, constants/e and constants/pi.

This implements the ability to partition applications into different areas of the same object repository, mostly negating the need to set up different object repositories to provide for this kind of separation. An application would typically be developed in a sandbox area. By default, there's one sandbox for all processes in the server, but it's possible to have dedicated, separate sandboxes for individual userids, for example. Once an application is fully cooked, and is ready to be launched (promoted to a production status, or a staging status, or whatever it's called), a namespace rule change repoints the application to its own, dedicated, initially empty object hierarchy, with no changes required to the application itself. See the section called “NAMESPACE {command}*” for more information.