English:

The Free and Open Productivity Suite
New: Apache OpenOffice 4.1.1 released!
 

OpenOffice.org UCB Commands - Error Handling Concept & Specification


General Error Handling Concept

Every UCB Content supports a set of commands. A UCB client calls css::ucb::XCommandProcessor::execute(...) if it wants the content to execute a command. Errors occurring while executing a command are managed using exceptions.

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

There is a number of predefined exceptions for the well-known UCB Commands. Every new command introduced by a UCB Content implementation can also introduce new exceptions. If these exceptions are interactive, there is the problem, that any existing Interaction Handlers most possibly won't be able to handle them. Thus reusing existing interactive exceptions should be the way of choice whenever possible.

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

The following exceptions can be thrown by all UCB Commands:
 
Exception Description
css::ucb::UnsupportedCommandException Thrown if the requested command is not supported by a content.
css::lang::IllegalArgumentException Thrown if the data type of the given command's argument does not match the command's definition.
css::ucb::InteractiveAugmentedIOException Used to indicate IO errors (exception contains an css::ucb::IOErrorCode)
css::ucb:InteractiveNetworkResolveNameException
css::ucb:InteractiveNetworkConnectException
css::ucb:InteractiveNetworkReadException
css::ucb:InteractiveNetworkWriteException
css::ucb:InteractiveNetworkGeneralException
css::ucb:InteractiveNetworkOffLineException
css::ucb::AuthenticationRequest Used to collect missing authentication information. An implementation of css::ucb::XInteractionSupplyAuthentication (that will be filled by the Interaction Handler with the missing data) should be supplied with the continuations.

Exceptions, that are never passed to an Interaction Handler:
 

Exception Description
css::ucb::CommandFailedException Thrown if the execution of the command failed (but only after communication with an Interaction Handler). This exception contains the "original" exception that was passed to the Interaction Handler.
css::ucb::CommandAbortedException Thrown if the execution of the command was ended by calling css::ucb::XCommandProcessor::abort().
css::ucb::DuplicateCommandIdentifierException Thrown if two threads passed the same (non-zero) command identifier to css::ucb::XCommandProcessor::execute().

getCommandInfo

No special exceptions defined.

getPropertySetInfo

No special exceptions defined.

getPropertyValues

No special exceptions defined. Note that most error handling (except command name and parameter checking ) is done using the css::sdbc::XRow implementation returned by this command.

setPropertyValues

Note that setPropertyValues does not throw an exception in the case that one or more of the requested property values cannot be set! The implementation should set as much property values as possible. This command returns a sequence< any > which has exactly the same number of elements like the number of properties to set. Every sequence element contains the status for a property. The first sequence elements corresponds to the first element in the sequence of css::beans::PropertyValues passed as command argument and so on. The exceptions will never be passed to an Interaction Handler by the implementation of the setPropertyValues command.

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.
If the value to set is equal to the current value, no exception must be added to the returned sequence

open

Exception Description
css::ucb::UnsupportedOpenModeException Used to indicate that the requested css::ucb::OpenMode is not supported.
css::ucb::UnsupportedDataSinkException Used to indicate that the type of data sink supplied is not supported.

delete

No special exceptions defined.

insert

Exception Description
css::ucb::MissingPropertiesException Used if one or more properties were not set that are needed to make the content persistent (like the name for a newly created file). The exception transports a list of property names.
css::ucb::MissingInputStreamException Used if no css::io::XInputStream was given with the command argument, but is required.
css::ucb::UnsupportedNameClashException Used if the parameter ReplaceExisting of the command's argument was set to false and the implementation is unable to determine whether there are existing data. The member NameClash of the exception must be set to NameClash::ERROR.
Must also be thrown in case the requested nameclash is just not yet implemented (a missing feature, so to speak).
css::ucb::NameClashException Used if the parameter ReplaceExisting of the command's argument was set to false and there exists a resource with a clashing name in the target folder of the operation.

transfer

Exception Description
css::ucb::InteractiveBadTransferURLException Used if the Source URL given with the command's argument is not supported by the command's implementation. For example, an FTP-UCP needs not be able to handle other URLs then FTP-URLs.
css::ucb::UnsupportedNameClashException Used if the nameclash directive specified in parameter NameClash of command's argument is not supported. For example, if the NameClash was set to NameClash::ERROR, to NameClash::RENAME or to NameClash::ASK, the implementation must be able determine whether there are existing data. 
This exception must also used if NameClash::RENAME was specified and the implementation is unable to create a valid new name after a suitable number of tries.
It must also be thrown in case the requested nameclash is just not yet implemented (a missing feature, so to speak).
css::ucb::NameClashException Used if the parameter NameClash of the command's argument was set to NameClash::ERROR and there exists a resource with a clashing name in the target folder of the operation.
css::ucb::NameClashResolveRequest If the parameter NameClash of the command's argument was set to NameClashh::ASK this interaction request can be used to obtain a new name. Implementations of css::ucb::XInteractionSupplyName and css::ucb::XInteractionReplaceExistingData (that will be filled by the Interaction Handler with the missing data) should be supplied with the continuations.

globalTransfer

Exception Description
css::ucb::UnsupportedNameClashException Used if the nameclash directive specified in parameter NameClash of command's argument is not supported. For example, if the NameClash was set to NameClash::ERROR, to NameClash::RENAME or to NameClash::ASK, the implementation must be able determine whether there are existing data. 
This exception must also used if NameClash::RENAME was specified and the implementation is unable to create a valid new name after a suitable number of tries.
css::ucb::NameClashException Used if the parameter NameClash of the command's argument was set to NameClash::ERROR and there exists a resource with a clashing name in the target folder of the operation.
css::ucb::NameClashResolveRequest If the parameter NameClash of the command's argument was set to NameClashh::ASK this interaction request can be used to obtain a new name. Implementations of css::ucb::XInteractionSupplyName and css::ucb::XInteractionReplaceExistingData (that will be filled by the Interaction Handler with the missing data) should be supplied with the continuations.

search

Not yet specified. Will be done later. (No implementations yet.)

update

Not yet specified. Will be done later. (No implementations yet.)

synchronize

Not yet specified. Will be done later. (No implementations yet.)

close

Not yet specified. Will be done later. (No implementations yet.)

undelete

Not yet specified. Will be done later. (No implementations yet.)


Author: Kai Sommerfeld ($Date: 2007/05/26 10:33:56 $)
Copyright 2001 OpenOffice.org Foundation. All Rights Reserved.


Logo ApacheCon Europe 2014

Apache Feather

Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.