UCB Commands - Error Handling Concept & Specification

General Error Handling Concept

Any exceptions can be used by a UCP implementation to interact with a UCB client. For example, if a file should be written to disk (using UCB's insert command) and another file with the same name already exists, an exception could be used to query the user whether he wants to overwrite the existing file. If the user confirms, the file will be overwritten, if he rejects, the insert command will be aborted.

Exceptions generally should be handed over to an css::task::XInteractionHandler implementation, which generally was obtained from a command's environment (css::ucb::XCommandEnvironment. If no Interaction handler is available or if the Interaction Handler did not handle the request, the exception must be thrown directly. This will always aborts the command. Using an Interaction Handler has the advantage, that additional data can be supplied to the command implementation without the need to abort and to retry the command (after supplying the missing data). The data supplied to the requesting code either may lead in continuing or aborting the command.

A css::task::XInteractionHandler handles css::task::XInteractionRequests. An Interaction Request contains an exception (the request) and a number of css::task::XInteractionContinuations, which define the responses that can be used to "answer" the request. There are some standard continuations defined, which are namely css::task::XInteractionAbort, css::task::XInteractionRetry, css::task::XInteractionApprove and css::task::XInteractionDisapprove. For example, for a GUI Interaction Handler these continuations could be assigned to buttons in a message box (Approve equals "Yes" button, Disapprove equals "No" button, ...). The Interaction Handler code does some work dependent on the kind of request and the possible continuations (like displaying a login dialog and supplying the data entered to the authentication request), selects one of the continuations provided and returns. The code that called the Interaction Handler now can act according to the kind of continuation that was previously selected. Not every Interaction Handler implementation must be able to handle all requests. If an Interaction Handler cannot handle a request, no continuation will be selected after the call to XInteractionHandler::handle( ... ). In this case the code that called the Interaction Handler must act as if no handler were available and throw the exception that was previously passed to the Interaction Handler.

For exceptions located in the module com::sun::star::ucb, the member Context (which is introduced by the base class of all UNO exceptions � css::uno::Exception) should be filled with the command processor (css::ucb::XCommandProcessor implementation) that executes the command.

The following pseudo code illustrates how to proceed with an error:
 

// Create the exception to propagate...
xxxxException aEx( ... );

xxxxContinuation aCont;

// Obtain Interaction Handler
uno::Reference< task::XInteractionHandler > xIH = ...

bool bSelection = false;
if ( xIH.is() )
{
    // IH available. Create Interaction Request.
    xxxxRequest aReq = ...( aEx, ... );

    // Pass over the request to the IH.
    xIH.handle( aReq );

    // Get selected continuation
    aCont = aReq.getSelection();

    // Was IH able to handle the request?
    if ( aCont.is() )
        bSelection = true;
}

// Act according to bSelection and aCont
bool bSuccess = ...;

if ( !bSuccess )
{
    if ( !bSelection )
    {
        // No IH or IH did not handle exception.
        throw aEx;
    }

    // IH handled the selection.
    throw ucb::CommandFailedException( aEx );
}

// Continue...

Exception Specifications for the Well-Known UCB Commands

The implementation of a command should use the predefined exception for the appropriate error condition whenever possible. But It can use any other exceptions, for example, if there is no matching predefined exception for a concrete error condition.
 

All commands

Exceptions, that are never passed to an Interaction Handler:
 

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

An any containing:

• No value indicates, that the property value was set successfully.
• css::beans::UnknownPropertyException indicates, that the property is not known to the content implementation.
• css::beans::IllegalTypeException indicates, that the data type of the property value is not acceptable.
• css::lang::IllegalAccessException indicates, that the property is constant (css::beans::PropertyAttribute::READONLY is set).
• css::lang::IllegalArgumentException indicates, that the property value is not acceptable. For instance, setting an empty title may be illegal.
• Any other execption derived from css::uno::Exception indicates, that the value was not set successfully. For example, this can be a css::ucb::InteractiveAugmentedIOException transporting the error code css::ucb::IOErrorCode::ACCESS_DENIED.

open

delete

insert

transfer

globalTransfer

search

update

synchronize

close

undelete