Directory specification

This specification describes the behavior that the Flower components expect from a directory implementation.

Directory entry ids

An id of a directory entry is a string starting with '#' char. The directory checks the first char of an entry identifier to distinguish path from ids. After the '#' char go a string uniquely identifying an entry within a directory. Semantics of this string may vary depending on directory implementation.

The ids and paths are interchangeable in all query methods. It is expected that a directory implementation provide the search by ids at least as fast as the search by paths, however the search by ids may be faster.

Directory entry names

A name of any directory entry must consist of only letters, digits or the following chars '#', '-', '_', '.', ':'.

An entry may not contain two child entries with the same name.

Directory entry names comparisons are case insensitive.

Directory entry paths

A directory entry path is a sequence of its ancestor names and its own name joined by '/' character. The names are ordered as '.../grand-parent/parent/child/grand-child/...'.

A path starts with '/' and specifies all ancestors starting from the root.

Directory errors

All directory service methods may throw a FaultException with DirectoryFault fault. An exact type of the fault condition is specified by the fault code:
  • InvalidArgument - An argument of a service call is empty or has invalid value.
  • AccessDenied - The operation is not permitted for the calling identity.
  • InvalidIdFormat - An id of a directory entry has invalid format.
  • EntryNotFound - The directory entry whose id or path is specified doesn't exist.
  • NameCollision - A parent entry already has a child with the same name.
  • ScriptError - Syntax or runtime error occurred in a script.
  • ServerError - Internal server error.

Path supplementation

If the parent in the Save operation or the target in the Move operation is specified as a path, the entry with that path may not exist. In this case, the deepest existing entry on the path is searched and the rest of the path is created as folders. The folders in this case each inherit ACL from its parent: all permissions are inherited as-is, but if the parent has create-children permission for a role, the same role will be granted the write permission on the created folders.

Empty subsets removal

If one of the ancestors of a removed entry is a set and the parent is a folder, the parent folder is removed if it becomes empty. This is done recursively up to the set ancestor.

Directory security

A directory implementation may implement authentication and authorization. In this case it should provide the directory permission checks.

Roles

The roles are the directory entries of type Role under the '/Roles' path.

Role name is the part of the path after '/Roles'. For example, default role 'Application' corresponds to '/Roles/Application'.

Each role has a list of associated user accounts. An account is identified by the user's domain qualified name.

A user may have multiple roles.

The roles may be nested. The nesting relationship is the parent-child relationship of the corresponding directory entries. Depth of the nesting is unlimited.

If something is permitted to a parent role, it is permitted to its children, grandchildren etc. If something is permitted to a child, it is permitted to its parent, grandparent etc. Permissions of the siblings are independent.

Access control lists

Each directory entry has an access control list (ACL) which is a set of name-value pairs associating a role (role name) with permissions. Each permission allows some action to the identities of the corresponding role. So, for an entry with an empty ACL any action is denied for all. However, there is a special role 'Administrator' that has all permissions for all entries regardless of their ACL.

There are following permissions:
  • Read - allows to see an entry. If one have no permission to read an entry, the directory behaves as if the entry doesn't exist.
  • Write - allows to update and delete an entry.
  • CreateChildren - allows to create child entries of an entry (both by inserting or moving to).

There are the following default roles:
  • Application - all external applications should have this role or its descendant role.
  • Processor - the role of all processors.
  • Administrator - the role having all permissions.

Directory scripting

Directory implementations provide scripting support via Flower.Directory.Scripting API. They obtain the scripting engine by using the default implementation of IScriptEnginePool or by calling Flower.Directory.Scripting.Setup.CreateEngine(). Thus, the scripting engine they use is initialized with the standard objects. Directory implementations wrap themselves into an instance of DirectoryObject to be available as $dir object in the scripts. They also map the input parameters to the $in object and the output parameters to the $out object.

A directory executes a script in a transaction with ReadCommited isolation level.

Data contracts

If a data contract field is marked as optional, this means that it can have null value.

DirectoryEntry

Base type for directory entries.

Each derived class of this class except DirectoryEntryInfo corresponds to a type of the entries. The DirectoryEntryInfo is used when it is required to enumerate entries without loading their payload, so the directory service provides methods returning the entries with and without payload.
  • Id: String - Id of the entry.
  • Name: String - Name of the entry.
  • CreatedOn: DateTime - When the entry was created in the directory. The property is populated if the entry is loaded from the directory; if a client creates or updates an entry, the directory ignores the property.
  • UpdatedOn: DateTime - When the entry was updated in the directory last time. The property is populated if the entry is loaded from the directory; if a client creates or updates an entry, the directory ignores the property.
  • AccessControlList: ICollection<AccessControlEntry> - Access control list of the entry. When the entry is updated, the specified list overwrites the current list in the directory.

DirectoryEntryInfo : DirectoryEntry

General information on a directory entry.

The directory returns this structure when a caller doesn't require entry type specific fields.
  • Type: DirectoryEntryTypes - Type of the directory entry. This bit-flag field has always only one bit set.

Assembly : DirectoryEntry

Assembly stored in the directory.
  • Image: Byte[] - COFF image of the assembly (the image that Assembly.Load(byte[]) accepts).

Folder : DirectoryEntry

Link : DirectoryEntry

  • Target: String - Id of the entry the link is pointing to.

Message : DirectoryEntry

  • Data: Blob - Optional. The payload of the message.

Process : DirectoryEntry

  • Workflow: String - Assembly qualified name of the workflow class of the process.

Processor : DirectoryEntry

  • Configuration: Blob - Optional. Spring.NET IoC container XML configuration containing processor service interface.

Role : DirectoryEntry

  • Users: ICollection<String> - Users assigned the role.

ServicesContainer : DirectoryEntry

  • Configuration: Blob - Spring.NET IoC container XML configuration containing services definitions.

Set : DirectoryEntry

  • MessageType: String - Assembly qualified name of the message type.
  • Capacity: Int32 - Capacity of the set. Zero for unlimited capacity.

State : DirectoryEntry

  • Data: Blob - The serialized process state.

Workflow : DirectoryEntry

  • DefinitionType: String - Assembly qualified name of the workflow class.
  • PreferredProcessors: ICollection<String> - Names of the processors which the scheduler will prefer starting the processes of this workflow. If the list is empty, any of the processors will be assigned; if at least one processor is specified as preferred, no other processor will be assigned except the preferred.

ScriptParameter

Base type for directory script parameters.
  • Name: String - Parameter name.

BoolScriptParameter : ScriptParameter

  • Value: Boolean - Parameter value.

IntScriptParameter : ScriptParameter

  • Value: Int32 - Parameter value.

DoubleScriptParameter : ScriptParameter

  • Value: Double - Parameter value.

StringScriptParameter : ScriptParameter

  • Value: String - Parameter value.

DirectoryEntryScriptParameter : ScriptParameter

  • Value: DirectoryEntry - Parameter value.

BoolArrayScriptParameter : ScriptParameter

  • Value: IList<Boolean> - Parameter value.

IntArrayScriptParameter : ScriptParameter

  • Value: IList<Int32> - Parameter value.

DoubleArrayScriptParameter : ScriptParameter

  • Value: IList<Double> - Parameter value.

StringArrayScriptParameter : ScriptParameter

  • Value: IList<String> - Parameter value.

DirectoryEntryArrayScriptParameter : ScriptParameter

  • Value: IList<DirectoryEntry> - Parameter value.

AccessControlEntry

Set of permissions of a role.
  • Role: String - Role name.
  • Permission: Permission - Permissions of the role.

Permission (enum)

Permissions which a role can have for a directory entry.
  • Read - Permission to see an entry.
  • Write - Permission to update and remove an entry.
  • CreateChildren - Permission to create children of an entry.

DirectoryEntryTypes (enum)

Directory entry type flags.
  • Assembly.
  • Folder.
  • Link.
  • Message.
  • Process.
  • Processor.
  • Role.
  • ServicesContainer.
  • Set.
  • State.
  • Workflow.
  • All = Assembly | Folder | Link | Message | Process | Processor | Role | ServicesContainer | Set | State | Workflow.

Blob

Serialized object or document.
  • Format: BlobFormat - Serialization format.
  • Data: Byte[] - The data.

BlobFormat (enum)

Object serialization formats.
  • TextXml - XML text.
  • BinXml - Binary encoded XML.
  • GZipXml - XML compressed with GZip.

Service interface

For all reading methods, if it is said that the method returns entries with their payload, the type of the returned value (DirectoryEntry derived class) depends on the type of the entry; otherwise, DirectoryEntryInfo is returned regardless of the type of an entry.

GetPathById: String

Returns the path of an entry with a specified id.

Throws EntryNotFound fault if the entry with the specified id doesn't exist.
  • id: String - The id of an existing entry.

Get: DirectoryEntry

Returns an entry with its payload by its path or id or null if the entry doesn't exist.
  • what: String - The path or id of the entry.

GetInfo: DirectoryEntryInfo

Returns an entry without its payload by its path or id or null if the entry doesn't exist.
  • what: String - The path or id of the entry.

GetChildren: IList<DirectoryEntry>

Returns child entries of an entry. The entries are returned with their payload.

If the parent entry doesn't exist, an empty collection is returned.
  • parent: String - The path or id of the parent.
  • entryTypes: DirectoryEntryTypes - The flags specifying entries of which type to return.
  • property: SortProperty - The property by which the entries are to be sorted.
  • order: SortOrder - The sorting order.
  • offset: Int64 - The zero based index of the first returned entry among found.
  • limit: Int64 - The upper limit on the indexes to return, so that max. entries returned = limit - offset. The limit less or equal to the offset means no limit.

GetChildrenInfo: IList<DirectoryEntryInfo>

Returns child entries of an entry. The entries are returned without their payload.

If the parent entry doesn't exist, an empty collection is returned.
  • parent: String - The path or id of the parent.
  • entryTypes: DirectoryEntryTypes - The flags specifying entries of which type to return.
  • property: SortProperty - The property by which the entries are to be sorted.
  • order: SortOrder - The sorting order.
  • offset: Int64 - The zero based index of the first returned entry among found.
  • limit: Int64 - The upper limit on the indexes to return, so that max. entries returned = limit - offset. The limit less or equal to the offset means no limit.

CountChildren: Int64

Counts the number of children of an entry.

If the specified parent entry doesn't exist, returns zero.
  • parent: String - The path or id of the parent.
  • entryTypes: DirectoryEntryTypes - The flags specifying entries of which type to count.

GetAncestor: DirectoryEntry

Finds the n-th nearest ancestor of an entry and returns it with payload.

If the child is specified as a path, the deepest existing entry on the path is searched and the operation is performed against it. For example, suppose one requests 0-th ancestor of type Set by the path '/Sets/Shared/Set/Subset' where 'Set' is a set and it exists, 'Subset' is a subset and it doesn't exist. Then, the set '/Sets/Shared/Set' is returned.

If the child is specified by id and it doesn't exists, the EntryNotFound fault is thrown.
  • child: String - The id of an entry or path starting from which to search for the ancestor.
  • n: Int32 - How many found ancestors to skip assuming that the search starts from the child entry itself. For example, if n = 0, and the child entry satisfies ancestorEntryTypes filter, than the child entry is returned itself. If, in the same case, n = 1, the nearest ancestor satisfying ancestorEntryTypes is returned.
  • ancestorEntryTypes: DirectoryEntryTypes - The bit-flags specifying entries of which types are to be returned.

GetAncestorInfo: DirectoryEntryInfo

The same as GetAncestor, but returns the ancestor without payload.
  • child: String - The id of an entry or path starting from which to search for the ancestor.
  • n: Int32 - How many found ancestors to skip assuming that the search starts from the child entry itself. For example, if n = 0, and the child entry satisfies ancestorEntryTypes filter, than the child entry is returned itself. If, in the same case, n = 1, the nearest ancestor satisfying ancestorEntryTypes is returned.
  • ancestorEntryTypes: DirectoryEntryTypes - The bit-flags specifying entries of which types are to be returned.

Save: String

Creates or updates a directory entry.

If the parent is specified as id and an entry with the id doesn't exist, the EntryNotFound fault is thrown.

If the entry is being updated (the id of the entry is specified), the parent may be null. In this case the entry is saved under its current parent. If the entry is created, the parent must be specified.

If the entry is being updated (the id of the entry is specified) and the parent specified is not its current one, the entry is moved to the new parent.

If the parent entry already has a child with the same name as the entry being saved, the NameCollision fault is thrown.
  • parent: String - The path or id of the parent entry.
  • entry: DirectoryEntry - The entry to be saved.

Move

Moves an entry from the current parent to another.

If the entry to be moved doesn't exist, the EntryNotFound fault is thrown.

If the parent entry already has a child with the same name as the entry being saved, the NameCollision fault is thrown.
  • what: String - The path or id of the entry to move.
  • where: String - The new parent of the entry.

Remove

Removes an entry.

All descendants are removed with their ancestor.

If the entry to be removed doesn't exist, nothing happens.
  • what: String - The path or id of the entry to remove.

Exists: Boolean

Checks whether an entry newer than a specified timestamp exists.

Returns true if the specified entry exists and it is newer than the specified timestamp; otherwise, false.
  • what: String - The path or id of the entry to check.
  • timestamp: DateTime - The last update timestamp.

ExecuteScript: ICollection<ScriptParameter>

Executes a script with specified parameters.

Returns attributes of $out object.
  • script: String - The script to execute.
  • args: ICollection<ScriptParameter> - Arguments that will appear as attributes of $in object.

Last edited Jan 30, 2014 at 5:37 PM by dbratus, version 4

Comments

No comments yet.