Networking

UBStores networking layer basically consists of two things: The INode interface that represents nodes in the network, and the IShepherd interface, which is a service that is responsible for maintaining a network structure and being able to find nodes in the network.

Network Nodes (INode)

TODO rewrite this when the INode semantics are clarified.

In UBStore, a network node consists of three characteristics: an address, a port, and a name. As implied by the presence of a port, a node does not necessarily have to be a physical machine. Instead, a node represents an instance of UBStore, and one physical machine can contain multiple nodes.

Nodes in the network are represented by INode objects, which are essentially triples of address, port and name.

IShepherd

The IShepherd is UBStores networking service, i.e. it is responsible for maintaining the network and enables finding nodes in the network by name.

Its interface is rather simple: There are methods for adding and removing nodes from the network, and resolving nodes by name. Despite the simplistic interface, a lot of logic can be buried transparently underneath the interface: Since the task of the shepherd is to also maintain the network structure, implementations probably need to do a lot of node to node communication for exchanging known nodes, detecting failed nodes, or redirecting resolve requests. However, there are no specifications for the implementations, and they can chose whether to do this via RMI, custom message passing, or anything else.

Obtaining the Shepherd

The easiest way to access the data access is via the IUBStore.getShepherd() method. However, since it is implemented as an OSGi service, it is also possible to get a reference using OSGi services, be it programmatically or by using declarative services.

Connecting to an existing network

When UBStore is supposed to connect to an existing network of nodes, this can be done via the IShepherd.addNode(INode) method. Simply call this method with a node that is a member of said network. Afterwards, the shepherd should then be able to find all nodes that exist in the network that node belongs to.

Resolving nodes

The shepherd is able to find nodes in the network, i.e. it can resolve addresses by name. The IShepherd.resolveNode(String) method returns an INode object that represents the node within the network with the given name.

Removing nodes

The IShepherd.removeNode() method is used for removing a node from the network (i.e. disconnecting it). When it is removed, it cannot be resolved anymore afterwards.

Getting the local node

The shepherd contains a method getLocalNode() that returns the node that represents the local UBStore instance.