Usage of @deprecated with parameter type change in method definition

Question

I am creating a API for DB access.

Already there is one application using our API.In this case if I want to change the type of parameter from interface to the implementing type.

For example,

API version 1.0:

getDomain1Data(SearchBy searchBy,List<String> someList);

Can i change this to the below ? I want to ensure that the API user does not search domain1 data with another domain's table column name.

getDomain1Data(Domain1SearchBy searchBy,List<String> someList);

If I do this should I add deprecated to the first method and then add the second method or I can just replace the first method with the second one.

Thanks.

Answer 1

If there is already a app which uses your interface method it would be unwise to delete previous method. I would rather add getDomain1Data(Domain1SearchBy searchBy,List<String> someList); and add @Deprecated annotation to the previous one.

Sample code:

@Deprecated
static interface SearchBy {
}
static class Domain1SearchBy implements SearchBy {
}

static interface Api10 {
    void some(SearchBy a);
}
static interface Api11 extends Api10 {
    void some(Domain1SearchBy b);
}

static class Api10Impl implements Api10 {
    @Deprecated
    public void some(SearchBy a) {
        System.out.println("some searchby");
    }
}
static class Api11Impl extends Api10Impl implements Api11 {
    public void some(Domain1SearchBy b) {
        System.out.println("some domain1");
    }
}

public static void main(String[] args) {

    //with api 1.0
    Api10 api10 = new Api10Impl();
    api10.some(new SearchBy() {});
    api10.some(new Domain1SearchBy());

    //with api 1.1
    Api11 api11 = new Api11Impl();
    api11.some(new SearchBy() {});
    api11.some(new Domain1SearchBy());

}

Result:

some searchby
some searchby
some searchby
some domain1

Answer 2

If you're changing methods that are in use, as they are in this case, then I think that the correct way would be to add the new method and add the @Deprecated tag to the old method with an explanation of why it has been deprecated, and which method should be used instead.

Answer 3

You can't just replace the first one with the second one because a client might call it with SearchBy object as acutual parameter. This would than result in a compile error.

Having both methods is also not possible, because they are ambigous. If called with Domain1SearchBy object both methods would be applicable so it can't be decided which one to use.

Your only two options are giving the new one another name or change the parameter count.