changing public api ?

[Brad Walker <bw...@musings.com>]

I'm in need of some help!

I'm working on cleaning up uses of deprecated API usages and when I do
this, there are impacts on the public API because an exception that was
previously being thrown is now no longer.

For example, in
*ide/image/src/org/netbeans/modules/image/ImageDataObject.java* there is
this method..

            /** Gets value of property. Overrides superclass method. */
            public Icon getValue() throws InvocationTargetException {
                try {
                    return new ImageIcon(obj.getPrimaryFile().getURL());
                } catch (FileStateInvalidException fsie) {
                    throw new InvocationTargetException(fsie);
                }
            }

If I do something simple like change the getURL() to toURL() to remove the
deprecation warning, the exception will no longer be thrown.

This means I have to change the Public API and remove the throws statement..

What is the process (files, docs, etc.) for changing a public API?

Thanks.

-brad w.

Re: changing public api ?

[Jan Lahoda <la...@gmail.com>]

Changing a public API is always tricky, and should be avoided if possible.
I believe the primary reason for adding FileObject toURL() instead of
changing the signature of getURL() was to keep source compatibility.

In this case, I am not sure what is the problem? Methods can have
exceptions in their throws clause that are not being thrown by the body,
that is not a compile-time error. I.e.:
class Test {
      public void hasThrowsButNotThrow() throws java.io.IOException {}
}

should compile just fine.

Moreover - ide/image/src/org/netbeans/modules/image/ImageDataObject.java is
not a public API, as far as I can tell. So removing the throws clause there
is not an API change. And the getValue method is a method of a private
nested class - there should be even less issues with removing the throws
clause there. Unless I am missing something.

Jan

On Thu, Aug 27, 2020 at 11:43 PM Brad Walker <bw...@musings.com> wrote:

> I'm in need of some help!
>
> I'm working on cleaning up uses of deprecated API usages and when I do
> this, there are impacts on the public API because an exception that was
> previously being thrown is now no longer.
>
> For example, in
> *ide/image/src/org/netbeans/modules/image/ImageDataObject.java* there is
> this method..
>
>             /** Gets value of property. Overrides superclass method. */
>             public Icon getValue() throws InvocationTargetException {
>                 try {
>                     return new ImageIcon(obj.getPrimaryFile().getURL());
>                 } catch (FileStateInvalidException fsie) {
>                     throw new InvocationTargetException(fsie);
>                 }
>             }
>
> If I do something simple like change the getURL() to toURL() to remove the
> deprecation warning, the exception will no longer be thrown.
>
> This means I have to change the Public API and remove the throws
> statement..
>
> What is the process (files, docs, etc.) for changing a public API?
>
> Thanks.
>
> -brad w.
>