Remove finishSpanOnClose flag

This is a follow up on https://github.com/opentracing/opentracing-java/issues/267. The underlying issue of that one is that you can’t remember the finishSpanOnClose flag when implementing a bridge for ScopeManager#active().

The point of this issue is to remove the finishSpanOnClose flag altogether, as it is only useful in try-with-resources constructs which are a bad practice because you can’t can’t log exceptions as the span is closed before the catch block. To cite the main README.md:

Note that startActive(true) finishes the span on Scope.close(). Use it carefully because the try-with-resources construct finishes the span before the catch or finally blocks are executed, which makes logging exceptions and setting tags impossible. It is recommended to start the span and activate it later in try-with-resources. This makes the span available in catch and finally blocks.

So we are basically officially admitting that finishSpanOnClose is a bad practice.

You could argue that try-with-resources is valid if you don’t want to log exceptions. But what if a user then later decides that they do want to log exceptions? Do they still remember that they can’t use try-with-resources + a catch block then? I would most likely forget about that.

The finishSpanOnClose just enables some syntactic sugar after all which turns out to be problematic. As flag essentially advocates a bad practice, I suggest removing it.

Transition: Of course, we can’t just remove the flag which would introduce a breaking change.

Instead, I propose adding the method io.opentracing.Tracer.SpanBuilder#startActive() without arguments, which has the same semantics like calling spanBuilder.startActive(false). Also, deprecate io.opentracing.Tracer.SpanBuilder#startActive(boolean finishSpanOnClose). This method can then be removed on a later release (for example 1.0.0-RC1)

The Scope interface can still extend from Closeable, because logging an exception is still valid to do after the scope is closed.

I think, even after doing this, https://github.com/opentracing/opentracing-java/issues/267 (Deprecate or remove ScopeManager.active()) is still relevant, but maybe less severe.

[felixbarny]

The problem is that it requires people to actually read (and remember) the documentation because it’s counter-intuitive and thus error-prone.

[carlosalberto]

Hey @felixbarny ! as we merged #301, shall we close this?