[#737] Extension logging

[robertpanzer]

This PR fixes #737 and allows extensions to also log LogRecords.

These LogRecords don't pass through Asciidoctor/Ruby though, so that handlers registered in Ruby won't get notified of them.

I had to make larger changes to the extension infrastructure to give extension access to their owning Asciidoctor instance.
@Mogztter This is a breaking change that will also hit you in AsciidoctorG, I renamed and changed the Interface that creates the extension delegates.
An extension now has a method unwrap(Class<?>) that allows to get the corresponding implementation.

[robertpanzer]

@Mogztter Do you have any objections against these changes?

[ggrossetie]

Sorry for the delay.

Do you have any objections against these changes?

No I do not have any objection 😉
So we now have two more methods in the API:

void log(LogRecord logRecord);
<T> T unwrap(Class<T> clazz);

The log method looks fine 👍
And we already talked about the unwrap method, it's necessary and useful.

I renamed and changed the Interface that creates the extension delegates.

I'm still trying to figure it out so I don't really mind for now.

[abelsromero]

I haven't been on the whole conversation but should we add unwrap to the docs explaining clearly when it is required?

[robertpanzer]

Good idea!

[robertpanzer]

@Mogztter Awesome, thanks! I wanted to have your approval as this will break your current AsciidoctorG.

I was thinking about creating a asciidoctorj-1.6.0 branch soon, and then let master evolve to 2.0.0.
So as this changes the interface of a Processor I don't want to merge it into 1.6.

[ggrossetie]

I was thinking about creating a asciidoctorj-1.6.0 branch soon, and then let master evolve to 2.0.0.
So as this changes the interface of a Processor I don't want to merge it into 1.6.

Why not, asciidoctorj-1.6.0 will be a "maintenance" branch for AsciidoctorJ 1.6.x ?
As far as I know, Asciidoctor 2.0.0 (core) will be released soon (end of January) so indeed we should merge it into master to prepare the ground for 2.0.0.

[mojavelinux]

I think the branch should be named asciidoctorj-1.6.x (or asciidoctorj-1.6.0.x). Aside from that, 👍

Once 2.0.0 is out, I'd like to use a more standard branch naming pattern. I've been using v2.0.x in other projects that use SemVer, though I'm open to discuss the "v" prefix. Perhaps best in a separate issue.

[ggrossetie]

Once 2.0.0 is out, I'd like to use a more standard branch naming pattern. I've been using v2.0.x in other projects that use SemVer, though I'm open to discuss the "v" prefix. Perhaps best in a separate issue.

Since npm creates tags prefixed by v, I don't use this prefix in branches names for usability reasons.
So when I type git checkout v (+ tab for expansion) I know that git will only show me tags. And when I type git checkout 1 I will only get branches (in this case maintenance branches for 1.x).

I know that Maven prepends the artifactId but I don't think it's necessary and it can be overridden:

<tagNameFormat>v@{project.version}</tagNameFormat>

http://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html

It should be possible to do the same with Gradle. Not saying that we should do it but it's possible to do so if we want to adopt a new format 😉

[robertpanzer]

I don't have any specific preference :-)
There's so many different ways each having its own advantages and disadvantages, that I am sure that whatever we choose, any possible disadvantage will bite us at some time 😅.

asciidoctorj-1.6.x would continue the tradition of asciidoctorj-1.5.x.

[robertpanzer]

Rebased.
This PR breaks binary compatibility with 1.6.x, there fore it must not be merged into the 1.6.x branch.

[mojavelinux]

So when I type git checkout v (+ tab for expansion) I know that git will only show me tags.

That's a strong argument for. 🤔

[robertpanzer]

I already went ahead and created a branch asciidoctorj-1.6.x.
I can certainly still rename it, but it would match the pattern of not starting with a v. :)

[mojavelinux]

I don't think any branch renames are necessary until 2.0.0. The 2.0.0 is the dawn of the new era where we try new things.