LibreSocial · Documentation

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):

  1. socialCache.lookup(key) — if socialCacheEnabled — hit → counter SOCIAL_CACHE_COUNT.
  2. loadItemFromCache(key.getKeyBasis()) — LRU memoryCache (200 entries) — hit and not isOutdated() → counter NORMAL_CACHE_COUNT.
  3. overlay: storageDispatcher.retrieveItem(key.getKeyBasis(), className); a LoginItem is then cached for 600 000 ms, everything else for maxCacheTime; counter PASTRY_STORAGE_COUNT. ItemNotFoundException and a null payload both return null and count NULL_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.

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)