Why does wrapping an exception still request try-catch even when adding a throws?

Question

I'm making use of SikuliX's API within my own personal library. The idea is to reference my library alone in external projects which incorporates the parts of SikuliX that I require.

Now, SikuliX throwns a FindFailed exception, which I required. I tried to do:

public class FindFailed extends org.sikuli.script.FindFailed {
    FindFailed(String msg) { super(msg); }
}

Which seemed to make sense. However, when attempting to use a throws statement in one of the methods:

import org.mylibrary.exceptions.FindFailed;

public static boolean clickFinishButton() throws FindFailed {
    pattern = PatternManager.loadPattern("my-image.png");

    screen.wait(pattern, 10);
    region = screen.exists(pattern);
    region.click(pattern);

    return true;
}

I still get an Unhandled exception type FindFailed warning. Changing it back to the original org.sikuli.script.FindFailed will of course work, however making use of try-catch in an external project will require me to re-add the relevant SikuliX jar file.

What I would like to do, is simply wrap the FindFailed exception that is being thrown by SikuliX and use it internally and externally with my library.

The primary goal of all of this is to wrap around another API with my own additional methods and such, so that when I reference this library, the later projects don't have to reference SikuliX's jar as well.

- - - - My Library - - - <—————— External Project
|                      |
|        SikuliX       |
- - - - - - - - - - - - 

As is it right now, I require to do the following:

- - - - My Library - - - <—————— External Project
|                      |                |
|        SikuliX       |                |
- - - - - - - - - - - -                 v
                                  SikuliX (Again)

---

So far I've changed things as follows which seems to work.

public class FindFailed extends Exception {
    public FindFailed(Throwable cause) { super(cause); }
}

I now don't extend any third party Exceptions. And instead I proceed by doing the following:

public static boolean clickNewScan() throws FindFailed {
    pattern = PatternManager.loadPattern("my-image.png");   
    region = screen.exists(pattern);
    try {
        screen.wait(pattern, 60);
        region.click(pattern);
    } catch (org.sikuli.script.FindFailed e) {
        throw new FindFailed(e);
    }
    return true;
}

Answer 1

You do this by wrapping all the calls in SikuliX their own interfaces. I don't know SikuliX, so I'll make a toy example.

package third.party.library;

public class Foo {
    public void doSomething() throws ThirdPartyException {
        // Their code
    }
}

Okay, so you want to wrap this functionality without depending on their library.

package juxhin;

public interface FooBehavior {
    public void doSomething() throws MyException;
}

Then, when you need their behavior, you can use your own implementation:

package juxhin; // YOU write this class

public class ThirdPartyFooBehavior implements FooBehavior {
    private final Foo foo;

    public FooThirdPartyFooBehavior(Foo theirObject) {
        this.foo = theirObject;
    }

    @Override
    public void doSomething() throws MyException {
        try {
            foo.doSomething();
        } catch (ThirdPartyException e) {
            throw new MyException(e);
        }
    }
}

Once you've wrapped their library behind all your own interfaces, then your classes only will only depend on your own interfaces, which means you won't have to worry about their exceptions. Their library will be completely removable as long as you reimplement these interfaces with a non-dependent implementation.

Note that MyException should not extend third.party.library.ThirdPartyException, because that won't help your problem; it should use the Exception(Throwable cause) constructor and remove it from the org.sikuli.script class hierarchy.

---

The bottom line, though, is that you still have to include the code included in SikuliX somehow. This is why tools like Maven exist, so that adding the reference to jars is very easy. For example, if your jar is dependent on SikuliX, then when you tell your new project to use your jar, it will automatically include the SikuliX reference without you having to do anything. You end up with dependency trees like this, which automatically do all this work for you:

I personally use Maven but there are other options like Ivy and Gradle that do the same thing - I'm not trying to advocate for any particular tool here, just advocating for using any dependency tool.

Answer 2

Extending from classes you don't own is never a good idea and should be avoided. Besides, it would make whoever handles your exception still have the jar that contains org.sikuli.script.FindFailed.

A better approach would be wrapping the exception like this:

public class MyFindFailedException extends Exception {
    MyFindFailedException(String message, Exception cause) {
        super(message, cause);
    }
}

And then use it like this:

public static boolean clickFinishButton() throws MyFindFailedException {
  try {
    pattern = PatternManager.loadPattern("my-image.png");

    screen.wait(pattern, 10);
    region = screen.exists(pattern);
    region.click(pattern);

    return true;
  } catch (FindFailed e) {
    throw new MyFindFailedException("something went wrong", e);
  }
}