Sunday, August 27, 2006

The Revised Document Management Interface

This is the revised document management interface.  I am including this as a separate entry so that you can have multiple web pages up at the same time.  This interface uses three other class: ReturnStatus, DocumentIndex, and TOCElement.  My commentary on this revised interface will be posted shortly.  By the way, I am posting this entry using the beta version of Live Writer using the Live Writer plug-in for code formatting written by Steve Dunn.  Works quite nicely.

namespace Interfaces
{

/// <summary>
/// This is the delegate that can be used to process
/// an individual TOC entry.
/// </summary>
/// <param name="tocElement">An entry holding data from
/// the table of contents.</param>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that holds the success/failure indicator
/// and an error message for this invocation of the delegate;
/// if the last operation succeeded,
/// the error message is an empty string.
/// In general, the logic of the delegate should return errors
/// in the return status rather than throwing exceptions.
/// </returns>
public delegate ReturnStatus ProcessTOCElement(TOCElement toc);

/// <summary>
/// This is the delegate that can be used to process paragraphs
/// with the portion of the document that is referened by an
/// instance of the <see cref="DocumentIndex"/> class.
/// </summary>
/// <param name="documentIndex">An instance of a
/// <see cref="DocumentIndex"/> class that "points" to the
/// the portion of the document that holds the contents of
/// the <see cref="paragraph"/> parameter.
/// </param>
/// <param name="paragraph">An string holding the text of the
/// paragraph in Unicode format without any formatting
/// indicators.</param>
/// <param name="paragraphNumber">An integer that holds
/// the relative position of the paragraph within the portion
/// of the document referenced by the <see cref="documentIndex"/>
/// parameter.
/// </param>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that holds the success/failure indicator
/// and an error message for this invocation of the delegate;
/// if the last operation succeeded,
/// the error message is an empty string. In general,
/// the logic of the delegate should return values in the
/// return status rather than throwing exceptions.</returns>
public delegate ReturnStatus ProcessParagraph
(DocumentIndex documentIndex,
int paragraphNumber,
string paragraph);

/// <summary>
/// Defines the actions that the document interface/viewer
/// can take against a specified portion of the document.
/// </summary>
public enum DocumentActions
{
/// <summary>
/// Display the portion of the document
/// </summary>
Display,
/// <summary>
/// Print the portion of the document
/// </summary>
Print,
/// <summary>
/// Transmit a copy of the portion of the document
/// </summary>
Transmit,
/// <summary>
/// Store a copy of the portion of the document in a file
/// or other persistent store
/// </summary>
Store
}
/// <summary>
/// This is a revision of the document management interface.
/// </summary>
public interface IManageDocumentsFixed
{
/// <summary>
/// Prepare the document for use.
/// </summary>
/// <exception cref="InvalidOperationException">
/// When the client software opens an already open document.
/// </exception>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that holds the success/failure indicator
/// and an error message for the open operation;
/// if the open operation succeeded, the error message
/// is an empty string.</returns>
/// <remarks>The location of the document is established in
/// the constructor of the class that
/// implements this interface. It is
/// </remarks>
ReturnStatus Open();

/// <summary>
/// Retrieve the title of the document.
/// </summary>
/// <returns>The overall title of the document.</returns>
string GetTitle();

/// <summary>
/// Release the document. The document must be re-opened
/// again before any further use.
/// </summary>
/// <exception cref="InvalidOperationException">
/// When the client software closes a document that is not
/// open.
/// </exception>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that holds the success/failure indicator
/// and an error message for the close operation;
/// if the close operation succeeded,
/// the error message is an empty string.</returns>
ReturnStatus Close();

/// <summary>
/// Returns the reference to the "root" element
/// of the document.
/// </summary>
/// <returns>An instance of the
/// <see cref="DocumentIndex"/> class that
/// refers to the "root" element of the document.</returns>
DocumentIndex GetRootIndex();

/// <summary>
/// Run through each of the entries in the table of contents
/// in a depth-first fashion by invoking the specified
/// <see cref="ProcessTOCElement"/> delegate for each entry.
/// Each TOCElement contains the document index element
/// that can be used to position the document to a
/// specific location within the document; the title
/// of the TOC entry; and the hierarchical level of the
/// TOCElement within the table of contents.
/// </summary>
/// <param name="localRoot">An instance of a
/// <see cref="DocumentIndex"/> class that "points" to the
/// the starting point for the run through. The client
/// should use the return value from the
/// <see cref="GetRootIndex"/> method to start at the root
/// of the document.
/// </param>
/// <param name="process">A reference to a delegate that
/// conforms to the <see cref="ProcessTOCElement"/> definition.
/// </param>
/// <param name="maximumLevel">The maximum number of levels
/// to descend. The value must be non-negative. A value of
/// zero will invoke the delegate just once for the root;
/// A value of one will invoke the delegate once for the
/// root followed by once for each direct child of the root.
/// And so on.
/// </param>
/// <exception cref="ArgumentNullException">
/// When the localRoot parameter is null.</exception>
/// <exception cref="InvalidOperationException">
/// When the localRoot parameter "points at"
/// a portion of the document that does not exist.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
/// When the maximum level parameter is less than zero.
/// </exception>
/// <exception cref="ArgumentNullException">
/// When the process parameter is null.</exception>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that hold the overall success/failure indicator
/// and any error messages accumulated during the process;
/// if the operation succeeded,
/// the error message is an empty string.
/// Note that the return value is
/// the summation of all of the return values from
/// each of the invocations of the delegate.</returns>
/// <remarks>This method must be safe for recursion,
/// that is, the client program may call this method
/// to process each of the chapters. The invocation of the
/// delegate can do some process that includes a call
/// to <see cref="ProcessTOC"/> method, this time to process
/// the sections within the chapter. The logic of this
/// method must also not be affected by any use of the
/// <see cref="ProcessParagraph"/> method.</remarks>
ReturnStatus ProcessTOC(DocumentIndex localRoot,
ProcessTOCElement process,
int maximumLevel);

/// <summary>
/// Run through each of the paragraphs in the specified
/// section of the document by invoking the specified
/// <see cref="ProcessParagraph"/> delegate
/// for each paragraph.
/// </summary>
/// <param name="localRoot">An instance of a
/// <see cref="DocumentIndex"/> class that "points" to the
/// the portion of the document that holds the paragraphs
/// to be the run through. The client should use the return
/// value from the <see cref="GetRootIndex"/> method
/// to process the root of the document.
/// </param>
/// <param name="process">A reference to a delegate that
/// conforms to the <see cref="ProcessParagraph"/> definition.
/// </param>
/// <exception cref="ArgumentNullException">
/// When the localRoot parameter is null.</exception>
/// <exception cref="InvalidOperationException">
/// When the localRoot parameter "points at"
/// a portion of the document that does not exist.
/// </exception>
/// <exception cref="ArgumentNullException">
/// When the process parameter is null.</exception>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that hold the overall success/failure indicator
/// and any error messages accumulated during the process;
/// if the operation succeeded,
/// the error message is an empty string.
/// Note that the return value is the summation of all
/// of the return values from each of the
/// invocations of the delegate.</returns>
/// <remarks>This method is not intended to provide
/// significant display capabilities. That work should be
/// done through the viewer for the document controlled by
/// this interface. This method is intened to provide brief
/// "teaser" exerpts that can assist the user in selecting
/// a given paragraph.</remarks>
ReturnStatus ProcessSectionParagraphs(DocumentIndex localRoot,
ProcessParagraph process);

/// <summary>
/// Perform the specified action on the document at the
/// specified location within the document.
/// </summary>
/// <param name="action">A value taken from the
/// <see cref="DocumentActions"/> enumeration that
/// defines the action that the document viewer controlled
/// by this interface should take.</param>
/// <param name="documentIndex">A string value returned
/// by the <see cref="GetCurrentTOCID"/> method
/// or one of the values
/// returned by the <see cref="GetIndices"/> method.</param>
/// <exception cref="ArgOutOfRangeException">
/// When the action parameter has a value that is not found
/// in the <see cref="DocumentActions"/> enumeration.
/// </exception>
/// <exception cref="ArgumentNullException">
/// When the localRoot parameter is null.</exception>
/// <exception cref="InvalidOperationException">
/// When the localRoot parameter "points at"
/// a portion of the document that does not exist.
/// </exception>
/// <returns>An instance of the <see cref="ReturnStatus"/>
/// class that hold the overall success/failure indicator
/// and any error messages accumulated during the process;
/// if the operation succeeded,
/// the error message is an empty string.
/// Note that the return value is the summation of all
/// of the return values from each of the
/// invocations of the delegate.</returns>
ReturnStatus ActAtIndexLocation
(DocumentActions action, DocumentIndex documentIndex);

/// <summary>
/// Retrieve a set of zero or more document indices
/// that represent the locations within the document
/// where the lookup parameter value appears.
/// </summary>
/// <param name="lookup">The "index term" to search for.</param>
/// <returns>An array of document indices. If the search term
/// does not match any part of the document, the returned
/// array is zero length.</returns>
DocumentIndex[] GetIndices(string lookup);

}
}

0 Comments:

Post a Comment

Links to this post:

Create a Link

<< Home