Writing a Settings Storage Provider

In this short article we are going to learn how to write a simple Settings Storage Provider for ScrewTurn Wiki 3.0 (STW from now on). A Settings Storage Provider is a type of plugin that handles storage of system data and configuration.

Introduction to Settings Storage Providers¶

This brief section assumes you have already a general knowledge on STW providers.

The main tasks a Settings Storage Provider performs are:

• store system configuration entries
• manage the log
• manage "meta" data items (content of header, sidebar, footer, etc.)
• manage the list of recent changes in the wiki
• store plugin assemblies and their configuration
• store and manage Access Control List (ACL) entries
• store the graph of links between pages.
  

For its nature, a Settings Storage Provider cannot be read-only.

System Configuration¶

System configuration consists in a list of key, value entries, both strings, not allowing new-lines or pipes.

The following methods are used by the wiki application for managing system configuration:

• GetSetting gets the value of a setting (key), if it exists
• SetSetting sets the value of a setting
• GetAllSettings gets all the settings (key, value)
• BeginBulkUpdate begins a bulk-update operation (in a bulk-update, many settings are set in sequence, then saved all at once)
• EndBulkUpdate ends a bulk-update operation, saving all the modified keys at once.
  

Log Management¶

The log consists in a list of entries, each represented by an instance of the LogEntry class, that contains a message, the user associated with the logged operation, the level (Error, Warning, General) and the date/time the entry was recorded.

The following methods are used by the wiki application to manage the log:

• LogEntry adds an entry to the log, only when the currently configured logging level allows the operation (see the LoggingLevel system configuration setting) and setting the entry date/time to the current time, and also truncating old entries when the size of the log exceeds the MaxLogSize system configuration setting
• GetLogEntries gets all the log entries, sorted by date/time, oldest first
• ClearLog clears the log.
• LogSize (property) gets the size of the log (in KB).
  

Meta Data Items Management¶

Meta data items are pieces of content like the header, sidebar and footer. They're namespace-specific, thus each method that handles them has a "tag" parameter that is generally used for distinguishing the namespace (but might be used for other purposes in the future). Valid items are defined in the MetaDataItem enumeration.

The wiki application calls the following methods:

• GetMetaDataItem gets the value of the specified meta data item, if any (return an empty string otherwise)
• SetMetaDataItem sets value of the specified meta data item.
  

Recent Changes Management¶

Recent changes describe the last activities performed by users in the wiki, such as page editing. Each entry, represented by the RecentChange class, contains information such as the date/time of the change, the author, the page affected, the title of the page or the subject of the message (if the change refers to a message rather than a page), and so on. Any of these properties might be null, depending on the information available when the entry is generated by the application.

The following methods are used by the wiki engine to manage recent changes:

• GetRecentChanges get all the recent changes, sorted by date/time, oldest first
• AddRecentChange adds a new recent change, and should also truncate old entries when their number exceeds the MaxRecentChanges system configuration setting.
  

Plugins Management¶

Plugin assemblies are stored by the Settings Storage Provider, which also handles plugins configuration.

The following methods take part into the plugins management:

• ListPluginAssemblies lists all the available plugin assemblies
• StorePluginAssembly stores a plugin assembly (reading from a byte array)
• RetrievePluginAssembly retrieves a plugin assembly as a byte array
• DeletePluginAssembly deletes a plugin assembly
  

• SetPluginStatus sets the status of a plugin (enabled or disabled) identified by its full type name
• GetPluginStatus gets the status of a plugin (enabled or disabled) identified by its full type name
  

• SetPluginConfiguration sets the configuration string of a plugin, if any
• GetPluginConfiguration gets the configuration string of a plugin, if any.
  

ACL Management¶

ACL management is done via the provider's AclManager read-only property, that returns an instance of a class that implements the IAclManager interface. Such interface allows the wiki engine to store and retrieve instances of the AclEntry class, containing:

• the subject (string, e.g. a user or a group)
• the resource (string, e.g. a page or a directory)
• the action (string, e.g. delete)
• the value (Value enumeration, e.g. grant or deny).
  

The IAclManager interface defines the following methods:

• StoreEntry stores an ACL entry, overwriting any previous entry for the same subject, resource, action
• DeleteEntry deletes an ACL entry
• DeleteEntriesForResource deletes all entries for a given resource
• DeleteEntriesForSubject deletes all entries for a given subject
• RenameResource renames a resource wherever it's used in ACL entries
• RetrieveAllEntries retrieves all the ACL entries
• RetrieveEntriesForResource retrieves all the ACL entries for a given resource
• RetrieveEntriesForSubject retrieve all the ACL entries for a given subject
• InitializeData is a method that can be called by the Settings Storage Provider if it needs to initialize entries on application startup
• TotalEntries (property) returns the number of ACL entries stored
• AclChanged is an event that should be fired every time an entry changes, providing information about the change.
  

Page Links Graph Management¶

The wiki application stores an (oriented, possibly cyclic) graph of links between pages. Such graph is managed using the following methods:

• StoreOutgoingLinks stores the links that from a given page point towards a set of other pages (even non-existing) and overwriting all previous links for the given page
• GetOutgoingLinks gets all the links that from a given page point towards other pages
• GetAllOutgoingLinks gets all the links for all pages, in a IDictionary<string, string[]> where the key is the source page
• DeleteOutgoingLinks deletes a page from both sources and destinations of the link graph (basically, it completely removes a page)
• UpdateOutgoingLinksForRename updates all the links (sources and destinations) after a page has been renamed.
  

Miscellanea¶

The following methods are also defined and used:

• IsFirstApplicationStart returns true if the application has been started for the first time and initial data structures must be created.