Plugin System — OSGi bundles, Declarative Services, commands
The 17 application bundles under Source/org.lifesocial.plugin.*, the Equinox/SWT shell bundle
Source/org.lifesocial.ui, the command layer, and the appstore with its framework-side counterpart
com.p2pframework.appstore. Related: messaging, StorageDispatcher.
Purpose
LibreSocial's application features are not compiled into the peer: wall, friends, messaging, photos, groups, forum, chat, calendar, voting, file hosting, search, profile, login, notifications, web front end, appstore and the command router are each an OSGi bundle registering services and wired to its neighbours by Declarative Services at run time, sitting above the P2P framework and below the user-facing interfaces (Jetty/REST web provider, Equinox console). Its four jobs:
- Modularity with enforced boundaries — a bundle exports only its
apipackage;componentstays private, so a plugin is replaceable without recompiling anything else. Activation is lazy: an absent plugin simply leaves its services and commands unregistered. - Dynamic composition — dependencies resolve by service interface plus cardinality/policy
(
@Reference), not bynew; cross-plugin listeners (friends, notifications, group content) are themselves services, so features can be added while running. - One command surface — every plugin publishes
<PluginID>.<Command>commands; console, test framework and (historically) the GUI use the singleICommandsComponentservice. - Runtime distribution — the appstore publishes app bundles as DHT storage items and installs them
with
installBundle("file:///…"), so new bundles arrive over the overlay, not a central server.
Current implementation (as of 2026)
17 plugin bundles are built and wired into the product; four sample bundles exist only as appstore
payloads. Counts from the working tree; 130 @Component declarations across the 17 bundles.
Directory (Source/…) |
Bundle-SymbolicName |
files / lines | @Components |
|---|---|---|---|
org.lifesocial.plugin.appstore |
org.lifesocial.plugin.appstore |
26 / 2 392 | 1 |
org.lifesocial.plugin.calendar |
org.lifesocial.plugin.calendar |
10 / 966 | 6 |
org.lifesocial.plugin.commands |
org.lifesocial.commands |
3 / 325 | 1 |
org.lifesocial.plugin.filestorage |
…plugin.filestorage;singleton:=true |
12 / 1 118 | 2 |
org.lifesocial.plugin.forum |
org.lifesocial.plugin.forum |
15 / 1 144 | 5 |
org.lifesocial.plugin.friendsplugin |
org.lifesocial.friendsplugin |
27 / 3 261 | 22 |
org.lifesocial.plugin.groups |
…plugin.groups;singleton:=true |
31 / 3 234 | 12 |
org.lifesocial.plugin.livechatplugin |
org.lifesocial.livechatplugin |
19 / 2 209 | 14 |
org.lifesocial.plugin.loginplugin |
org.lifesocial.loginplugin.component |
12 / 2 004 | 7 |
org.lifesocial.plugin.messagingplugin |
org.lifesocial.messsagingplugin (sic) |
15 / 1 942 | 11 |
org.lifesocial.plugin.notifications |
…plugin.notificationplugin |
8 / 1 136 | 1 |
org.lifesocial.plugin.photosplugin |
org.lifesocial.photosplugin |
17 / 2 680 | 14 |
org.lifesocial.plugin.profileplugin |
org.lifesocial.profileplugin.component |
15 / 2 505 | 11 |
org.lifesocial.plugin.searchplugin |
org.lifesocial.searchplugin |
11 / 1 137 | 8 |
org.lifesocial.plugin.voting |
…plugin.voting;singleton:=true |
13 / 1 547 | 9 |
org.lifesocial.plugin.wallplugin |
org.lifesocial.wallplugin |
12 / 1 760 | 5 |
org.lifesocial.plugin.webprovider |
org.lifesocial.plugin.webprovider |
44 / 7 614 | 1 |
org.lifesocial.ui (shell) |
org.lifesocial.ui;singleton:=true |
4 / 476 | 0 |
Directory names and symbolic names drift systematically (org.lifesocial.wallplugin inside directory
org.lifesocial.plugin.wallplugin), and the typo messsagingplugin is load-bearing:
cnf/org.libresocial.launcher.common.bndrun selects bundles by osgi.identity.
Build and runtime wiring
- Gradle multi-project build; each bundle applies
osgi-bundle-conventions.gradleinbuild-logic: Java 17 Adoptium toolchain,srcDirs = ['src'], resources fromresourcesandconfig, jar metadata delegated to bnd 7.2.3 reading a per-bundlebnd.bnd. bnd.bndcarriesBundle-ActivationPolicy: lazy,Bundle-RequiredExecutionEnvironment: JavaSE-17, an explicitExport-Package(onlyapi/component/utils|model), anImport-Packagelist closed by*, and a small legacyRequire-Bundleblock;-dsannotations: *with-dsannotations-options: inheritgenerates theOSGI-INF/*.xmldescriptors, so no hand-written component XML remains.- Runtime resolution lives in
cnf/*.bndrun:-runfw: org.eclipse.osgi,-runrequiresnaming the launcher, core bundles, all 17 plugin bundles andorg.lifesocial.ui,-runproperties: eclipse.product=org.lifesocial.ui.product. DS comes fromorg.apache.felix.scr 2.2.14, the console from the gogo bundles; SWT is excluded from Maven and supplied fromSource/org.lifesocial.ui/lib-dist. org.lifesocial.uiis only the application shell in 2026:Application.java(373 lines) starts the workbench, runs registered exit actions from a shutdown hook, and skips Display/tray creation whenGraphicsEnvironment.isHeadless()— what makes the Docker image work (compose.yaml: 9001 overlay, 8443 web UI, 10001 console). Its extension points areorg.eclipse.core.runtime.applications/…products(productorg.lifesocial.product.lifesocial, dormantMonitoringFP) andorg.lifesocial.ui.autorun, which nothing contributes to.
Service wiring inside a plugin
Source/org.lifesocial.plugin.wallplugin/src/org/lifesocial/wallplugin/component/WallPlugin.java:
@Component(name = "WallComponent", immediate = true, service = IWallPlugin.class)
public class WallPlugin implements IWallPlugin, IFriendsListener, INotificationPluginListener {
@Reference(name = "FRAMEWORK", policy = ReferencePolicy.DYNAMIC, unbind = "unsetFramework")
public synchronized void setFramework(Framework f) { … f-splitSize … }
@Reference(name = "FriendsPlugin", unbind = "unsetFriendsPlugin")
public synchronized void setFriendsPlugin(IFriendsPlugin fp) { registerFriendsListener(); }
Binding is registration: the wall subscribes to friends and notifications as soon as those services
appear, and DYNAMIC policy lets them vanish without restarting the component. ForumPlugin shows the
producing side — @Component(name = "org.lifesocial.plugin.forum", service = { Sensor.class,
IGroupContentContributor.class, IForumPlugin.class }) — one class as sensor, group content contributor
and forum API. SPIs in use: IFriendsListener, INotificationPluginListener,
IGroupContentContributor/IGroupContentObserver/IInvitationObserver
(org.lifesocial.plugin.groups/api), IWallEventListener, MessageListener, and framework-level
Sensor (com.p2pframework.message.aggregate).
Command layer
org.lifesocial.core.main/src/org/lifesocial/core/commands/holdsICommands,AbstractCommands(aMap<String, ICommandHandler>keyed by fully qualified command name),AbstractCommandHandler,ICommandHandler.- Each plugin defines
Abstract<Plugin>CommandHandlerplus one aggregate<Plugin>Commands(friendscommands,WallCommands, …), and every handler is its own OSGi component, e.g.@Component(name = "friendsrequestfriendcommand", service = AbstractFriendsCommandHandler.class); names come from the plugin'sPluginPropertiesContainer(WallPlugin.RetrievePosts). org.lifesocial.commands(CommandsComponent, 325 lines) collects allICommandsservices in asynchronizedSet, splits input on the first space, and returnsCommandNotAvailableMsgwhen no plugin claims the verb — the 2009 semantics (commands exist only while the plugin is active) holds. The asynchronous "…Loaded" queries (FriendsListLoaded,ProfileCompletelyLoaded) are still present.- Three consumers bind
ICommandsComponent:org.lifesocial.equinoxconsole(gogoCommandProvider, port 10001 in Docker),com.p2pframework.tester, and webprovider (ConsolePluginHandler).
Message and storage integration
IMessageDispatcher(org.lifesocial.messagedispatcher.api):sendMessage(usrname, msg, className),checkForUndeliveredMessages(pluginId, username, className),registerMessageListener(MessageListener, pluginID). The implementation keepsMap<String, MessageListener>— one listener per plugin id, so components sharing an id silently overwrite each other.classNameis the metric label (PLUGIN_WALL,PLUGIN_FRIENDS, …).- Offline recipients:
storeUndeliveredMessage()writes the payload viaIStorageDispatcher.storeSharedItem(msg, className)and appends its storage key to a per-plugin, per-userKeyHolderItem(createHolderKey(pluginId, username)). - The 2008 pull model survives in one place:
PluginMsgsCacheChecker(com.p2pframework.storagedispatcher/…/informationcache/caches/) is instantiated only byLiveChatPlugin(lines 179, 844). - Persistence goes through the
StorageDispatchercomponent, and for collections directly through DDS:WallPluginkeepsDistributedLinkedList<String> wallPostsplus one comment list per post;GroupsPlugindefaults toint splitSize = Integer.MAX_VALUE. - Legacy interface
org.lifesocial.core.commoninterfaces.Plugin(getPluginId,pluginMsgsAvailable,@Deprecated init()/terminate()) is still the supertype ofIFriendsPlugin,ILoginPlugin,IProfilePlugin,ISearchPlugin,IVotePlugin,IWallPlugin; several implementations keep astatic getInstance()singleton beside injection.
Configuration parameters
org.lifesocial.core.utilities/src/org/lifesocial/utilities/ConfigLoader.java loads
config/LibreSocialConfig.txt from the classpath (resource in
Source/org.lifesocial.core.utilities/resources/config/). Plugin-relevant keys, 2026 values:
measuringData = 1, socialMetricCollection = 1, dds_split_size = -1 (infinite),
dds_linkedlist_consolidation = true, replicationFactor = 4, CanYouProvideTimeOut = 7000;
DEFAULT_RETRIEVAL_COUNT = 10 is the wall's paging default when only an offset is given.
Runtime-installed apps
org.lifesocial.plugin.appstore (AppstorePlugin, UserToolKit, PublisherToolKit,
AppstoreClient, AppstoreDataClient) plus com.p2pframework/src/com/p2pframework/appstore/
(AppstoreServer, AppstoreDataServer, AppstoreData, SignedAppstoreData). Model objects are storage
items — PluginMeta, VersionMeta, PluginObjectFile, PrivatePublisherRepository,
PrivateUserRepository, each with a …StorageItem wrapper and generateKeyValue(). Installation is
literal OSGi: UserToolKit.installPlugin() builds "file:///" + getPathToPluginFolder() +
File.separator + key (default folder /apps/) and calls commonBundleContext.installBundle(file);
uninstallPlugin(AllVersions) calls Bundle.uninstall(); bootInstallPlugins() re-installs the saved
set at start-up. The four org.lifesocial.plugin.appstore.samples.* bundles are classic UI plugins
(plugin.xml contributions to org.eclipse.ui.commands|menus|views), deliberately absent from
-runrequires; they exist to be published and installed.
Web front end as a plugin
webprovider (7 614 lines) starts a Jetty 12 Server with GzipHandler and
WebSocketUpgradeHandler on TLS port PORT = 8443 (constant declared twice, lines 68 and 140).
RESTHandler routes baseRequest/target (e.g. photos/getalbumlist) through the
loggedInHandlers/loggedOutHandlers maps, one handler per plugin (18 classes under
…webprovider/PluginHandlers/); plugins that push events register into the static PluginRegistry
(HashMap<String, IWebProviderPlugin>) and reach the browser via NotificationSocket. Handlers call
plugin APIs or ICommandsComponent.execute(...) — the front end never imports an implementation class.
Design options and decision
(1) Static registration in one JAR vs. an OSGi module system. Until 2008 everything shipped in one
jar with plugins registered statically in a central MainSystem —
Updating the core LifeSocial library (2009)
exports it with Main-Class: main.MainSystem.
Alviṭe 2008 gives the reason for the
switch: the monolith forces recompile plus restart for every change, and a jar is a flat classpath — no
versioned dependencies, no run-time resolution, no information hiding, shadowed duplicates surfacing as
LinkageError. Since a peer's feature set must grow while running (later even over the overlay), the
monolith is ruled out. Chosen: OSGi R4 with Declarative Services. Recorded trade-offs: steeper
learning curve, few complex DS examples then; Import-Package beats Require-Bundle; DS forced removal
of the login↔profile cyclic dependency by moving createUserProfile into the command layer. The same
paper weighs Knopflerfish (BSD), ProSyst mBedded, Samsung and Hitachi, and picks Equinox: EPL, free,
matching the Eclipse tooling in use, pinned to the then-stable 3.4 (17 June 2008). In 2026 the framework
is still org.eclipse.osgi, with the DS implementation now from Felix scr 2.2.14.
(2) Service wiring vs. extension points vs. inheritance. All three were used; each survived where it
fits. Inheritance: the 2008 practikum solved shared group behaviour with the abstract base class
GroupEnabledPlugin (join/leave, message distribution, per-instance group storage in
GroupNamesItem/GroupUsersItem/GroupMessageHistoryItem) — quick to use, but it couples every feature
to one implementation, and it is gone from the tree, as are the whiteboard, tic-tac-toe and
address-book plugins of that batch
(Writing Praktikum Plugins 2008, and
LifeSocial Commands – Report 2009
notes the whiteboard existed only in that generation). Extension points (plugin.xml,
org.lifesocial.ui.autorun) fitted the RCP front end and still drive the appstore samples, but vanished
from the feature plugins when the workbench was dropped in 2013/14 — contributions are useless without a
workbench. Declarative Services won: the
2013 report records groups becoming a
service-interface extension point (IGroupContentContributor) so forum, file hosting and polls attach
content types without groups knowing their classes.
(3) GUI↔plugin coupling: direct calls vs. command bus vs. REST.
Quick Start 2009 fixes the
2009 answer: coupling runs exclusively through execute(<PluginID>.<Command> <params>) with a DS
reference on ICommandsComponent (1..1, dynamic), keeping the front end out of plugin internals and
degrading an uninstalled plugin to "Command Not Available". Cost: a stringly-typed, string-returning
interface with no compile-time checking. The 2013/14 group kept that philosophy at HTTP level — one
PluginHandler per plugin behind RESTHandler, JSON via Gson, WebSockets for push
(Final Report 2014); typed plugin APIs are
used plugin→plugin over DS only.
(4) Plugin distribution: manual install vs. central repository vs. P2P repositories. Manual install
(jar + install on the console) still works but does not scale to end users. A central app server would
be cheapest and contradicts the stated goal in
Modasia 2015 — deployment "in the network without a
central repository instance": publishers create repositories as DHT storage items (shared by publishing
the repository id), apps are PluginObjectFile + metadata with their own EC signatures, PAST-replicated
with the (k,r) scheme. Costs: no central review or revocation point, storage cost per publisher, and
metrics that never proved themselves — the 2012 test with 20 machines and 100 × 1.5 MB publications
produced implausible byte/s figures
(Final Report 2013).
(5) Where per-plugin measurements go. (Reconstructed.) The publications compare monitoring
placement for the platform — central collector, gossip, or a tree over the DHT — in favour of the tree
(SkyEye, ICPADS 2008,
IEEE P2P 2009,
dissertation 2010,
journal version 2017). The plugin
layer contributes only measurement points: a className label on every dispatcher call, a per-plugin
SocialDataCollectionImpl, a Sensor service. That keeps a central collector out of the plugin path, at
the price of a free-form string as the only join key between plugin and framework statistics — nothing
guarantees it matches the registered plugin id.
Technical details
Bundle metadata. singleton:=true where extension contributions are involved (filestorage,
groups, voting, samples, org.lifesocial.ui); lazy activation everywhere, so DS activation is the
only start mechanism apart from the activators in appstore, webprovider, loginplugin, ui.
Component metadata. @Component(name = …, immediate = true, service = …) on the plugin component;
handlers and contributors are non-immediate components under their plugin-local abstract type.
@Reference on the setter with an explicit unbind; DYNAMIC on optional collaborators (Framework,
ILogService, INotificationPlugin), static-by-omission on required ones (ILoginPlugin,
IMessageDispatcher, IFriendsPlugin). Alvite's cardinality vocabulary (0..n / 1..n / 0..1 / 1..1,
static/dynamic) now lives in annotations rather than component.xml.
Two-phase wiring. (i) OSGi binds the service; (ii) the binding method registers the application-level
listener (addNotificationPluginListener(pluginId, this)), so rebinding must be idempotent —
WallPlugin guards it with friendsListenerRegistered.
Notification plugin as event bus. INotificationPlugin.sendNotification(targetUserName,
pluginHandlerId, HashMap<String,Object> data, int kind, String messageType) plus displayNotification,
ACK messages (NotificationAckMessage) and offline storage; subscribers call
addNotificationPluginListener(pluginHandlerId, listener) with plugin-local message types
("wallentryadded"). WebRTC chat signalling rides on this bus (WebRTCNotificationSocketHandler).
Data structures in plugins. Wall: one DistributedLinkedList<String> of post ids per user plus a
comment list per post, keyed via HashKeyBuilder/StorageKeyImpl, with SecureStorageItem and
AccessControlList implementing the privacy levels (addWallPostPrivate, …AllFriends,
…SelectedFriends, …Public, changePrivacy). Groups: per-group structures with role-based keys and a
List<IGroupContentContributor>. Appstore: OperationMessage/DoneMessage remote operations against
AppstoreServer, signed SignedAppstoreData.
Integration points. Framework (DS component Framework) exposes getNetwork(),
getStorageDispatcher(), getMessageChannel(); MessageDispatcher and SignStorageDispatcher are DS
components in their own bundles; ILogService (@Component(name = "LOG")) is bound by every plugin;
ILifeSocial (LifeSocial, immediate) is what WebProvider binds for login state;
com.p2pframework.tester drives plugins purely through ICommandsComponent, making the command surface
the de-facto public plugin API for evaluation.
Known weak edges (2026). single listener per plugin id in MessageDispatcher; static registries
bypassing OSGi (PluginRegistry, AppstorePlugin.getInstance(), WallPlugin.instance assigned in a
constructor, so a second instance silently replaces the first); @Deprecated init()/terminate() still on
Plugin while shutdown runs through Application exit actions and DS deactivate; duplicated PORT
constant in WebProvider; config keys read without defaults in field initializers.
Evolution and supersession
- 2007–2008 — monolith. One jar, static registration in
MainSystem; the plugin APIPlugin(getPluginId,pluginMsgsAvailable,init/terminate) comes from Podrajanski 2008. - 2008 — OSGi conversion. Alviṭe 2008
creates the module set still recognisable (core, utilities, console, ui, the two dispatchers, and the
login/profile/friends/groups/messaging/livechat/search/photos plugins), introduces DS with
cardinalities and the
ICommands/CommandHandlersplit, and makes login a mandatory dependency of every plugin except search. Any description of LifeSocial as a single jar predates this. - 2008/09 — authoring rules. The practikum adds
GroupEnabledPluginand eight plugins; the Quick Start 2009 codifies the package patternapi/component/commands/data/utils, "exportapionly",SharedItem+Payload, per-pluginPluginPropertiesContainer, GUI binding viaICommandsComponent; the command reference 2009 snapshots it. Still accurate for package and command conventions; obsolete for tooling and for the GUI. - 2011/12 — plugins move onto the framework. Final Report 2012:
dispatcher wrappers replace direct FreePastry calls, push channels replace polling (live chat was first
migrated — the surviving
PluginMsgsCacheCheckeris that leftover), DDS underpins the new wall plugin; theclassNamemetric labels date from this rewrite. - 2012/13 — groups as extension point, RCP GUI, appstore. Final Report 2013:
IGroupContentContributor, forum/file-hosting/voting as group content types, RCP perspectives and AutoLogin, appstore in four layers. The RCP parts are superseded below; the extension-via-service pattern is not. - 2013/14 — GUI replaced by webprovider. Final Report 2014:
RCP front end deleted, embedded Jetty plus HTML5/Backbone/Knockout client,
RESTHandlerrouting, notifications plugin (encrypted, offline-stored, other plugins register handlers), WebRTC chat with signalling through notifications, 15 plugins reworked. Supersedes all pre-2014 statements on GUI coupling. - 2014/15 — appstore design documented. Modasia 2015
is authoritative for repositories,
PluginMeta/VersionMeta/PluginObjectFile, publisher/user roles and the bundle lifecycleINSTALLED → RESOLVED → STARTING → ACTIVE → STOPPING → UNINSTALLED. - 2017 — bug inventory. Summary of known bugs: per-plugin defects and an alpha-test configuration, flagged as possibly outdated by its own title.
- 2020 — consolidated view. LibreSocial: A peer-to-peer framework for online social networks and Graffi 2020 present the plugin layer as one of four layers and enumerate the 2014/15 plugin set; they supersede the 2008/09 texts wherever messaging, storage or GUI details differ.
- 2025–2026 — legacy revival, then modern build. Setup guide 2025
and Revival 2025 document the
JDK 1.7.0_80 / Eclipse Indigo era and ~120 compile/start-up fixes, including OSGi resource loading
(
getResourceAsStream→Bundle.getEntry) and manifest repair. The tree has since moved to Gradle + bnd, Java 17, annotation-generated DS descriptors and Docker, so those toolchain sections are historical while the manifest findings stay valid.
Related publications
- A Distributed Platform for Multimedia Communities (2008)
- A Peer-to-Peer based Framework for Large-Scale Social Networking Platforms (2008)
- LifeSocial – Masterpraktikum: Entwurf und Implementierung neuer Plug-ins (2008)
- Design and Implementation of a Service-oriented, Dynamic and Modular P2P-based Multimedia Online Community Platform using OSGi (2008)
- Updating the core LifeSocial library (How-To) (2009)
- Development of LifeSocial Plug-ins (Quick Start) (2009)
- LifeSocial Commands – Report (2009)
- SkyEye.KOM: An Information Management Over-Overlay for Getting the Oracle View on Structured P2P Systems (2008)
- Monitoring and Management of Structured Peer-to-Peer Systems (2009)
- Monitoring and Management of Peer-to-Peer Systems (2010)
- Seminararbeiten 2011: "A Distributed Framework for Social Networks" (2011)
- A Distributed Framework for Social Networks — Final Report (Project Group 2011) (2012)
- Seminararbeiten 2012: "A Peer-to-Peer Framework for Social Networks" (2012)
- A Peer-to-Peer Framework for Social Networks — Dokumentation (2013)
- A P2P-Framework for Social Networks (2013)
- Seminararbeiten 2013: "A Peer-to-Peer Framework for Social Networks" (2013)
- A Peer-to-Peer Framework for Social Networks — Final Report (Project Group 2013/14, LifeSocial) (2014)
- Appstore for LibreSocial — A Repository based App-Management for P2P Framework (2015)
- Data Synchronization and Local Data Access across Peer-to-peer Social Networks (2015)
- SkyEye: A tree-based peer-to-peer monitoring approach (2017)
- LibreSocial Report – Summary of known Bugs (maybe outdated) (2017)
- LibreSocial: A peer-to-peer framework for online social networks (2020)
- Peer-to-Peer Mechanisms for Fully Decentralized, Secure and Scalable Online Social Networks (2020)
- Running LibreSocial: A Legacy Java Project Setup Guide (2025)
- Reviving LibreSocial: Error Fixes and a Baseline Evaluation on Modern Systems (2025)