Interfaces... Everywhere... about spongeapi

[Mumfrey]

I think you're confusing syntax with sematics. Please read about the difference before making yourself look more foolish.

[superckl]

I see you are not open to change. I don't think insulting me was necessary to express that.

I recommend you read the section on interfaces from the book "Effective Java" by Joshua Bloch, since this is where a large portion of my opinion on this matter is based.

I would like to hear more opinions on this matter.

[jacklin213]

@superckl good lord maybe you should read, how to code an API off any google search

[Mumfrey]

This is an API, it's standard practice to define an API in terms of interfaces, this decouples the implementation from the API itself. Yes it's perfectly allowable to declare an object as implementing "PlayerEvent, BlockEvent, ChatEvent, Game, PluginManager,..." as you say, however since that has no corresponding semantic significance, it's largely irrelevant. I could similarly make an object implement Logger, Marker and Message from log4j's API but that wouldn't really carry any significance if the object in question was never used in the functional contract defined by the implementation. Make sense? In this instance, abstraction is all we're interested in.

My comment wasn't intended as an insult, I was just trying to draw attention to the fact that you're missing the point somewhat. I apologise for using the word "foolish", but is "silly" any better?

I applaud the fact that you've read "Effective Java", it's an excellent resource. However your comment has no relevance to this API because you're confusing different concepts and saying things like

it violates standard Java coding conventions

which it doesn't - abstraction is commonly achieved with interfaces - and

I realize this is very tedious to change, but I believe it is necessary.

just makes it seem like you're fundamentally misunderstanding how this kind of API works. Sorry but there just isn't a way to turn this which makes it a valid comment in the context of the API.

[superckl]

Ah, thank you. I see where you are basing your argument, and where mine is faulty. I apologize for taking it as an insult, I try to not be foolish in my life ;)

I guess at this point it comes down, for me at least, to a difference in philosophies. If I wrote an API that allowed a class to be two somewhat contradictory things, I wouldn't be sastified with it. If I remember correctly from Bukkit and Forge, classes similar to the ones I mentioned are not interfaces.

Although I regret to say I still don't agree with your point, I'm happy to leave this argument here if you so desire. Perhaps I'm still not understanding something.

[Mumfrey]

The point is that normally you'd be right, but in this case it's not userland classes which implement the interfaces (just like I mentioned, with the log4j example above) but API classes. This kind of decoupling means that you compile your code against an interface, the implementation of the API then defines how those interfaces behave.

This is important because it allows the implementation to shift and evolve over time without breaking binary compatibility with code compiled against the user-facing (users in this case being plugin authors) API.

The API interfaces thus only have actual meaning in terms of the functional contract defined by the API, those two things together then make the system as a whole operational. The point is that userland code shouldn't care about the actual structure of the program behind the scenes, it should only care about the advertised types (the interfaces) of objects returned by the various API methods it has access to.

For example, say you subscribe to an event which is a PlayerEvent (an interface, extending the Event interface) and receive callbacks from the engine which take a PlayerEventArgs (also an interface), the implementation of those interfaces can change over time, and even be implemented by completely different objects or entirely different systems (maybe Glowstone or another platform entirely). You don't care, as long as you only work with the API, the implementation can change as much as it likes provided the original functional contract remains intact.

In Bukkit, this was the case, for example Player, Entity, World etc. were all interfaces. The implementation was provided by CraftBukkit which actually put the meat on the bones in terms of providing the implementation. In Forge this is not the case, and that's why the abstraction layer is needed in order to form the API, Sponge will likewise be the meat on the bones of the SpongeAPI project.

Hope that makes more sense now.

[superckl]

Thank you. I completely see your position now.

I can still come up with a few counter examples where a user may care about the structure (i.e. custom events), but I think that's the case with every API.

Thanks for taking the time to explain with such depth.

[Mumfrey]

Again, everything not explicitly inferrable from the interface hierarchy or method signatures is defined by the functional contract. Since the functional contract won't be fully determined until the API is substantially complete it's difficult to say at this point, but in general an accompanying Functional Specification document is what defines the various behaviours. Of course for a project like this that may take the form of a Wiki or other crowd-sourced documentation. Javadoc also plays an important part in that the non-explicit functional behaviour of an interface or method can be described in detail in the Javadoc, which can then be used by consumers and implementors alike to ensure consistent behaviour and adherence to the expected contract.

In real-world systems usually a formal requirements document comes first, but when making something like this API to such a tight schedule, a more al-fresco approach is pretty much the accepted norm. This doesn't mean things aren't planned out, just that they're free to evolve as they're written. Agile and all that jazz... {insert modern programming paradigm buzzword here}.