This page contains information on details of distributed registry implementation in DistRegistry library. These details are given there to provide better exposure of distributed registry internals, which can be useful for better understanding of distributed registry configuration details and customizations (if ones will be necessary).

Internal decomposition

In previous section, we have considered both ProvidingRegistry and ConsumingRegistry as solid notions. Of course, this is correct from the high-level view on architecture, but internally different classes compose both these entities. 

Both ProvidingRegistry and ConsumingRegistry aggregate these classes and delegate significant part of their functionality to these classes. Since both registries are just different parts of the same distributed registry, they have quite close structure and internally utilize almost the same set of components.

Let us consider these classes in more details.

Overall scheme of distributed registry

First, both registries use some storage for items. ProvidingRegistry uses that storage to save data published directly via it only, while storage in ConsumingRegistry contains data item for particular key(s) published by all instances of ProvidingRegistry, which communicates with ConsumingRegistry.

The classes that implements registries include just a high-level functionality related to management of storage and communication with caller code. All details of network communication and commands, which are used within that protocol, are isolated from registries and are delegated to CommunicationHelper.

CommunicationHelper represents a facade for network communication protocol used by distributed registry. The protocol is fairly simple and sending of appropriate network messages is invocated by corresponding methods of the CommunicationHelper. In addition to issuing commands to network, CommunicationHelper also obtains information about incoming messages and provides listener that allows interested parties (such as registry) get information about incoming data.

To encode and decode data from high-level registry specific format to raw data format, in which data will be transferred via network, the CommunicationHelper uses CommunicationProtocol class. That class performs encoding of data, which should be sent via network, and decoding data received from there.

And finally, the Adapter is used to perform low-level network communication by sending and receiving network message.

Pluggable networks transport

The current implementation of distributed registry allows isolating details of network communication from logic of the registry via isolated CommunicationHelper. Currently, there are two possible implementations of network communication available - one is based on simple UDP multicasting and another one which uses JGroups library for network communication.  In general, it is possible to implement different schemes of network transport.

Depending on scheme of networking communication scheme, appropriate CommunicationProtocol and CommunicationHelper should be used by registries.

Of course, if one type of network transfer layer is used by ProvidingRegistry (say, JGroups based one) the same type of network transfer layer should be used by ConsumingRegistry.

Simple UDP

The UDP based network transport protocol specific classes are located in package.

The UDP multicasting (Adapter component) is supported by classes located in package. Please note that these classes are, in general, independent from the distributed registry and can be used separately.

Internally, the following figure illustrates the format of packets sent by multicaster:

Structure of UDP message

As it illustrated by figure above, the structure of UPD message sent by multicaster is simple and represents rather an envelope, which carries some custom data. For distributed registry, these custom data represent specific message, which is part of internal registry communication protocol.

The Signature field is used to filter incoming datagram packages and selecting only ones specific messages (this is necessary if the same multicast group is used by different applications or by different components of the application). Other components of message are self-explanatory.


The UDP based network transport protocol specific classes are located in package.

The PullPushAdapter from JGroups is used to implement underlying network operations.

Details of communication protocol

The communication protocol used within distributed registry is very simple. Actually, there are only four commands used internally. These commands are listed in the table below. 




Notification about item registration. It is sent by ProvidingRegistry either as result of new item publishing or after processing COMMAND_ITEM_REQUEST command issued by ConsumingRegistry


Issued either by ConsumingRegistry to invalidate particular item data. Processed by other ConsumingRegistry instances.


Issued by ProvidingRegistry if data item is un-published. Processed by ConsumingRegistry instances, which removes data item from their storages.


Issued by ConsumingRegistry to obtain information about data item under particular key or for all data items published. Processed by all instances of ProvidingRegistry.

The CommunicationHelper component offers high level API, which allows issuing such a network commands as well as processing them.

These commands are carried out by appropriate communication messages used by distributed registry. These messages are part (or content) of messages issued by either UDP multicaster or JGroups based messages.

The structure of communication message is also very simple and figure below illustrates it:

Structure of distribute registry message

The Signature field is used to filter messages, which are related to particular distributed registry. This is necessary if several distributed registries are used within the same application or if there are other components of the system, which use the same network protocol but transfer different type of data.

Typedefines the command for message.

To and From fields are used internally by registry and present ID of providing or consuming registry.

The Key field represents key of data item, Value field contains that data item itself.  If COMMAND_ITEM_REQUEST command is issued by ConsumingRegistry, that field is empty. If Key item is missed in COMMAND_ITEM_REQUEST command, such a message is considered as request for all items published.

Details of internal functioning

Here we briefly review some details of internal implementation of distributed registry and collaboration between internal components. We consider high-level sequence of processing incoming data from network and issuing network notifications.

To find more details of communications, please refer to source code of DistRegistry library.

Processing incoming data

Each registry within its lifecycle either issues data into network or receive them. Here we consider what happens if outer data are available and examine the sequence of processing them. 

The following diagram illustrates the process:

Sequence of incoming data processing

When some remote component of distributed registry issues network message, it first arrives to network adapter (UDP or JGroups based). If NetworkAdapter decides that it should process incoming data, it notifies CommunicationHelper of that fact (step 2). CommunicationHelper decodes incoming message using CommunicationProtocol (step 3), checks whether valid data are received and whether this message is related to distributed registry. If necessary, it notifies registry of obtained data (step 4). Registry performs all necessary operations according to incoming data.

Issuing outgoing notification

The process of issuing notification to network is quite close to the previous case and utilizes the same set of component. Actually, the sequence is close but is directed to the opposite side. The following diagram illustrates it:

Sequence of outgoing data processing

As it was expected, the sequence is quite straightforward. As soon as caller code (one which outside ConsumingRegistry or ProvidingRegistry) invokes some method, registry starts to process it. If registry determines that network notification is to be issued, it issues proper call to CommunicationHelper (step 3). CommunicationHelper creates appropriate registry message and uses CommunicationProtocol to encode data to format, which is ready to network (step 4).

After that, CommunicationHelper invokes NetworkAdapter to initiate sending of data via network.

Distributed cache

In some cases, the providing registry can be not applicable for needs of particular application. For example, it can be necessary to have a simple HashMap-like structure that stores only one value under given key but is still distributed.

For this purposes, DistRegistry includes simple implementation of distributed hash table, which is based on the same protocol as one used by distributed registry, but stores only one value under one key.

Current implementation does not make any assumptions about resolving possible conflicts (i.e. how to resolve the case if different data for the same key are stored in different locations). Instead, it simply stores data and therefore slightly different values can be stored in different instances of cache.

However, such a simple distributed cache is still quite useful in some cases despite of these limitations.

To find more about distributed cache, please refer to package.

Integration with Spring framework

In general, the distributed registry does not require Spring framework and can be used separately.

However, Spring is very popular today and offers very convenient way of assembling applications via Inversion of Control (IoC) pattern (among with other features). That is why DistRegistry includes some small extensions of base classes which are intended to simplify usage of library components within Spring container (however, it's not necessary to use extended class to use DistRegistry within Spring - extensions just slightly simplify configuration).

These extended classes do not provide any additional logic, which is directly related to, for example, distributed registry. However, they contain implementation of some interfaces related to Spring lifecycle.

To find more about such classes, please refer to package. Logo   Support This Project