Org.Lwes/DB/IEventTemplateDB.cs

   1 namespace Org.Lwes.DB
   2 {
   3         using System;
   4         using System.Collections.Generic;
   5         using System.IO;
   6         using System.Text;
   7
   8         using Org.Lwes.ESF;
   9
  10         /// <summary>
  11         /// Interface for event template databases.
  12         /// </summary>
  13         public interface IEventTemplateDB
  14         {
  15                 /// <summary>
  16                 /// An enumerable containing the names of defined events.
  17                 /// </summary>
  18                 IEnumerable<string> EventNames
  19                 {
  20                         get;
  21                 }
  22
  23                 /// <summary>
  24                 /// Indicates whether the template db has been initialized.
  25                 /// </summary>
  26                 bool IsInitialized
  27                 {
  28                         get;
  29                 }
  30
  31                 /// <summary>
  32                 /// Gets the named event template.
  33                 /// </summary>
  34                 /// <param name="evName">the event name</param>
  35                 /// <returns>the event template for the named event</returns>
  36                 /// <exception cref="ArgumentOutOfRangeException">thrown if the event is not defined in the DB</exception>
  37                 EventTemplate GetEventTemplate(string evName);
  38
  39                 /// <summary>
  40                 /// Initilizes the template db by reading ESF files at <paramref name="filePath"/>.
  41                 /// </summary>
  42                 /// <param name="filePath">a path containing ESF (*.esf) files</param>
  43                 /// <param name="includeSubdirectories">indicates whether subdirectories should be included</param>
  44                 /// <exception cref="InvalidOperationException">thrown if the template db has already been initalized</exception>
  45                 /// <exception cref="ArgumentNullException">thrown if <paramref name="filePath"/> is null</exception>
  46                 void InitializeFromFilePath(string filePath, bool includeSubdirectories);
  47
  48                 /// <summary>
  49                 /// Initializes the template db by reading ESF templates from the <paramref name="esfStream"/>.
  50                 /// </summary>
  51                 /// <param name="esfStream">a stream containing ESF template definitions</param>
  52                 /// <exception cref="InvalidOperationException">thrown if the template db has already been initalized</exception>
  53                 /// <exception cref="ArgumentNullException">thrown if <paramref name="esfStream"/> is null</exception>
  54                 void InitializeFromStream(Stream esfStream);
  55
  56                 /// <summary>
  57                 /// Checks to see if a named event template exists.
  58                 /// </summary>
  59                 /// <param name="eventName">the event name</param>
  60                 /// <returns><em>true</em> if the template with the <paramref name="eventName"/> exists;
  61                 /// otherwise <em>false</em>.</returns>
  62                 bool TemplateExists(string eventName);
  63
  64                 /// <summary>
  65                 /// Tries to create the named event.
  66                 /// </summary>
  67                 /// <param name="evName">event name</param>
  68                 /// <param name="ev">reference to a variable that contains the event upon success</param>
  69                 /// <param name="performValidation">whether the event should perform validation</param>
  70                 /// <param name="enc">the encoding used for the event</param>
  71                 /// <returns><em>true</em> if the named event is created; otherwise <em>false</em></returns>
  72                 bool TryCreateEvent(string evName, out Event ev, bool performValidation, SupportedEncoding enc);
  73
  74                 /// <summary>
  75                 /// Tries to get the named event template.
  76                 /// </summary>
  77                 /// <param name="evName">the event's name</param>
  78                 /// <param name="template">reference to a variable that will contain the template upon success</param>
  79                 /// <returns><em>true</em> if the named event is retreived; otherwise <em>false</em></returns>
  80                 bool TryGetEventTemplate(string evName, out EventTemplate template);
  81         }
  82 }