What is an AssertionError? In which case should I throw it from my own code?

Question

In Item 2 of the "Effective Java, 2nd edition" book, there is this snippet of code, in which the author wants to forbid the empty initialization of an object.

class Example {     private Example() {         throw new AssertionError();     } } 

The type of exception thrown, is what confuses me here.

I don't understand if the AssertionError is thrown just because of an absence of more suited errors or because it should be this way.

As I understand, this error is thrown by the framework when an assert statement fails. Also, in the javadoc it's just written

[An AssertionError is] Thrown to indicate that an assertion has failed.

But I don't see any assertion (true-false statement) being violated here. Of course the "You shall not instantiate an item of this class" statement has been violated, but if this is the logic behind that, then we should all throw AssertionErrors everywhere, and that is obviously not what happens.

FWIW, I'd have just thrown a

new IllegalStateException("Must not instantiate an element of this class") 

Is there something wrong with that? In which case should I throw an AssertionError in my own code?

Sorry if it's just a subtle doubt but I use this pattern a lot in my code and I want to make sure I'm doing the right thing.

Answer 1

Of course the "You shall not instantiate an item of this class" statement has been violated, but if this is the logic behind that, then we should all throw AssertionErrors everywhere, and that is obviously not what happens.

The code isn't saying the user shouldn't call the zero-args constructor. The assertion is there to say that as far as the programmer is aware, he/she has made it impossible to call the zero-args constructor (in this case by making it private and not calling it from within Example's code). And so if a call occurs, that assertion has been violated, and so AssertionError is appropriate.

Answer 2

The meaning of an AssertionError is that something happened that the developer thought was impossible to happen.

So if an AssertionError is ever thrown, it is a clear sign of a programming error.