How to deprecate an inner interface

Question

I need to deprecate APIs in a Java SDK to make them more general. But I can't figure out how to do it for the following case:

public class AdoptDog {
    public interface OnDogAdoption {
        public void onDogAdoption(String dogName);
    }
    public void adoptDog(final String dogName, OnDogAdoption callbackObj) {
        // Perform asynchronous tasks...
            // Then call the callback:
            callbackObj.onDogAdoption(dogName);
    }
}

Users of the SDK make calls as follows:

AdoptDog adoptDog = new AdoptDog();
adoptDog.adoptDog("Snowball", new OnDogAdoption {
    @Override
    public void onDogAdoption(String dogName) {
        System.out.println("Welcome " + dogName);
    }
};

I want to generalize from Dog to Pet and deprecate APIs that mention Dog. For backward compatibility, the code snippet above where Snowball gets adopted should not have to change when I deprecate the APIs.

How I tried to deprecate the Dog API:

// Introduce Pet API

public class AdoptPet {
    public interface OnPetAdoption {
        public void onPetAdoption(String petName);
    }
    public void adoptPet(final String petName, OnPetAdoption callbackObj) {
        // Perform asynchronous tasks...
            // Then call the callback:
            if (callbackObj instanceof OnDogAdoption) {
                ((OnDogAdoption) callbackObj).onDogAdoption(petName);
            }
            else {
                callbackObj.onPetAdoption(petName);
            }
    }
}

// Dog API now extends Pet API for backward compatibility

@Deprecated
public class AdoptDog extends AdoptPet {
    @Deprecated
    public interface OnDogAdoption extends AdoptPet.OnPetAdoption {
        @Deprecated
        public void onDogAdoption(String dogName);
    }
    @Deprecated
    public void adoptDog(final String dogName, OnDogAdoption callbackObj) {
        super.adoptPet(dogName, callbackObj);
    }
}

The problem is it's not fully backward compatible. Users of the SDK have to implement AdoptPet.OnPetAdoption.onPetAdoption() or else they get a compiler error:

AdoptDog adoptDog = new AdoptDog();
adoptDog.adoptDog("Snowball", new OnDogAdoption {
    @Override
    public void onDogAdoption(String dogName) {
        System.out.println("Welcome " + dogName);
    }

    // PROBLEM: How avoid customers having to implement this dummy method? 
    @Override
    public void onPetAdoption(String petName) {
        assert("This code should not be reached");
    }
};

Is there some other way to deprecate AdoptDog (specifically OnDogAdoption) and maintain full backward compatibility?

Answer 1

Java 8 allows you to specify default method implementations. You could use that to help you, for example:

@Deprecated
public interface OnDogAdoption extends AdoptPet.OnPetAdoption {
    @Deprecated
    void onDogAdoption(String dogName);

    default void onPetAdoption(String petName) {
        onDogAdoption(petName);
    }
}

By having a default implementation, the client code will not be required to implement it (but may if they wish) and so there should be no compilation error.

---

Note: All interface methods are public by default - in fact they can only be public - there's no need to specify that.

Answer 2

You don't extend the OnPetAdoption. A OnDogAdoption is not a OnPetAdoption. A OnPetAdoption could also handle a cat adoption. A OnDogAdoption can not.

I would suggest that you wrap the OnDogAdoption in a OnDogAdoptionDispatcher, and call the new method with that dispatcher, e.g.:

@Deprecated
public class AdoptDog extends AdoptPet {
    @Deprecated
    public interface OnDogAdoption {
        @Deprecated
        public void onDogAdoption(String dogName);
    }

    private static class DogAdoptionDispatcher implements AdoptPet.OnPetAdoption {
            final OnDogAdoption target;
            public DogAdoptionDispatcher(OnDogAdoption target) {
                this.target = target;
            }
            @Override
            public void onPetAdoption(String petName) {
                target.onDogAdoption(petName);
            }
    }

    @Deprecated
    public void adoptDog(final String dogName, OnDogAdoption callbackObj) {
        super.adoptPet(dogName, new DogAdoptionDispatcher(callbackObj));
    }
}

This way, you still have backward compatibility and a clean new interface.

If you are using Java 8 or higher, you don't need a separate class for this, you could just do

public void adoptDog(final String dogName, OnDogAdoption callbackObj) {
    super.adoptPet(dogName, callbackObj::onDogAdoption);
}