Exception Management

Radovan pointed out a very important problem with the origin of the Exception.

The full call chain may have two I/O channels and if both are network connection then very likely they throw the same exception and IDM can not distinguish between them.

[IDM] --I/O--> [ConnectorServer] --I/O--> [Resource]

We have full control over the network connection between the IDM and ConnectorServer and we can catch any Throwable and as I propose the Framework can call the appropriate method on a callback handler instead of wrap them into ConnectorIOException and label them as "Come from ConnectorServer IO" Exception. We can expect any kind of exception from the second I/O between the Connector and the Resource. IDM needs to know if the connection to ConnectorServer fails or the connection from connector to Resource fails. In first case IDM can try another ConnectorServer in second case it's a Exception blocking the operation. The problem may be Retryable so it's one case where we can use a RetryableException and wrap the original exception.

The other important fact is where in the call stack the exceptions comes from. The API operation call goes through these steps and any of them may throw exception and we can not identify the source.

• validate
• init
• checkAlive
• operation
• dispose

If validate throws IllegalArgumentException then the configuration is wrong and it's a permanent exception, if the create operation throws IllegalArgumentException then the request contains something wrong. Both may be handled differently in IDM.

Validation Failed -> Permanent Exception because the configuration is invalid.
Init or CheckAlive Failed -> Retryable/Permanent Exception because the remote server may be down at the moment. It's up to IDM to decide. The connector implementor can use the RetryableException here too.
Operation Failed -> Permanent Exception because the bad request/attributes was supplied or Permission is denied or Operation is not supported. IDM may handle different exceptions in different way.
Dispose Failed -> Diagnostic report to IDM because the allocated resources has to be discharged at some point.

The pool exceptions may be interesting to IDM and there is one where we may change
ConnectorException - If the pool has no more available Connector after the {@link ObjectPoolConfiguration#maxWait} time.
to
RetryableException - If the pool has no more available Connector after the {@link ObjectPoolConfiguration#maxWait} time.

One solution to avoid some problem is when we can force IDM to call the validate and be sure when we call the operation (for example create) the validate won't fail. Still there is init, checkAlive and after a success operation the dispose and all these may be over any I/O connection.

• Connect to remote server [OK/Fail] --> validate[OK/Fail]
• Connect to remote server [OK/Fail] --> validate[OK] --> init[OK/Fail] --> checkAlive[OK/Fail] --> operation[OK/Fail] --> dispose [OK/Fail]

Q: What if Validate throws NullPointerException/IllegalArgumentException or the operation throws it? I think this is why it's important to separate them.

Solutions:

1. A: Wrap it into an exception and mark it as PRE_OPERATION, OPERATION, [POST_OPERATION] exception and throw it up to IDM.
2. B: Change the API to use a CallBackHandler and framework can call the appropriate method with the exception.

I prefer the 2. B option because that is closer the to the solution proposed for the query and sync implementation. Now the Framework implementation has a synchronous API then asynchronous implementation and then the API is a mix of sync/async. When we want to support the Asynchronous provisioning in the future, this interface change makes it simpler for the IDM integration.

import org.identityconnectors.framework.common.objects.ConnectorObject;
/**
 *
 */
public interface ResultHandler<V> {
    /**
     *
     */
    public enum Origin {
        /**
         * The Origin of the exception is the connection to the Connector Server.
         */
        CONNECTION,
        /**
         * The Origin of Exception is before the Framework calls the Operation.
         * validate or init or checkAlive
         */
        PRE_OPERATION,
        /**
         * The Origin of Exception is inside the Operation.
         */
        OPERATION,
        /**
         * The Origin of Exception is after the Framework called the Operation.
         * dispose
         */
        POST_OPERATION,
    }
    /**
     * Invoked when the asynchronous request has failed.
     *
     * @param origin
     *            The origin of the exception.
     * @param error
     *            The resource exception indicating why the asynchronous request
     *            has failed.
     */
    void handleError(Origin origin, Throwable error);
    
    /**
     * Invoked when the asynchronous request has completed successfully.
     *
     * @param result
     *            The query result indicating that no more resources are to be
     *            returned and, if applicable, including information which
     *            should be used for subsequent paged results query requests.
     */
    void handleResult(V result);
}

There is another issue with the Exception serialisation. I noticed nobody knows well how the exceptions are handled if they are serialised and received from a remote server. For the better understanding the problem and the solution I wrote this sample project and I documented so you can play with it and see What exception is received in IDM if a remote connector throws a NumberFormatException and what happens with the original cause and the stack trace. I think if you see it as a Java code it tells you more then I can explain the problem.

From the log you can see if a remote java connector throws AssertionError then IDM receives RuntimeException.

Call [facade ]:
Throw [Error ]
Catch [remote]: class="AssertionError" message=Missing attribute cause=null
Catch [IDM ]: class="RuntimeException" message=Missing attribute cause=null

From the log you can see if a remote .Net connector throws Microsoft.Build.BuildEngine.InvalidToolsetDefinitionException then IDM receives RuntimeException.

Call [facade]:
Throw [UnknownException]
Catch [dotnet]: class="Microsoft".Build.BuildEngine.InvalidToolsetDefinitionException message=Example Message cause=null
Catch [IDM ]: class="RuntimeException" message=Microsoft.Build.BuildEngine.InvalidToolsetDefinitionException cause=null

We need to bring together the .Net System.Exception and the Java Error/Exception/RuntimeException management and the the way they are serialised in binary/xml format without loosing important information.

Because ConnId targets Java 6 and OpenICF try to stay Java 5 compatible I listed here the Java 5 RuntimeExceptions and marked the Java6. I check but I didn't see any new required Java 6 exceptions so I suggest to stay with Java 5.

I listed and I categorised the exceptions in JVM.

FU - Fully Used: These exceptions should be part of the contract. They are named Known exceptions in the sample project.
NU - Not Used in the contract. If this exception is thrown then it was downcast to plain new RuntimeException(e.getMessage())

Smart Message: The exception has more information then just e.getMessage() so concatenating them would contains all information. This would requires additional logic per exception. Q: Does it worth it?
Complex: The Class does not have Default or String constructor.
Null message: The Exception does not have Message (Exception )
Subclasses: The Exception has many other subclasses

AnnotationTypeMismatchException, NU Smart Message
ArithmeticException, NU
ArrayStoreException, NU
BufferOverflowException, --> System.IO.InternalBufferOverflowException NU
BufferUnderflowException, NU Null message
CannotRedoException, NU Null message
CannotUndoException, NU Null message
ClassCastException, --> System.InvalidCastException NU
CMMException, NU
ConcurrentModificationException, NU
Java 6 DataBindingException
DOMException, NU Smart Message
EmptyStackException, NU Null message
EnumConstantNotPresentException, NU Smart Message
EventException, NU Smart Message
IllegalArgumentException, --> System.ArgumentException FU Subclasses
IllegalMonitorStateException, NU
IllegalPathStateException, NU
IllegalStateException, --> System.InvalidOperationException -- FU/ NU? Subclasses
ImagingOpException, NU
IncompleteAnnotationException, NU Smart Message
IndexOutOfBoundsException, NU
JMRuntimeException, NU
LSException, NU Smart Message
MalformedParameterizedTypeException, NU Null message
Java 6 MirroredTypeException,
Java 6 MirroredTypesException
MissingResourceException, NU Smart Message
NegativeArraySizeException, NU
NoSuchElementException, NU
Java 6 NoSuchMechanismException,
NullPointerException, --> System.NullReferenceException FU (don't confuse with System.ArgumentNullException extends System.ArgumentException :( )
ProfileDataException, NU
ProviderException, NU
RasterFormatException, NU
RejectedExecutionException, NU
SecurityException --> System.Security.SecurityException
SystemException, Too complex, use the message only
Java 6 TypeConstraintException
TypeNotPresentException, NU, Complex
UndeclaredThrowableException, NU Complex
Java 6 UnknownAnnotationValueException,
Java 6 UnknownElementException,
Java 6 UnknownTypeException
UnmodifiableSetException, NU
UnsupportedOperationException, --> System.NotSupportedException FU
Java 6 WebServiceException

Exceptions

AclNotFoundException, NU Null message
ActivationException,NU
AlreadyBoundException,NU
ApplicationException, CORBA Too Complex
AWTException, NU
BackingStoreException,NU
BadAttributeValueExpException, NU Complex
BadBinaryOpValueExpException, NU Complex
BadLocationException, NU Complex
BadStringOperationException,NU
BrokenBarrierException,NU
CertificateException,NU
ClassNotFoundException, NU
CloneNotSupportedException,NU
DataFormatException,NU
DatatypeConfigurationException,NU
DestroyFailedException,NU
ExecutionException,NU
ExpandVetoException, Complex
FontFormatException,NU
GeneralSecurityException, FU Subclass
GSSException, Too Complex
IllegalAccessException,NU
IllegalClassFormatException,NU
InstantiationException,NU
InterruptedException,NU
IntrospectionException,EE
InvalidApplicationException, NU Complex
InvalidMidiDataException,NU
InvalidPreferencesFormatException,NU
InvalidTargetObjectTypeException,NU
InvocationTargetException,NU
IOException, NU SUBCLASSES
Java 6 JAXBException, NU Smart Message
JMException,NU
Java 6 KeySelectorException,NU
LastOwnerException, NU Null message
LineUnavailableException,NU
Java 6 MarshalException,NU
MidiUnavailableException,NU
MimeTypeParseException,NU
Java 6 MimeTypeParseException,NU
NamingException, NU Complex Subclasses
NoninvertibleTransformException,NU
NoSuchFieldException, NU
NoSuchMethodException,NU
NotBoundException,NU
NotOwnerException, NU Null Message
ParseException, NU Complex
ParserConfigurationException,NU
PrinterException,NU
PrintException,NU
PrivilegedActionException, NU Too Complex
PropertyVetoException, NU Complex
RefreshFailedException,NU
RemarshalException,NU
RuntimeException, FU Subclasses
SAXException, NU Subclasses
Java 6 ScriptException,NU
ServerNotActiveException,NU
Java 6 SOAPException,NU
SQLException, NU Subclasses
TimeoutException,NU
TooManyListenersException,NU
TransformerException, NU Smart Message
Java 6 TransformException,NU
UnmodifiableClassException,NU
UnsupportedAudioFileException,NU
UnsupportedCallbackException,NU
UnsupportedFlavorException, NU Complex
UnsupportedLookAndFeelException, NU
Java 6 URIReferenceException, NU Smart Message
URISyntaxException, NU Complex
UserException, NU Corba, Subclasses
XAException,NU
XMLParseException,NU
Java 6 XMLSignatureException,NU
Java 6 XMLStreamException, NU Smart Message
XPathException NU Subclasses

Proposed new Exceptions

SchemaViolationException

PreconditionFailedException

PreconditionRequiredException

RetryableException

PasswordNotFoundException

InvalidAccountException

AccountExpiredException

AccountLockedException

Proposed JavaDoc update

Generic rules

Framework API level:

Connector SPI level: