Interfaces (agents)

NCommet's functionality is spread across several interfaces, often referred to as agents:
  • IPersister, which is responsible to store items and everything about them (including content objects) to a persistent medium (typically a database).
  • IDaoEventsSink, which is responsible to propagate item related events originating at the persister.
  • ITypedTreeValdiator, which enforces validation rules on the trees, usually rules about the itemType of the items.
  • IAuthorizationManager, which enforces role based authorization on several operations, protecting items based on their assigned access level.
  • IWhoAmI, which provides roles and user information to IAuthorizationManager
  • ISorter, which sorts a list of items based on a field of their content.
  • ISearcher, which performs a text search on items.

ISorter and ISearcher are not used by NCommet.Core, but can be used by your application. There's a default implementation for every agent (except ISearcher) in NCommet, separated in their own assemblies. You can download a component diagram that depicts NCommet.Core using the agents through their default implementation.

Please note that you can create and use your own implementations for any agent you wish. NCommet's architecture is modular and pluggable: you can dynamically change the implementation of any agent. You can read more about that at the bottom of this page, in the section of NCommetContainer and Configurator.

Persistence

The IPersister interface contains all the required methods to store, retrieve and delete NCommet's objects (Item, RelItem and content objects which are instances of subclasses of ContentBase).

Some of the methods it contains are methods that allow the following tasks:
  • Retrieve, Store and Delete an Item.
  • Retrieve all the Items or Items that match specified criteria (i.e. name, item type and tags).
  • Retrieve all the Items that have a content object with a property containing a given string.
  • Retrieve all the root items in the hierarchy (i.e. items that have no parent), optionally based on their item type.
  • Retrieve the children of an Item filtered by their item types or their tags.
  • Retrieve all the relative items of an Item filtered by their relationship type or the type of the relative item.
  • Methods that support transactions.
  • Methods that answer whether an item is stored or transient (i.e. in-memory only).
  • A method that provides detailed information about the Persister MetaData.

Authorization

NCommet supports authorization, protecting some of its functions based on the rights of a certain role (the role is an entity "outside" NCommet). The rights are defined inside NCommet. These rights are:
  • None: No right.
  • View: Right to retrieve an item from the persistent storage.
  • Edit: Right to save an item to the persistent storage.
  • Delete: Right to delete an item from the persistent storage.
  • Detach: Right to detach an item from its parent.
  • AddChild: Right to add a child to a parent item.
  • Everything: All of the above rights.
These basic rights can be combined together. This combination is given to an Item for a specified role. The role is an entity that's "outside" the authorization part of NCommet. This means that NCommet is responsible to set and manage the rights on an item for a specified role and the roles are provided from another system.

The interface that supports authorization is called IAuthorizationManager. As we said earlier, this interface is foreign to the system that provides the roles. The system that provides the roles must implement the IWhoAmI interface. IWhoAmI is an interface that gives all the roles of a user (called IPrincipal), the roles of the system in overall and the current user (IPrincipal).

IAuthorizationManager supports the following operations:
  • Check if a specified role has explicit access rights on a given item.
  • Get the access level that a specified principal has on a given item.
  • Get the access level that a specified role has on a given item.
  • Explicitly assign perimissions for a specified role on a given item.
  • Remove all explicitly assigned permissions that a specified role has on a given item.
  • Filter the children of acgiven item, returning only those items on which the given principal has the required permissions.
  • Check if the current logged-in user has the specified permissions on a given item.
  • Return all the roles that have the given access level on a given item.
The authorization checks are performed in NCommet.Core only if there is an available implementation of IAuthorizationManager. If not, these checks are not performed (it's as if the user was assigned with the Everything access level).

Rules (Typed Tree Validation)

Another feature that's supported by NCommet is the validation of an item tree based on rules. The rules that are supported are the following:
  • Whether an item can be set as root in the hierarchy (i.e. with no parent).
  • Whether an item can be attached to another item (i.e. set as a children).
  • Whether an item can be removed from its parent.
  • Whether a ContentBase object can be set as the content of an item.
These four rules are checked each time a related operation is performed. We have to note here that authorization is performed before validation. So, for example, if a user doesn't have the role to delete an item from its parent the action will not performed along with the validation of whether that item could have been detached from its parent in the first place.

The interface that supports this functionality is ITypedTreeValidator. The checks that are performed are based on the implementation. The goal is to keep the items tree valid at all times. If one rule has been violated a ValidationException is thrown.

ITypedTreeValidator also contains methods to:
  • Get all the valid child item types for a given item.
  • Get all the valid item types for a root item.
  • Get the valid content types for a given item.

Sort

Even though NCommet itself doesn't use a sorting mechanism, it provides the ISorter interface, that sorts a list of items based on a field of their content. The interface contains only one method (Sort), which accepts a list of item ids and the field on which the sorting is based, given as an integer. The meaning of this integer is based on the implementation of the interface and is used to distinguish the field of the content class that is used for sorting. The method returns the sorted list of the provided items.

Search

NCommet provides the ISearcher interface, which defines a text search engine. The interface states that there are logical categories (defined by the application) on which at most one value per item is stored. Typically, the application matches one text field to a category. The search can be performed to specific categories. For example if an index is created for the categories "firstName" and "surname" the search can be performed only on the surname.

ISearcher defines methods to:
  • Insert content for a given item id into the index. The content is divided into logical categories (or fields). Each category matches a numeric value defined by the application.
  • Update the indexed content for a given item id.
  • Delete the indexed content for a given item id.
  • Search the index for a given text. The text is only searched in the designated categories.
  • Spot the exact area inside the string (TextToSpot) where string we want to find (TextToFind) make a match. This method is useful when the implementation does not require TextToSpot to be equal to TextToFind, e.g. when the implementation takes into consideration grammar and linguistic elements, providing more intelligent results.

NCommetContainer: accessing the concrete classes

Interfaces are the key to provide a modular design, however the implementations of the interfaces make the actual work. NCommetContainer is a signleton class that holds references and provides access to the actual implementations of IPersister, ITypedTreeValidator, etc. For every agent, NCommetContainer has a matching property, for example IPersister's implementation can be found at NCommetContainer's Persister property. In essence, NCommetContainer acts as a central object repository that can point you to the used implementation of an agent.

Download class diagram

Configurator: automatically plugging implementations in NCommetContainer

NCommetContainer owns the references to the implementations of the agents, but has no idea who they are. You can of course assign manually your implementations but there's an easier solution: Configurator. Configurator uses the application's configuration file to automatically instantiate and assign all available agents implementations.

Download sequence diagram

Last edited Jun 29, 2010 at 7:57 PM by kingherc, version 16

Comments

No comments yet.