The user facing API designs

[surajkumar]

User Facing API Discussion

We should have this discussion out in the open so we can all come to a consensus on what the best approach should be for the user facing API.

There are 2 styles we could implement;

Traditional

The "traditional" method would like so:

public class MyEventListener implements ChannelCreateEventListener {
    @Override
    public void onChannelCreate(Channel channel) {
       // ...
    }
}
...
discord.addEventListener(new MyEventListener());

This is how a lot of the existing solutions do it and it's not particularly a bad one.
Pros:

• Many developers are accustomed to this approach, making it easier for them to understand and maintain code.
• Each event handler is explicitly implemented and registered, making it clear which events are being listened to.

Cons:

• Requires writing additional code for each event listener class, which can be tedious and increase code verbosity.
• As the number of events grows, managing individual listener classes might become cumbersome.

Annotations

@EventListener
public class ExampleListener {
    @ChannelCreate
    public void exampleChannelCreate(Channel channel) {
        System.out.printf("Channel created: %s", channel.name());
    }
}

This would then automatically get created by the library so the user does not need to explicity bind the handler.

Pros:

• Using annotations reduces boilerplate code, resulting in cleaner and more readable event handling code.
• Allows for more dynamic event handling as listeners are automatically discovered and registered by the library.
• Separates event handling logic from the registration process, promoting a more modular design.

Cons:

• Users need to understand the specific annotations and their parameters, which might require additional documentation or learning resources.
• Automatic registration might obscure which events are being handled, leading to potential confusion or difficulty in tracing event flow.
• IDEs or static analysis tools may not fully support or recognize annotated event handlers, potentially causing issues such as false positives for unused methods.

Any other ideas? What do you guys think between the traditional and annotations based methods? Should we explore other patterns for the end user?

Some other ideas I have is following an Aspect Oriented Programming approach.

[surajkumar]

Just for some context, JDA and Javacord follow the traditional pattern. The annotations way is influenced by the Spring framework and Discord4j does this type of syntax:

 gateway.on(MessageCreateEvent.class).subscribe(event -> {
      Message message = event.getMessage();
      if ("!ping".equals(message.getContent())) {
        MessageChannel channel = message.getChannel().block();
        channel.createMessage("Pong!").block();
      }
    });

[surajkumar]

Nobody has voted against the annotation based processing so this will be implemented.