[WiP] Add a simple example for basic/common things done in extensions

[purbon]

I started working on this with the idea of providing simple enough examples of working with jruby-extensions. Including things like class and module definitions, working with static methods, passing parameters and creating internal objects, etc.

I'm opening this PR to get feedback if the direction is the one expected or should I take another direction to provide meaningful examples to help document this.

Welcoming all proposals and ideas,

• purbon

[purbon]

@monkstone not sure how I can help with the issue, I have to admit myself I'm fairly new to the world of jruby-extensions, however more than willing to collaborate here adding examples and documentation.

Next thing I would really like to add here is a super simple example integrating with a jar, lib. Any idea which one would be simple and basic enough?

/cheers

[guyboertje]

@purbon - this looks like a good start, but should there be more comments in the Java?

e.g.

@JRubyClass(name = "Bar")
public class Bar extends RubyObject {

should we ask for clarification from @headius, @enebo or others about the annotation
i.e. is it necessary if the ruby class and the java name are the same vs...

@JRubyClass(name = "Bar")
public class RubyBar extends RubyObject {

etc.

[guyboertje]

I would like to see some discussion that reveals insights about the different ways the BasicLibraryService can be implemented and which bits are necessary etc. For example, the ObjectAllocator is defined as an anonymous class but it can be an inner class.

[guyboertje]

I fear that we will create dogmatic cut and paste examples.

[monkstone]

Hi, I'm not so new to jruby extensions and can state categorically that the class names should just be different (as should method names, and there is a convention regarding method names). My issue with @headius is that he has never replied to my question, however it seems pretty clear by his actions that he favours implement Library over LibraryService. rake-compiler/rake-compiler#87

[enebo]

By convention all Ruby instances in native extensions are called 'RubyXXX' (e.g. RubySocket, RubyString, etc...).

Another common convention for stateless module definitions is to bind with static methods:

    @JRubyMethod(module = true)
    public static IRubyObject default_options(ThreadContext context, IRubyObject self) {

Any arg logic would follow self but self ends up being the self of the module itself.

@monkstone You mean BasicLibraryService right? I did not remember this even existed. We do not use it internally and I am not sure there ends up being a real difference but I also only use Library.

[rtyler]

An ellipsis, how ominous! 😃

[purbon]

Yeah! I was more on the idea shared later here by @enebo, using BasicLibraryService, using Library, etc... but yeah! the naming is funny!

[rtyler]

IMHO this is a great start and we should merge it and continue to iterate upon it.

[enebo]

@purbon can you followup by renaming Bar to RubyBar and I also think using static methods for module is more idiomatic so I would like to see that change based on my comment above.

[enebo]

@purbon and I should say I am very happy you are doing this for us!

[monkstone]

@enebo that was the clarification I had been seeking but the fact there is more than one way to it should be mentioned. I have plenty of examples to offer including static modules of my MathTool which is pretty standalone

[enebo]

@monkstone yeah agreed we have perhps too many ways to do things but I think providing a golden single path might be best for example apps.

[purbon]

@guyboertje in next iterations I will improve comments on both sides, my idea here is to provide good learning examples, if people end up c&p is hard to avoid, but I hope reader learn/understand what they will be doing.

[purbon]

@enebo thanks for bringing this in, I will follow up with your proposal of improvements. And obviously with more examples. A pleasure to help a nice community and project like this one! On the other side, I wonder what do you mean by golden single path? can you elaborate this a bit more?

@rtyler thanks for the appreciation man! looking forward to keep improving this!

@monkstone please contribute here, I really would like to see here a good discussion on providing good learning examples for jruby.

Thanks!

• purbon

[enebo]

@purbon by golden path I mean recommended idioms vs elaborating on different mechanisms for achieving the same task.

[purbon]

Makes sense, looking forward to keep this going!

Thanks for making jruby happen!

[mkristian]

maybe this should have been the right place for my comments: #3 (comment)