A fault is like an exception in Java or another modern programming language. It’s a data structure that holds information about an exceptional situation. Most of the faults are raised by the server; you can normally determine the cause from their fault names.
Close to 300 fault types are defined in the vSphere API. Let’s look at the top level hierarchy shown as follows.
Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.
The supertype for all faults is MethodFault. It is extended by InvalidCollectorVersion, InvalidProperty, RuntimeFault, and VimFault. The first two faults are not further extended to any other fault types.
Each of the last two fault types has a pretty big subtype hierarchy underneath. RuntimeFault is the base for all runtime faults that a method can throw. Please don’t confuse RuntimeFault with RuntimeException in Java. RuntimeException does not require you to catch it explicitly. RuntimeFault does, even though it is intended to be like RuntimeException. Optionally, you can declare to throw it in the containing method signature.
When client-side stubs are generated from WSDL, the faults are mapped to language-specific exception types. In the AXIS-generated Java stubs, the MethodFault type becomes a subclass of java.rmi.RemoteException, while the hierarchy underneath remains the same. If you catch RemoteException in your code, you are going to catch all the possible faults. In general, you should not catch RemoteException or MethodFault unless you don’t want to handle the specific fault types. It’s a good practice, though, to catch RemoteException after you catch the more specific fault types, but not the other way around.
To understand exception handling, you should look at these basic fault types so that you can understand the scenarios in which the faults are thrown and handle them accordingly in your application.
- InvalidArgument The set of arguments passed to the function is not specified correctly.
- InvalidState The operation failed due to the current state of the system.
- InvalidName The name contains an invalid character or format.
- NoPermission An operation is denied because of a privilege not held on a managed object.
- NotSupported The method is not supported on the server. Not all methods are supported on all servers. An ESX server host supports less functionality than a VirtualCenter server. A feature might also be disabled due to missing licenses.
- TaskInProgress An operation tries to access an entity that already has another (long) operation in progress.
- Timedout A server abandons an operation that is taking longer than expected.
- OutOfBounds A parameter exceeds the acceptable range of values.
- NotFound A referenced component of a managed object cannot be found. The referenced component can be a data object type (such as a role or permission) or a primitive (such as a string).
- AlreadyExists An attempt is made to add an element to a collection, if the element’s key, name, or identifier already exists in that collection.
The concrete fault types sometimes have extra properties defined to show you the information specific to the fault. For example, TaskInProgress defines a property called task to hold the MOR to the task already in progress. With this information you can tell with which task your last invocation was in conflict.