Difference between setOnXXX() method and addEventHandler() JavaFx

Question

I'm trying to learn JavaFX event handling. I found that we can register event by two ways.

One is convenience method like setOnAction(EventHandler), setOnMouseClicked(EventHandler)

The second is by using addEventHandler(MouseEvent.MOUSE_CLICKED, EventHandler)

But I'm confused what is the difference between them? how decide which one will be suitable?

I have tested and registered two event handler using both methods and both are working fine.

Button btn = new Button("Click Me One!");
    btn.setOnMouseEntered(new EventHandler<MouseEvent>(){
        @Override
        public void handle(MouseEvent e){
            System.out.println("Mouse Entered on Click Me One");
        }
    });

    btn.setOnMouseExited(new EventHandler<MouseEvent>(){
        @Override
        public void handle(MouseEvent e){
            System.out.println("Mouse Exited from Click Me One");
        }
    });


    Button btn2 = new Button("Click Me Two!");
    btn2.addEventHandler(MouseEvent.MOUSE_ENTERED, new EventHandler<MouseEvent>(){
        @Override
        public void handle(MouseEvent e){
            System.out.println("Mouse Entered on Click Me Two");
        }
    });
    btn2.addEventHandler(MouseEvent.MOUSE_EXITED, new EventHandler<MouseEvent>(){
        @Override
        public void handle(MouseEvent e){
            System.out.println("Mouse Exited from Click Me Two");
        }
    });

Here is the output after checking.

Mouse Entered on Click Me One
Mouse Exited from Click Me One
Mouse Entered on Click Me Two
Mouse Exited from Click Me Two

I also checked by defining event handler.

Button btn2 = new Button("Click Me Two!");
        // Define an event handler
        EventHandler<InputEvent> handler = new EventHandler<InputEvent>() {
            public void handle(InputEvent event) {
                System.out.println("Handling event " + event.getEventType()); 

            }
        };
        btn2.addEventHandler(MouseEvent.MOUSE_ENTERED, handler);
        btn2.addEventHandler(MouseEvent.MOUSE_EXITED, handler);

        btn2.setOnMouseEntered(handler);
        btn2.setOnMouseExited(handler);

Output:

Handling event MOUSE_ENTERED
Handling event MOUSE_ENTERED
Handling event MOUSE_EXITED
Handling event MOUSE_EXITED

Answer 1

After testing myself I got the exact point what is the meaning of There can be only one handler of same type with convenience method. So I'm going to answer of my own question.

There are two main difference I found between setOnXXX() method and addEventHandler

1: The event that you register with addEventHandler() will execute first. Here is the Example.

Button btn = new Button("Hover Me!");

btn.setOnMouseEntered(new EventHandler<MouseEvent>() {
    public void handle(MouseEvent event) {
        System.out.println("Handling event with Convience Method"); 
    }
});
btn.addEventHandler(MouseEvent.MOUSE_ENTERED, new EventHandler<MouseEvent>() {
    public void handle(MouseEvent event) {
        System.out.println("Handling event with addEventHandler"); 
    }
});

Output:

Handling event with addEventHandler
Handling event with Convience Method

After reading James_D's comment I have added paragraph from original doc for the 1st difference.

A node can register more than one handler. The order in which each handler is called is based on the hierarchy of event types. Handlers for a specific event type are executed before handlers for generic event types. For example, a handler for the KeyEvent.KEY_TYPED event is called before the handler for the InputEvent.ANY event. The order in which two handlers at the same level are executed is not specified, with the exception that handlers that are registered by the convenience methods described in Working with Convenience Methods are executed last.

2: The second difference is that you can add Multiple handler with Same EventType ( as I used Mouse_Entered Event) using addEventHandler(); but in case of setOnXXX(); last registered event handler will execute. Here is the Example.

Button btn = new Button("Hover Me!");

btn.setOnMouseEntered(new EventHandler<MouseEvent>() {
    public void handle(MouseEvent event) {
        System.out.println("Handling event 1 with Convenience Method"); 
    }
});
btn.setOnMouseEntered(new EventHandler<MouseEvent>() {
    public void handle(MouseEvent event) {
        System.out.println("Handling event 2 with Convenience Method"); 
    }
});
btn.addEventHandler(MouseEvent.MOUSE_ENTERED, new EventHandler<MouseEvent>() {
    public void handle(MouseEvent event) {
        System.out.println("Handling event 1 with addEventHandler"); 
    }
});

btn.addEventHandler(MouseEvent.MOUSE_ENTERED, new EventHandler<MouseEvent>() {
    public void handle(MouseEvent event) {
        System.out.println("Handling event 2 with addEventHandler"); 
    }
});

Output:

Handling event 1 with addEventHandler
Handling event 2 with addEventHandler
Handling event 2 with Convenience Method

As you see I registered two event handler using both ways. But in convenience method's way the last event handler executed. To complete the answer let me copy the paragraph from jns's answer.

So if you need only one EventHandler it makes no difference which method you use. However, if you need to apply several EventHandlers for the same EventType you have to add them using addEventhandler