StorageDispatcher — the local storage facade
Deep-dive page: the com.p2pframework.storagedispatcher bundle — the API that plugins actually call
for shared content, the cache tiers that sit above PAST, the push-based social cache, and the
deprecated local-disk path.
Supersession note: the original StorageDispatcher/Information-Cache design is Podrajanski 2008, its OSGi packaging Alviṭe 2008; the bundle itself was created by the 2011/12 project group (PG 2011) and renamed in 2013 (PG 2012). The cache layer as it runs today is the social caching design of ISNCC 2020, consolidated in Graffi 2020. What follows describes the 2026 source state, including the July-2026 social-cache fixes.
Purpose
StorageDispatcher in the LibreSocial component map names two distinct layers that share one name.
Confusing them is the single most common mistake when reading the code:
| Layer | Interface | Implementation | Package / bundle |
|---|---|---|---|
| Application level (plugin API) | org.lifesocial.middlewarestorage.storagedispatcher.api.IStorageDispatcher |
com.p2pframework.storagedispatcher.SignStorageDispatcher |
com.p2pframework.storagedispatcher (this page) |
| Framework level (overlay-facing) | com.p2pframework.storage.StorageDispatcher |
com.p2pframework.storage.past.PastryStorageDispatcher |
com.p2pframework — see PAST storage |
The application-level dispatcher is a local facade: it takes SharedItem objects keyed by a
StorageKey, serves them from local caches when possible, otherwise delegates to the framework-level
dispatcher, which performs the actual PAST put/get on the FreePastry overlay. It also owns the
Information Cache — the local staging area for incoming messages and for items requested
asynchronously — plus the group/task updaters that consume it.
One precision correction to the usual one-line description ("routes storage operations to
PAST/DDS/cache"): the plugin-level dispatcher routes to caches and to the framework PAST
dispatcher only. Distributed data structures do not go through it — com.p2pframework.DDS.DataBackend
and the DistributedSet/DistributedLinkedList/DistributedTree classes call
framework.getStorageDispatcher() directly (194 such call sites across the source tree), so DDS
bucket access bypasses the plugin-level caches entirely.
Current implementation (as of 2026)
Bundle root: Source/com.p2pframework.storagedispatcher/ — 36 Java files, 5 145 lines, built as an
OSGi bundle via bnd.bnd + the Gradle osgi-bundle-conventions plugin
(Bundle-RequiredExecutionEnvironment: JavaSE-17, Bundle-ActivationPolicy: lazy). It exports
com.p2pframework.storagedispatcher, org.lifesocial.localstorage.api,
org.lifesocial.middlewarestorage.informationcache.* and
org.lifesocial.middlewarestorage.storagedispatcher.api, and requires com.p2pframework,
rice.freepastry and org.lifesocial.core.
src/com/p2pframework/storagedispatcher/SignStorageDispatcher.java 508 l the facade (OSGi component)
src/org/lifesocial/middlewarestorage/storagedispatcher/api/ 106 l IStorageDispatcher (plugin API)
src/org/lifesocial/localstorage/api/ILocalStorage.java 93 l deprecated local-disk API
src/org/lifesocial/middlewarestorage/informationcache/main/ 637 l InformationCache (static singleton)
src/org/lifesocial/middlewarestorage/informationcache/caches/ SharedItemCache, NodeHandlesCache, UsrDataWaiter,
PluginMsgsCacheChecker
src/org/lifesocial/middlewarestorage/informationcache/handlers/ ItemHandler, MessageHandler, DeliveredMsgDeleter
src/org/lifesocial/middlewarestorage/informationcache/requests/ SharedItemRequest, NodeHandleRequest
src/org/lifesocial/middlewarestorage/informationcache/updaters/ Group/GroupNamesHolder + Task/TaskNamesHolder updater
src/org/lifesocial/middlewarestorage/informationcache/utils/ LRUCache(-Impl), StorageContainer, SocialCache (384 l),
SocialCachingMessage, SocialCachingUpdateStrategy
{Abstract,Random,Total,Trend,SocialScore}, SocialCacheUtils
There is no OSGI-INF/ directory any more: since commit 189018957 (2026-05-19) the component
and service descriptions are Java annotations generated by bnd —
@Component(name = "StorageDispatcher", immediate = true, service = { IStorageDispatcher.class, ILocalStorage.class })
on SignStorageDispatcher, which implements both interfaces. It uses dynamic @Reference injection of
Framework (setFramework, which resolves
framework.getStorageDispatcher() and calls InformationCache.setStorageDispatcher(this)) and of
ILogService. Plugins bind the same service with
@Reference(name = "SD", policy = ReferencePolicy.DYNAMIC, unbind = "unsetSD") on a
setSD(IStorageDispatcher sd) method (org.lifesocial.plugin.profileplugin/.../ProfilePluginComponent.java).
API surface (IStorageDispatcher)
| Method | Notes |
|---|---|
storeSharedItem(SharedItem, String className) |
delegates to the 3-arg form with CACHE_DEFAULT_CACHE_TIME |
storeSharedItem(SharedItem, int maxCacheTime, String className) |
asynchronous overlay store (fixed pool of 5 threads) |
lookupSharedItem(StorageKey, String className) |
cache-then-overlay read, see order below |
lookupSharedItem(StorageKey, int maxCacheTime, String className) |
per-call cache lifetime; values below CACHE_MIN_CACHE_TIME are clamped |
deleteSharedItem(StorageKey) |
overlay delete + cache invalidation |
isInCache(StorageKey) / isInCache(String) |
LRU membership test only |
isAvailable(StorageKey, String className) |
not in the interface; cache check, then a real overlay retrieve |
requestUserIDForUsername(String,String) / requestIDForUsername(String,String) |
username → UserID/ID via the LoginItem record (HashKeyBuilder.buildLoginItemKey) |
isStarted / startStorageDispatcher / stopStorageDispatcher |
trivial boolean started flag; no lifecycle effect |
requestLoginItem(String) |
implementation-only helper, not part of the interface |
ILocalStorage (storeItemLocally, deleteItemLocally, loadItemLocally) is published by the same
component but every method is @Deprecated — "no local storage anymore. Only memory cache is
used" (edit note dated 23.01.2014, Christopher Holomek). deleteItemLocally returns false without
doing anything; storeItemLocally is still used internally as the private cache-put helper.
Read path, in exact order
lookupSharedItem(key, maxCacheTime, className):
socialCache.lookup(key)— ifsocialCacheEnabled— hit → counterSOCIAL_CACHE_COUNT.loadItemFromCache(key.getKeyBasis())— LRUmemoryCache(200 entries) — hit and notisOutdated()→ counterNORMAL_CACHE_COUNT.- overlay:
storageDispatcher.retrieveItem(key.getKeyBasis(), className); aLoginItemis then cached for 600 000 ms, everything else formaxCacheTime; counterPASTRY_STORAGE_COUNT.ItemNotFoundExceptionand a null payload both returnnulland countNULL_VALUE_COUNT.
Every call also counts OVERALL_COUNT. className is the per-plugin/per-class dimension of all
these counters; the dispatcher's own name is SIGNSTORAGE_DISPATCHER.
Write and delete
storeSharedItem pushes the item into the social cache (socialCache.store), into the LRU cache,
and only then submits the overlay store to a Executors.newFixedThreadPool(5) worker; a
StoringFailedException is caught and swallowed silently. deleteSharedItem calls the framework
deleteItem(keyBasis) (which at PAST level is an overwrite with an empty GenericStorageItem<String>("")),
puts null into the LRU entry, and calls the deprecated deleteItemLocally; DeletionFailedException
is likewise swallowed.
Configuration as shipped
Source/org.lifesocial.core.utilities/resources/config/LibreSocialConfig.txt:
| Key | Shipped value | Code default | Effect |
|---|---|---|---|
socialCacheEnabled |
1 |
true |
push-based social cache on |
socialCacheUpdater |
socialscore |
socialscore |
selection strategy (random, total, trend, socialscore) |
socialCacheUpdateLimit |
2 |
— (read without default) | update channels used per item |
socialCacheUpdaterUpdateInterval |
50 |
50 |
re-rank MUC every 50 interactions |
socialCacheMUCLimit |
150 |
-1 (unlimited) |
Dunbar-sized limit of the friend list |
socialCacheBootstrapEnabled |
1 |
true |
send whole cache to a new registration |
normalCacheEnabled |
0 |
true |
LRU tier — see discrepancy below |
socialMetricCollection |
1 |
0 |
enable per-class counters |
socialCacheVerboseOutput / socialCacheSDKeyRoutingOutput |
0 |
false |
debug/trace output |
Live discrepancy worth knowing: the shipped configuration disables the LRU tier
(normalCacheEnabled = 0) while the code defaults it to true. A default 2026 run therefore serves
reads from the social cache and from PAST only, and the NORMAL_CACHE_COUNT path is dead — although
the write path still fills the LRU map only when enabled, LoginItem re-caching and isInCache()
become misleading. The related PAST-side keys are replicationFactor = 4, heterogeneityCacheSize = 50,
autoDeleteStorage = 0.
Information Cache and updaters
InformationCache is a static singleton (not an OSGi service): SharedItemCache (LRU, 2 000
entries via PluginPropertiesContainer.DefaultCachSize), NodeHandlesCache (2 000), UsrDataWaiter,
and messagesCacheMap (pluginId → Queue<AbstractBasicMessage>). The message dispatcher hands every
incoming application message to it (MessageDispatcher, InformationCache.addMsg(pluginId, message)),
and plugins poll it (friendsplugin: InformationCache.getItem(listkey)). Items are held as
ItemContainers with three load states (available / loading / missing), which is what lets a GUI show
a consistent snapshot of incomplete data. DeliveredMsgDeleter exists but its delete call is commented
out with a TODO, so delivered messages are not pruned.
The four @Component updaters (groupitemupdater, groupnameholderupdater, task equivalents) are
Observers that wait through SharedItemRequest (maxTimeElapsed = 60000, minTimeout = 10000,
threadWaitingTime = 500 ms) and then re-read via storageDispatcher.lookupSharedItem(...).
Who calls it
Call sites of the plugin API by bundle: friendsplugin 9, loginplugin 8, profileplugin / photosplugin /
messagingplugin / livechatplugin 4 each, searchplugin 2, groups 1; framework-level
getStorageDispatcher() appears 194 times (plugins, DDS, monitoring, tester, unit tests, the
addressbookapp / chatapp_secure examples). The framework-level dispatcher is additionally
registered as a monitoring Sensor (MonitoringThread.addSensor(framework.getStorageDispatcher())).
Design options and decision
Alternatives below are taken from the theses and papers where a decision is recorded; where the code only shows the result, the rationale is marked [reconstructed].
Direct overlay access vs. a wrapper facade. LifeSocial originally used FreePastry/PAST classes directly. The 2008 core-architecture work and the platform paper (ISM 2008) introduced thin wrappers — StorageDispatcher and MessageDispatcher — recording better performance for all network-related interactions and a stable plugin API independent of the overlay. Consolidated in LibreSocial framework 2020.
PAST as persistence, with mutability bolted on. PAST
(SOSP 2001,
2001 caching) is append-only and immutable, but an
OSN needs update and delete. The chosen compromise is a fetch–modify–re-put at the framework layer
(lookup, then signChange(existingItem.getNonceForVersion()), then insert) and a delete as an
empty-payload overwrite. Podrajanski 2008
lists the open problems of this shortcut: replica convergence between concurrent writers, access
control at the storage layer, and proving that the requester may write the identifier — the first two
were later addressed by encrypted/signed structures
(CTS 2014,
access control), the third remains open.
Local persistent cache vs. memory-only cache. A local folder per user and network existed
(localstorage bundle, see Alviṭe 2008);
the 2011 project group folded "local storage" into the storage dispatcher
(PG 2011 final report), and in January 2014
the file-backed tier was deprecated in favour of the memory cache — the disk path was a stale-copy and
cleanup liability (files older than 60 s had already been dropped at lookup in 2011) and is now an
application concern: file-level persistence/sync is implemented in a plugin, with only authorization
data stored in the overlay (Gao 2015).
Why the removal happened is [reconstructed] — the Javadoc states the fact, not the reason.
Pull vs. push toward plugins. Explicitly argued in Podrajanski 2008: event propagation through the Information Cache (pull) was chosen over notifying plugins directly, because it keeps plugins loosely coupled and avoids duplicate object instances; the accepted cost is periodic cache polling by plugins and updaters. (Messaging later moved to push channels — see messaging — but the storage side is still pull.)
Time-window/LRU caching vs. social caching. The pre-2020 design is pure freshness windows:
20 s default, 10 s floor, Integer.MAX_VALUE for "never expires", LRU eviction at 200 entries —
correctness relies on expiry alone. The ISNCC 2020 work
(ISNCC 2020,
dissertation 2020) replaces
"wait for the window to lapse" with pushed updates: an item update is sent to a small set of
selected peers, whose caches stay fresh without asking the overlay. Measured hit ratios:
random 94.9 %, trend 93.3 %, social score 92.4 %; current (LRU/PAST) cache alone 94.5 %; social cache
alone 84.9 %; both combined 99.2 % hits, 0.8 % overlay lookups, at the price of up to about five
times as many cached objects and the highest MessageDispatcher traffic of all variants. A run with
no cache had to be aborted after roughly a quarter of the measurement because of internal Pastry
errors — which is the empirical case for caching at all.
Which peer set to push to (the same paper): random, total (all friends), trend, and
socialscore = α·tie strength + β·connection gain + γ·mean session length (α = β = γ = 1 in code).
Random has the highest hit ratio but scales badly with the number of subscriptions; social score was
chosen as the shipping default because at a nearly equal hit ratio it needs the smallest cache and
the fewest update channels (~250–400 MB per instance at 92.4 % in the paper's setting). That
preference is stated in the paper's cost discussion; the choice of socialscore in the shipped config
is consistent with it but is [reconstructed] as a direct consequence.
Structure cache — a documented alternative that is not in this bundle. Collective retrieval of
deep DDS structures was improved by a root-held key list ("structure cache",
WPMC 2016):
N·S retrievals drop to ≈2·S, 190 s → 40 s under churn. It was not adopted: no StructureCache
type exists anywhere in Source/, and the paper itself limits it to structures that do not change
frequently (single-item retrieval degrades to 1.1–1.4 s → 18.4 s with recursive fallback). See
DDS internals.
Capacity/heterogeneity handling — decided at the PAST layer, not here.
Load balancing 2011,
Adaptive Chord 2013 and
capacity management 2020
argue for separating index from storage on heterogeneous nodes. In the current code that idea survives
only as size-capped caches at the framework layer (heterogeneityCacheSize = 50 MB capped at
maxMemory/10, a second cache capped at maxMemory/20, replicationFactor = 4, and the config note
"it is important that #strongNodes ≥ replicationFactor + 1"). Treating these as the implementation of
the indirection idea is [reconstructed].
Technical details
Key derivation. StorageKey.getKeyBasis() is the string that becomes the PAST identifier; keys are
built centrally in Source/org.lifesocial.core.main/src/org/lifesocial/core/data/utils/HashKeyBuilder.java
(buildLoginItemKey → <username><LoginPlugin><LoginItemToken>, plus group, group-name-holder, task,
task-name-holder, network and random-key builders). A commit in the bundle history changed the hashing
used when a SharedItem is converted to a StorageItem, so key layout is version-sensitive across
the 2011→2015 history.
Constants (SignStorageDispatcher): CACHE_DEFAULT_CACHE_TIME = 20000 ms,
CACHE_MIN_CACHE_TIME = 10000 ms, CACHE_SIZE = 200, LoginItem re-cache 600000 ms,
className = "SIGNSTORAGE_DISPATCHER", thread pool 5. SharedItemCache / UsrDataWaiter:
DefaultCachSize = DefaultUsersCachSize = 2000
(informationcache/utils/PluginPropertiesContainer.java).
Freshness rule isOutdated(): values < CACHE_MIN_CACHE_TIME are raised to 10 s;
Integer.MAX_VALUE means "never outdated"; otherwise the container timestamp must be newer than
now − maxCacheTime. The Javadoc notes the LRU eviction can outlive any maxCacheTime.
Concurrency. All memoryCache access is inside synchronized (this) blocks; SocialCache
pruning uses an AtomicBoolean busy guard for the re-ranking pass. InformationCache state is
static, so it is shared by every bundle instance and is not reset on bundle restart.
Metrics. Per-class counters go to SocialDataCollectionImpl, which stores CLASS_METRIC keys in a
static HashMap (com.p2pframework/src/com/p2pframework/datacollection/social/) and is gated by
socialMetricCollection: OVERALL_COUNT, SOCIAL_CACHE_COUNT, NORMAL_CACHE_COUNT,
PASTRY_STORAGE_COUNT, NULL_VALUE_COUNT; the social cache adds SOCIAL_CACHE_REGISTER,
SOCIAL_CACHE_UNREGISTER, SOCIAL_UPDATES_RECEIVED, SOCIAL_BOOTSTRAP_RECEIVED,
USED_UPDATE_CHANNELS, SOCIAL_CACHE_SIZE, MUC_LIST_SIZE,
SOCIAL_CACHE_ID_REQUEST_FROM_CACHE / _FROM_OVERLAY. The framework-level dispatcher exposes
STORAGEDISPATCHER_* attributes (used size, element count, cache statistics, average lookup/store
time, redirections, hop count) as a monitoring Sensor — see
monitoring. With socialCacheSDKeyRoutingOutput = 1 each lookup
logs >SD< SC|NC|PS: <key>, the trace used to produce the hit-ratio figures above.
Social cache protocol (utils/SocialCachingMessage, payload strings): REGISTER (carries the
initiator's own collection), BOOT (bootstrap: full cache if socialCacheBootstrapEnabled, otherwise
only the own LoginItem), UNREGISTER, and item updates. Peers register into each other's
multipoint-capable MessageChannels obtained from the framework; at most
socialCacheUpdateLimit channels are used per update. The MUC (friend) list is capped at
socialCacheMUCLimit and re-ranked every socialCacheUpdaterUpdateInterval interactions.
Known rough edges in the 2026 code (observed, not inferred): debug System.out.println markers in
the hot lookupSharedItem/storeSharedItem/loadItemFromCache paths; empty catch blocks around
StoringFailedException and DeletionFailedException, so a failed overlay store leaves the caller
with a cached-but-unstored item; DeliveredMsgDeleter's delete commented out; the method name
pruneUpateChannel (typo) in the public surface of SocialCache; no versioning/consistency check at
the plugin layer (the nonce-based protection exists only at PAST level).
Java-17 note: KryoLRUCache in the PAST layer was changed from Kryo's removed
UnsafeOutput/UnsafeInput to standard Output/Input ("Modified by Lukas Mueller 2026"), with a
FIXME about the hardcoded class registrations.
Evolution and supersession
| When | Change | Evidence |
|---|---|---|
| 2007–2008 | LifeSocial.KOM moves from direct FreePastry use to dispatcher wrappers; Information Cache with LRU + three load states designed | Podrajanski 2008, ISM 2008 |
| 2008 | storage/localstorage split into OSGi bundles | Alviṭe 2008 |
| 2011-11-02 | bundle created as com.sign.storagedispatcher (305db210b) |
PG 2011 final report |
| 2011-11-16 / -17 | local storage implemented by the dispatcher (e3a9ac55f); cache added, files older than 60 s dropped at lookup (26c9084c5) |
Git history |
| 2013-07-09 | renamed com.sign.storagedispatcher → com.p2pframework.storagedispatcher (ba14eeb63) |
PG 2012 final report |
| 2014-01-23 | ILocalStorage deprecated: "no local storage anymore. Only memory cache is used" |
Javadoc, edit note C. Holomek |
| 2015-02 | package refactor into org.lifesocial.middlewarestorage.* (0e5dab546, 42464327e sharedItem hashing); named threads (d043cd318); TimeoutException forwarded to the front end (08f883568) |
Git history, PG 2013 final report |
| 2019-10-28 / 2020 | social cache by Moritz Kanzler (6af1a4a75); published and consolidated |
ISNCC 2020, dissertation 2020 |
| 2025-04 | exception handling corrected (ed81bc1f7), Java-version compatibility work (583d9d6ff); baseline on modern hardware: lookup 11.50 ms, store 0.048 s at N = 2 |
Imam 2025 |
| 2026-04/06 | Gradle build (a07624e41), bnd.bnd (2d9d29420), OSGI-INF XML → component/service annotations (189018957), OpenRewrite pass (3a9e918d0), JavaSE-1.7 → JavaSE-17 (6b651a1e1) |
Git history |
| 2026-07-10 | social-cache defect batch (16398a707): MUC overflow pruning, pruneCache ConcurrentModificationException, connectionGain stub returning 0, MSL denominator, update-channel limit cap, AtomicBoolean race |
Git history |
Not superseded: the two-layer split (plugin facade / framework PAST dispatcher), the pull model
toward plugins, and PAST as the persistence substrate are all still current in 2026.
Still open: the normalCacheEnabled = 0 vs. true mismatch; swallowed store/delete failures;
the unused structure-cache idea; and no cache invalidation for items written by other peers when the
social cache is disabled. See the development blog for the corresponding work items.
Related publications
Storage substrate and the dispatcher design: PAST: A large-scale, persistent peer-to-peer storage utility (2001) · Storage Management and Caching in PAST (2001) · A Peer-to-Peer based Framework for Large-Scale Social Networking Platforms (2008) · Design and Implementation of a Service-oriented, Dynamic and Modular P2P Platform using OSGi (2008) · LifeSocial – Masterpraktikum: Entwurf und Implementierung neuer Plug-ins (2008) · Development of LifeSocial Plug-ins — Quick Start (2009) · A Distributed Platform for Multimedia Communities (2008)
Project-group implementation reports covering the bundle: PG 2011 Final Report (2012) · PG 2012 Dokumentation (2013) · PG 2013/14 Final Report (2014)
Caching, capacity, security and the DDS interaction: Caching Structures for Distributed Data Management in P2P-based Social Networks (2020) · Distributed Data Structures Improvement for Collective Retrieval Time — Structure Cache (2016) · Data Synchronization and Local Data Access across Peer-to-peer Social Networks (2015) · Adaptives Loadbalancing für strukturierte P2P-Netzwerke am Beispiel von Chord (2011) · Adding Capacity-Aware Storage Indirection to Homogeneous Distributed Hash Tables (2013) · Secure Distributed Data Structures for Peer-to-Peer-based Social Networks (2014) · Sets, Lists and Trees: Distributed Data Structures on Distributed Hash Tables (2016) · Capacity Management Protocol for a Structured P2P-based OSN (2020)
Consolidation and current state:
LibreSocial: A peer-to-peer framework for online social networks (2020) ·
Peer-to-Peer Mechanisms for Fully Decentralized, Secure and Scalable OSNs (2020) ·
Systematic Benchmarking of a Fully Distributed Communication System (2018) — storage dispatcher saturates at ≈90–100 kB/s while the message dispatcher reaches 1.7 MB/s ·
Benchmarking a Distributed Framework for Social Networks (2013) — documents heterogeneityCacheSize ·
Reviving LibreSocial: Error Fixes and a Baseline Evaluation on Modern Systems (2025)