Can an IllegalStateException be used to capture all sub-exceptions?

Question

I wonder if using an IllegalStateException in this scenario is a good design choice for an API.

Scenario: I have a function which checks if an XML document is well formed with the following signature:

public boolean isXMLDocumentWellFormed(InputStream inXMLDocument)

This function uses the following snippet to load the XML document:

    boolean isXMLDocWellFormed = false;

    // Setup document builder
    DocumentBuilderFactory docBuilderFactory = DocumentBuilderFactory
            .newInstance();

    if (docBuilderFactory == null)
        throw new IllegalStateException(
                "The DocumentBuilderFactory cannot be instanciated");
    try {
        DocumentBuilder docBuilder = docBuilderFactory.newDocumentBuilder();

        // Parse document
        Document doc = docBuilder.parse(inXMLDocument);

        if (doc != null)
            isXMLDocWellFormed = true;

    } catch (ParserConfigurationException e) {
        // TODO Auto-generated catch block
        e.printStackTrace();
        throw new IllegalStateException(e);
    } catch (SAXException e) {
        // TODO Auto-generated catch block
        e.printStackTrace();
        throw new IllegalStateException(e);
    } catch (IOException e) {
        // TODO Auto-generated catch block
        e.printStackTrace();
        throw new IllegalStateException(e);
    }

    return isXMLDocWellFormed;

The API is designed to be very easy to use. However, I would like to provide to API users the possibility to know why an XML document cannot be checked (example: DocumentBuilderFactory cannot create a DocumentBuilder object) without overwhelming them with tons of checked exception that they will have to deal with.

My concerns regarding this design are:

a) Does using one single Exception type (i.e IllegalStateException) to return every possible caught exceptions to indicate a failure to perform the check a good idea ? I would say yes since users would except 2 things out of this function:

1. To know if the XML document is well formed or not.
2. To know in the event that the function cannot return the answer (due to an exception for instance) why the function failed to provide the answer.

b) If the answer to a) is no, then what would be the most appropriate exception name or solution and why ?

Regards,

Answer 1

My first recommendation to people is to not catch exceptions just to effectively re-throw. Catch when you can actually do something about them. So think about that. But in your example where you are catching checked exceptions and wrapping them in a runtime exception, I'd ask the question - how often will this occur? If the exceptions are likely to be common (or serious) then you want programmers to ensure that they deal with them, so checked is the way to go. However if they are not common (and not serious) then throwing a wrapping runtime may be acceptable. This is something that you need to think about because nothing annoys a developer more than unexpected exceptions.

Having said nothing by saying all that :-) if you are going to wrap I'd consider creating your own exception because you want to be clear that it is yours and not Java's. You could even create a hierarchy with a generalised exception extending runtime, and then more specific ones extending your genralised exception. Thus allowing API users the option to catch at different levels.