Sunday, August 27, 2006

The ReturnStatus Class

This class is one of several classes that I use in the revised document management interface.  I am including them as separate entries so that you can have multiple web pages up at the same time.  The 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.

The ReturnStatus class is used to return a status.  If there are other values that should be included in the return status, you could subclass this class or you could modify this class to hold some generic (Object) values.  Of the two approaches, I prefer subclassing.

 

using System;

namespace Interfaces
{
/// <summary>
/// The ReturnStatus status class holds the status generated
/// by various operations. It is designed to make
/// the generation and manipulation of return status values
/// easy and painless.
/// </summary>
public class ReturnStatus
{

#region Variables

private string[] _Errors;

#endregion

#region Constructors

/// <summary>
/// Instantiates the class with zero or more error messages.
/// This is the prime constructor; all of the other
/// constructors come here to do the actual work.
/// </summary>
/// <param name="theMessages">An array of error messages.
/// The array can be zero length.
/// All supplied messages must be non-null and non-empty.
/// </param>
public ReturnStatus(string[] theMessages)
{
_Errors
= new string[theMessages.Length];
for(int MsgNdx = 0; MsgNdx < theMessages.Length;
MsgNdx
++)
{
CheckMessage(theMessages[MsgNdx]);
_Errors[MsgNdx
++] = theMessages[MsgNdx];
}
}
/// <summary>
/// Instantiates the class without any error messages.
/// </summary>
public ReturnStatus()
:
this(new string[0])
{
}
/// <summary>
/// Instantiates the class from a single error message.
/// </summary>
/// <param name="theMessage">
/// A single error message for the status.</param>
public ReturnStatus(string theMessage)
:
this(new string[1] {theMessage})
{
}

/// <summary>
/// Instantiates the class from a previous return result
/// plus an error message.
/// </summary>
/// <param name="thePreviousReturnStatus">
/// A previously created return status.</param>
/// <param name="theMessage">
/// An error message for the status.</param>
public ReturnStatus(ReturnStatus thePreviousReturnStatus,
string theMessage)
:
this(CombineMessages(ExtractMessages(thePreviousReturnStatus),
new string[1] {theMessage}))
{
}

/// <summary>
/// Instantiates the class from a previous return result
/// plus an array of error messages.
/// </summary>
/// <param name="thePreviousReturnStatus">
/// A previously created return status.</param>
/// <param name="theMessages">
/// An array of error messages for the status.</param>
public ReturnStatus(ReturnStatus thePreviousReturnStatus,
string[] theMessages)
:
this(CombineMessages(ExtractMessages(thePreviousReturnStatus),
theMessages))
{
}

/// <summary>
/// Instantiates the class from two previous return results.
/// </summary>
/// <param name="thePreviousReturnStatus">
/// A previously created return status.</param>
/// <param name="theNewReturnStatus">
/// Another previously created return status.</param>
public ReturnStatus(ReturnStatus thePreviousReturnStatus,
ReturnStatus theNewReturnStatus)
:
this(CombineMessages(ExtractMessages(thePreviousReturnStatus),
ExtractMessages(theNewReturnStatus)))
{
}

#endregion

#region Methods

/// <summary>
/// Return the count of the error messages within this object.
/// </summary>
/// <returns>An integer count of error messages.</returns>
public int GetErrorCount()
{
return _Errors.Length;
}
/// <summary>
/// Return the specified error message.
/// </summary>
/// <param name="MsgNdx">
/// An index to the error messages.</param>
/// <returns>If the index is in range, the error message;
/// if the index is out of range, an empty string.</returns>
/// <remarks>We could throw an ArgumentOutOfRange exception
/// here but I want to get back an empty string
/// if there are no errors, which technically is
/// an out of range condition. Having set
/// a foot on the "slippery slope" it does not seem to do
/// much damage to return empty strings in all other
/// out of range situations. </remarks>
public string GetIndexedError(int MsgNdx)
{
if(MsgNdx < 0 || MsgNdx >= _Errors.Length)
{
return "";
}
return _Errors[MsgNdx];
}
/// <summary>
/// Return the first error. This is a convienence
/// method to handle the most likely situation.
/// </summary>
/// <returns>The first error message.</returns>
public string GetError()
{
return GetIndexedError(0);
}
/// <summary>
/// Returns an indicator of whether there are errors
/// in the return result. This is a convienence method
/// to handle a common inquiry.
/// </summary>
public bool IsOK
{
get { return _Errors.Length > 0; }
}

#endregion

#region Support Methods

/// <summary>
/// Check that an error message is real and substantive.
/// </summary>
/// <param name="theMessage">
/// The string for the error message.</param>
/// <exception cref="ArgumentNullException">
/// When the message parameter is null.</exception>
/// <exception cref="ArgumentException">
/// When the message parameter is an empty string.</exception>
private static void CheckMessage(string theMessage)
{
if(theMessage == null)
{
throw new ArgumentNullException("Message",
"An error message must be supplied");
}
if(theMessage.Trim().Length == 0)
{
throw new ArgumentException("Message",
"An error message may not be empty (zero-length)");
}
return;
}
/// <summary>
/// Returns an array which holds the combined error messages
/// from the return status and an array of error messages.
/// </summary>
/// <param name="thePreviousReturnStatus">
/// A previously created return status.</param>
/// <param name="theMessages">
/// An array of error messages</param>
/// <returns>An array (possibly zero length)
/// of error messages.</returns>
private static string[] CombineMessages
(
string[] theOldMessages, string[] theNewMessages)
{
int oldCount = theOldMessages.Length;
int newCount = theNewMessages.Length;
string [] myErrors = new string[oldCount + newCount];
int MsgNdx;
for(MsgNdx = 0; MsgNdx < oldCount; MsgNdx++)
{
myErrors[MsgNdx]
= theOldMessages[MsgNdx];
}
for(MsgNdx = 0; MsgNdx < newCount; MsgNdx++)
{
myErrors[MsgNdx
+ oldCount] = theNewMessages[MsgNdx];
}
return myErrors;
}
/// <summary>
/// Build an array of error messages
/// from the specified return status.
/// </summary>
/// <param name="theStatus">
/// A previously created return status.</param>
/// <returns>An array (possibly zero length)
/// of error messages.</returns>
private static string[] ExtractMessages(ReturnStatus theStatus)
{
int count = theStatus.GetErrorCount();
string [] myErrors = new string[count];
for(int MsgNdx = 0; MsgNdx < count; MsgNdx++)
{
myErrors[MsgNdx]
= theStatus.GetIndexedError(MsgNdx);
}
return myErrors;
}

#endregion

}
}

0 Comments:

Post a Comment

Links to this post:

Create a Link

<< Home