vSphere Client SDK API Documentation : version 5.5.0.1300321

com.vmware.vise.data.query
Class DataException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by com.vmware.vise.core.model.MutableMessageException
              extended by com.vmware.vise.data.query.DataException
All Implemented Interfaces:
Serializable

public class DataException
extends MutableMessageException

Fault thrown by data-service adapters and providers to represent failure to fetch data. It is used in the error field of a ResultSet as shown in the examples below.

Example of a PropertyProviderAdapter's getProperties method returning a DataException in the result.error field so that the error can be handled in the UI layer.

public ResultSet getProperties(PropertyRequestSpec propertyRequest) { // code to retrieve some properties of some objects ... ResultSet result = new ResultSet(); try { ... } catch (Exception e) { result.error = DataException.newInstance(e, propertyRequest.objects, propertyRequest.properties[0].propertyNames); } return result; }

Example of a ResponseHandler displaying the error message in the Flex UI. The text comes from the exception used to create the DataException on the java side.

[ResponseHandler(name= "{com.vmware.data.query.events.PropertyRequest.RESPONSE_ID}")] public function onDataRetrieved(request:PropertyRequest, result:Object, error:Error):void { if (error != null) { // Only display the error message here. You could also extract the objects and // properties information if error is a DataException. Alert.show(error.message); return; } ... }

A DataProviderAdapter can also use DataException to signal the failure to return anything when asked to discover new objects (i.e. by opposition to returning properties on existing objects). This is done by omitting objects and properties in DataException. The error will be handled by the UI framework in the list view, the message will be displayed as a temporary notification to show that the empty list is not a normal state.

Example of DataProviderAdapter signaling a configuration problem preventing it from returning any object when the query expects a list of objects.

... // Case of an error with the back-end data server ResultSet rs = new ResultSet(); rs.items = null; rs.totalMatchedObjectCount = 0; Exception ex = new Exception( "Chassis back-end server not responding! Check your configuration."); rs.error = DataException.newInstance(ex); return rs; ...

See Also:
ResultSet, Serialized Form

Field Summary
 Object[] objects
          Objects for which data could not be fetched.
 String[] properties
          Properties that were not fetched.
 Throwable rootCause
          Error describing why the data could not be retrieved.
 
Constructor Summary
DataException()
           
 
Method Summary
static DataException newInstance(Throwable e)
          Create a new DataException to report a failure to retrieve any object.
static DataException newInstance(Throwable e, Object[] objects, String[] properties)
          Create a new DataException for the associated objects and properties.
static DataException newInstance(Throwable e, Object object, String property)
          Create a new DataException for one object and one property.
 
Methods inherited from class com.vmware.vise.core.model.MutableMessageException
getMessage, setMessage
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

objects

@optional
public Object[] objects
Objects for which data could not be fetched. This can be omitted to signal the failure to return any object in the case of a DataProviderAdapter.


properties

@optional
public String[] properties
Properties that were not fetched.


rootCause

public Throwable rootCause
Error describing why the data could not be retrieved. The DataException's message will be set to that rootCause's message.

Note: when the DataException is serialized back in the UI as an ActionScript object the rootCause will be null if there is no equivalent Flex error object but the DataException message is preserved to describe the rootCause.

Constructor Detail

DataException

public DataException()
Method Detail

newInstance

public static DataException newInstance(Throwable e)
Create a new DataException to report a failure to retrieve any object.

Parameters:
e - the error to report.
Returns:
a new DataException containing this error.

newInstance

public static DataException newInstance(Throwable e,
                                        Object object,
                                        String property)
Create a new DataException for one object and one property.

Parameters:
e - the error to report.
object - the object for which the data error occurred.
property - the property which could not be fetched.
Returns:
a new DataException for the specified object and property.

newInstance

public static DataException newInstance(Throwable e,
                                        Object[] objects,
                                        String[] properties)
Create a new DataException for the associated objects and properties.

Parameters:
e - the error to report.
objects - the object for which the data error occurred.
properties - the properties which could not be fetched.
Returns:
a new DataException for the specified objects and properties.

vSphere Client SDK API Documentation : version 5.5.0.1300321

Copyright @ 2012 VMware, Inc. All rights reserved.