Fault Handling

The Control API uses standard SOAP fault handling to inform the client application of errors. The type of fault returned depends on the error that occurred. For example, an “ObjectDoesNotExist” fault is returned when trying to set a property for a Virtual Server that doesn't exist. Information contained inside the fault helps to determine more information about the error.

In addition to the specific faults specified for the functions, applications should be written to handle generic failures for which a specific fault does not exist.

Fault handling differs depending on the API being used. Refer to your API documentation for details on how best to handle faults.

The following examples show code snippets of how to handle faults with various standard libraries.

Fault Handling with SOAP::Lite

As SOAP::Lite doesn't read the WSDL files, the fault handling code needs to process the fault structures manually:

# This is the url of the Traffic Manager Admin Server
my $admin_server = 'https://<user>:<pass>@adminserver:9090';

my $conn = SOAP::Lite
-> ns('http://soap.zeus.com/zxtm/1.0/VirtualServer/')
-> proxy("$admin_server/soap")
-> on_fault( \&handle_fault );

sub handle_fault
{
my( $soap, $res ) = @_;

if( ! $res ) {
die "A transport error occured\n";
}

if( ! ref $res ) {
die $res;
}

# $res is a SOAP fault – extract the information in it
if( $res->faultdetail ) {
my $detail = $res->faultdetail;
my @elems = keys %$detail;
my $fault = $elems[0];

my $msg = "SOAP Fault: $fault\n";

# Extract out the components of the fault
foreach my $key( qw( errmsg object key value ) ) {
if( defined $detail->{$fault}->{$key} ) {
$msg .= " $key: " . $detail->{$fault}->{$key} ."\n";
}
}
die $msg;
} else {
die "SOAP Fault: " . $res->faultcode . ": " .
$res->faultstring . "\n";
}
}

# Could throw 'ObjectDoesNotExist'
$conn->setEnabled( [ "my-virtual-server" ], [ 1 ] );

Fault Handling using C Sharp

Like Perl, the fault detail structure needs to be inspected manually:

try {
p.setEnabled( new string[] { "my-virtual-server" },
new bool[] { true } );
} catch( SoapException fault ) {
string msg = "";
// Look at the fault detail XML tree
if( fault.Detail != null && fault.Detail.FirstChild != null ) {
XmlNode detail = fault.Detail.FirstChild;

// The SOAP fault is the name of the first child of the
// fault detail
msg += "SOAP Fault: " + detail.LocalName + "\n";

// And the other members of the fault are children
XmlNodeList children = detail.ChildNodes;
for( int i = 0 ; i < children.Count ; i++ ) {
msg += " " + children[i].Name + ": " +
children[i].InnerText + "\n";
}
} else {
// Otherwise this is a generic fault - just print the fault
msg = fault.ToString();
}
Console.Write( msg );
}

Fault Handling using Java

Fault handling is built into the Java AXIS libraries; the SOAP faults are translated into standard Java exceptions which make it very easy to handle faults:

VirtualServerLocator vsl = new VirtualServerLocator();
vsl.setVirtualServerPortEndpointAddress(
"https://<user>:<pass>@adminserver:9090/soap" );
VirtualServerPort vsp = vsl.getVirtualServerPort();

try {
vsp.setEnabled( new String[] { "my-virtual-server" },
new boolean[] { true } );

System.out.println( "Virtual Server enabled successfully" );
} catch( ObjectDoesNotExist e ) {
System.err.println(
"Virtual Server '" + e.getObject() + "' does not exist" );
} catch( RemoteException e ) {
System.err.println( "Generic exception: " + e );
}