Writing a Settings Storage Provider

Modified on Sun, 14 Feb 2010 15:05 by Dario Solera Categorized as Development, dotNET Development, Plugins and Providers
{s:Complete}

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 [ProvidersIntro|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.

((('''Important note''': all providers should be totally '''thread-safe'''.)))

==System Configuration==
System configuration consists in a list of ''key, value'' entries, both {{string}}s, 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}} [ProvidersIntro#The_IHostVDA_Interface_3|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&lt;string, string&#91;&#93;&gt;}} 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.
Meta Keywords:
Meta Description:
Change Comment:
Writing a Settings Storage Provider

Side Projects¶

About¶
