Java API break

Question

I have the following API:

public interface MyApi {

   /**
    * Performs some stuff.
    * @throws MyException if condition C1
    */
   public void method() throws MyException;
}

I am now performing the following modification in my API implementation

public class MyApiImpl {

   public void method() throws MyException {
     if (C1) {
       throw new MyException("c1 message");
     }
     ...
   }
}

is replaced by :

public class MyApiImpl {

   public void method() throws MyException {
     if (C1) {
        throw new MyException("c1 message");
     } else if (c2) {
        throw new MyException("c2 message");
     }
     ...
   }
}

Do you consider this as an API breakage ?

Client's code will still compile but method contract defined by the API javadoc is no more respected since MyExcepiton is thrown by a "new" condition.

If only my API jar file is updated, clients application will still work but depending on the way clients catch the exception the application behavior can change a lot.

What's your point of view on that ?

Answer 1

Yes, you're breaking the contract of the interface by throwing an exception when C1 doesn't occur.

As a rule of thumb, the vaguer the interface contract, the easier it is not to break :) If the interface isn't defined in terms of an explicit C1, but in more general terms, that gives a lot more flexibility.