How to Write OGSA-DAI-compliant Exceptions

By extending OGSA-DAI's base exception classes you can write exceptions that exploit OGSA-DAI's internationalization functionality.

This page assumes that you are familiar with OGSA-DAI's support for internationalization and message bundles as described in the tutorial on How to Register New Message Bundles.

How to declare a new exception

First you should decide whether you wish your exception to be checked or unchecked and declare your exception to extend the appropriate OGSA-DAI class:

• For checked exceptions - those that must be declared in the throws clause of methods - your exception should extend uk.org.ogsadai.exceptions.DAIException
• For unchecked exceptions, your exception should extend uk.org.ogsadai.exceptions.DAIUncheckedException

For example:

package com.example;

import uk.org.ogsadai.exception.DAIException;

public class MyNewException extends DAIException 
{
    // Exception in progress - see below for more of the body.
}

How to associate an exception with an error ID and key

You should now define an error ID for your exception. The OGSA-DAI class uk.org.ogsadai.exception.ErrorID is a sub-class of the message ID class (uk.org.ogsadai.common.msgs.MessageID) introduced in the tutorial on message bundles and should be used when defining error messages.

In the same way that message IDs hold message keys which index into a message bundle, error IDs hold error keys which index into a message bundle.

The error key held within your error ID should be prefixed with a namespace specific to your organisation. As for message keys, we recommend that error keys have meaningful names as if no entry with this key is found in your message bundle then the key itself will be used as the message.

Our example class would now look like the following:

package com.example;

import uk.org.ogsadai.exception.DAIException;
import uk.org.ogsadai.exception.ErrorID;

public class MyNewException extends DAIException 
{
    // Declaration of error ID constant whose value is a
    // unique namespace-qualified error key.
    private static final ErrorID MY_NEW_ERROR =
        new ErrorID("com.example.MY_NEW_ERROR");

    // Exception in progress - see below for more of the body.
}

Similarly, you should add an entry for the error key associated with the error ID to your message bundle:

com.example.MY_NEW_ERROR=A bad value was encountered. The value was
{0} when I was expecting {1}.

How to write a constructor for your exception

You can now complete your exception by providing a constructor. This should pass the error ID to the super-class constructor and also any parameters required by the associated error key as specified in the message bundle.

Arguments required by the associated error key, as specified in a message bundle, should be provided a java.lang.Object array with the entries in the array in the same order as the placeholders in the message string associated with the error key. For example:

package com.example;

import uk.org.ogsadai.exception.DAIException;
import uk.org.ogsadai.exception.ErrorID;

public class MyNewException extends DAIException 
{
    // Declaration of error ID constant whose value is a
    // unique namespace qualified ID.
    private static final ErrorID MY_NEW_ERROR =
        new ErrorID("com.example.MY_NEW_ERROR");

    public MyNewException(String badValue, String expectedValue)
    {
        // Note how the order of values in the array matches that
        // expected by the message bundle entry for error key
        // com.example.MY_NEW_ERROR shown above.
        super(MY_NEW_ERROR, new Object[] {badValue, expectedValue});
    }
}

How to chain exceptions

To link exceptions into causal chains you can use the standard java.lang.Throwable initCause(Throwable) method. e.g.

package com.example;

import uk.org.ogsadai.exception.DAIException;
import uk.org.ogsadai.exception.ErrorID;

public class MyOtherNewException extends DAIException 
{
    private static final ErrorID MY_OTHER_NEW_ERROR =
        new ErrorID("com.example.MY_OTHER_NEW_ERROR");

    public MyOtherNewException(String badValue, String expectedValue,
                               Throwable cause)
    {
        super(MY_OTHER_NEW_ERROR, new Object[]{badValue, expectedValue});
        // Set up the causal chain.
        super.initCause(cause);
    }
}