LibreSocial · Documentation

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:

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

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

Message and storage integration

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