iControl 101 - #05 - Exceptions

When designing the iControl API, we had two choices with regards to API design.  The first option was to build our methods to return status codes as return values and outbound data as "out" parameters.  The other option was to make use of exception handling as a way to return non-success results allowing the use of the return value for outbound data.  This article will discuss why we went with the later and how you can build exception handling in your client application to handle the cases where your method calls fail.

Camp 1: return codes

As I mentioned above, there are two camps for API design.  The first are the ones that return status codes as return values and external error methods to return error details for a given error code.  For you developers out there who still remember your "C" programming days, this may look familiar:

struct stat sb;
char [] dirname = "c:\somefile.txt";
if ( 0 != stat(dirname, &sb) )
{
  printf("Problem with file '%s'; error: %s\n", dirname, strerror(errno));
}

You'll notice that the "stat" method to determine the file status returns an integer that is zero for success.  When it's non, zero a global variable is set (errno) indicating the error number, and the "strerror" method can then be called with that error number to determine the user readable error string.

There is a problem with this approach, as illustrated by the "Semipredicate problem", in which users of the method need to write extra code to distinguish normal return values from erroneous ones.

Camp 2: Exceptions

The other option for status returns is to make use of exception handling.  Exception handling makes use of the fact that when error conditions occur, the method call will not return via it's standard return logic but rather the information on the exception will be stored and the call stack is unwound until a handler for that exception is found.  This code sample in C# is an example of making use of exceptions to track errors:

try
{
  Microsoft.Win32.RegistryKey cu = Microsoft.Win32.Registry.CurrentUser;
  Microsoft.Win32.RegistryKey subKey = cu.OpenSubKey("some_bogus_path");
}
catch(Exception ex)
{
  Console.WriteLine("Exception: " + ex.Message.ToString());
}

iControl works with Exceptions

Luckily for us, the SOAP specification takes into account the exception model by adding an alternate to the SOAP Response.  A SOAPFault can be used to return error information for those cases where the method calls cannot be completed due to invalid arguments or other system configuration issues.

A SOAPFault for an invalid parameter to Networking::VLAN::get_vlan_id() looks like this:

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap-env:body>
<soap-env:fault>
<faultcode xsi:type="xsd:string">SOAP-ENV:Server</faultcode>
<faultstring xsi:type="xsd:string">Exception caught in Networking::VLAN::get_vlan_id()
Exception: Common::OperationFailed
        primary_error_code   : 16908342 (0x01020036)
        secondary_error_code : 0
        error_string         : 01020036:3: The requested VLAN (foo) was not found.</faultstring>
</soap-env:fault>
</soap-env:body>
</SOAP-ENV:Envelope>

The faultcode element indicates that the fault occurred on the server (ie, it wasn't a client connectivity issue) and the faultstring contains the details.  You may ask why we include all our fault data in the return string and not in the new SOAPFault elements defined in SOAP v1.2?  Well, when we first released our iControl interfaces, SOAP v1.0 was just coming out and they were not defined yet.  At this point we cannot change our fault format for risk of breaking backward compatibility in existing iControl applications.

An added benefit of using exceptions is that it makes client code much cleaner as opposed to using "out" type parameters.  Wouldn't you much your code look like this:

String [] pool_list = m_interfaces.LocalLBPool.get_list()

As opposed to this:

String [] pool_list = null;
int rc = m_interfaces.LocalLBPool.get_list(pool_list);

Types of Exceptions

If you look in the Common module in the SDK, you'll find a list of the exceptions supported in the iControl methods.  The most common of them is "OperationFailed" but in some cases you'll see AccessDenied, InvalidArgument, InvalidUser, NoSuchInterface,  NotImplemented, and OutOfMemory crop up.  The SDK documentation for each method lists the Exceptions that can be raised by each method if you need to narrow down what each method will give you.

Processing Faults

In almost all cases, it is sufficient to just know that an exception occurred.  The use of the method will likely give you the reason for a possible fault.  If you are trying to create a pool and it fails, odds are you passed in an existing pool name as an input parameter.  But for those situations where you need to get detailed info on why an exception happened how do you go about it?

Given that the Exceptions we return are all encoded as text in the faultstring field, it would be handy to have some tools to help you decipher that data.  Good thing you are reading this tech tip!  Here is a sample C# class to parse and identify iControl exceptions.  This could easily be ported to another language of your choice.

using System;
using System.Collections.Generic;
using System.Text;

namespace iControlProgram
{
  public class ExceptionInfo
  {
    #region Private Member Variables
    private Exception m_ex = null;
    private Type m_exceptionType = null;
    private String m_message = null;
    private String m_location = null;
    private String m_exception = null;
    private long m_primaryErrorCode = -1;
    private String m_primaryErrorCodeHex = null;
    private long m_secondaryErrorCode = -1;
    private String m_errorString = null;
    private bool m_IsiControlException = false;
    #endregion

    #region Public Member Accessors
    public System.Type ExceptionType
    {
      get { return m_exceptionType; }
      set { m_exceptionType = value; }
    }
    public String Message
    {
      get { return m_message; }
      set { m_message = value; }
    }
    public String Location
    {
      get { return m_location; }
      set { m_location = value; }
    }
    public String Exception
    {
      get { return m_exception; }
      set { m_exception = value; }
    }
    public long PrimaryErrorCode
    {
      get { return m_primaryErrorCode; }
      set { m_primaryErrorCode = value; }
    }
    public String PrimaryErrorCodeHex
    {
      get { return m_primaryErrorCodeHex; }
      set { m_primaryErrorCodeHex = value; }
    }
    public long SecondaryErrorCode
    {
      get { return m_secondaryErrorCode; }
      set { m_secondaryErrorCode = value; }
    }
    public String ErrorString
    {
      get { return m_errorString; }
      set { m_errorString = value; }
    }
    public bool IsiControlException
    {
      get { return m_IsiControlException; }
      set { m_IsiControlException = value; }
    }
    #endregion

    #region Constructors
    public ExceptionInfo()
    {
    }
    public ExceptionInfo(Exception ex)
    {
      parse(ex);
    }
    #endregion

    #region Public Methods
    public void parse(Exception ex)
    {
      m_ex = ex;
      ExceptionType = ex.GetType();
      Message = ex.Message.ToString();

      System.IO.StringReader sr = new System.IO.StringReader(Message);
      String line = null;
      try
      {
        while (null != (line = sr.ReadLine().Trim()))
        {
          if (line.StartsWith("Exception caught in"))
          {
            Location = line.Replace("Exception caught in ", "");
          }
          else if (line.StartsWith("Exception:"))
          {
            Exception = line.Replace("Exception: ", "");
          }
          else if (line.StartsWith("primary_error_code"))
          {
            line = line.Replace("primary_error_code   : ", "");
            String[] sSplit = line.Split(new char[] { ' ' });
            PrimaryErrorCode = Convert.ToInt32(sSplit[0]);
            PrimaryErrorCodeHex = sSplit[1];
          }
          else if (line.StartsWith("secondary_error_code"))
          {
            SecondaryErrorCode = Convert.ToInt32(line.Replace("secondary_error_code : ", ""));
          }
          else if (line.StartsWith("error_string"))
          {
            ErrorString = line.Replace("error_string         : ", "");
          }
        }
        IsiControlException = (null != Location) && (null != Exception);
      }
      catch (Exception)
      {
      }
    }
    #endregion
  }
}

And here's a usage of the above ExceptionInfo class in a snippet of code that is making use of the iControl Assembly for .NET.

...
try
{
  m_interfaces.NetworkingVLAN.get_vlan_id(new string[] { "foobar" });
}
catch (Exception ex)
{
  ExceptionInfo exi = new ExceptionInfo(ex);

  if (exi.IsiControlException)
  {
    Console.WriteLine("Exception: " + exi.Exception);
    Console.WriteLine("Location : " + exi.Location);
    Console.WriteLine("Primary Error : " + exi.PrimaryErrorCode + 
      "(" + exi.PrimaryErrorCodeHex + ")");
    Console.WriteLine("Seconary Error : " + exi.SecondaryErrorCode);
    Console.WriteLine("Description    : " + exi.ErrorString);
  }
}

Conclusion

The flexibility in our Exception implementation in iControl, along with some utilities to help process that information, you should help you well on your way to building a rock solid iControl application.