You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID> on 2018/02/05 12:20:58 UTC
[imaging] IMAGING-154 remove Debug class
Hello,
If memory serves me well, some time ago we had a discussion around sanselan & commons-imaging 1.0. One of the issues with commons-imaging 1.0 was the Debug class.
https://issues.apache.org/jira/browse/IMAGING-154
I finished the pull request, but Gilles raised an important point, about discussing other alternatives first.
Initially I am against logging in low level libraries, especially commons components. But some time ago I had to debug TIFF issues in commons-imaging, and having the dump methods was a tremendous help.
The issue is that some imaging algorithms/processing have a lot of variables that can be altered. And keeping an eye on all of them in the debugger can be quite hard - though not impossible.
So all in all, now I am more confident to proceed without the Debug class. But some users could have a hard time investigating possible issues in the library without seeing what's going on within the library.
IMO, that could be solved with the logging/dump features... or through a better design, especially around exception handling/throwing. The latter is my preferred approach. Instead of logging, I prefer - whenever possible - that low level libraries throw exceptions and let me handle the logging.
So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a logging added to commons-imaging.
Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
>They are not necessarily exclusive options.
>I mean: (intending on) good design is necessary but, if achieved,
>it doesn't imply that logging is never necessary.
+1 agreed, regardless of the decision here.
>I'd like to recall that logging is a tool primarily for _users_:
>it helps them see how their data is handled by "lower" layers.
>[Even if the code is fine, some input data might make it seem to
>behave strangely, and it is not necessarily the job of the library
>developer to figure out how and why this happens. Moreover, in
>those cases, a debugger is not always the most productive tool.]
Agreed again. But here's where I think it's hard to trace a line between where we
should include logging or not.
Here's some code from commons-rng:
https://github.com/apache/commons-rng/blob/b28f668eea841289020cb89bcae1bd84151100ab/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/DiscreteProbabilityCollectionSampler.java#L91
In this line, DiscreteProbabilityCollectionSampler is throwing an exception because the
sum of probabilities is greater than 0. The exception is providing meaningful and simple
information about the error. And as a user I could want to check if there's anything wrong
with the lower level code.
In this case, the user will either debug, or modify the code to output some dump data as in
commons-imaging. Or just review his data and the conditions of the algorithm without inspecting
the code (maths is not really my speciality).
While it may be contrived example, I like the design in commons-rng's DiscreteProbabilityCollectionSampler,
and would not suggest to include logging there... though I can't really give more meaningful arguments.
Now here's some code from commons-imaging:
https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/JpegImageParser.java#L233
Here, while reading a JPEG image, the parser complains about the order of segments found
in the image. Someone familiar with the format might suspect there's something wrong, and
will either use some other tool to validate the segments, or inspect the code.
Then s/he will start reading the code, debug, or with the current code of commons-imaging,
it is possible to enable debug (setDebug(true) for that class) and see a dump of the current segments.
I think in this case we have good exception handling, and the dump method call is unnecessary.
While I agree logging the segments and other info here would be helpful, just seeing the message that
the segments order is wrong, and on which segment the parser failed, is already quite useful (maybe
as useful as knowing that the sum of probabilities in greater than 0 in the commons-rng example?).
Not trying to change your opinion on this example.
I believe we have had a few discussions around logging here in ASF - not only in commons - and that
there is not always a consensus.
And said all that, if the majority believes for the case of commons-imaging logging would be
good, I'm happy to update the pull request (: what's more important for me is having a 1.0 version that
can be released, so that I can keep working on an experiment with the library + IIIF.
Cheers
Bruno
________________________________
From: Gilles <gi...@harfang.homelinux.org>
To: dev@commons.apache.org
Sent: Tuesday, 6 February 2018 2:47 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
On Mon, 5 Feb 2018 04:41:20 -0800, Otto Fowler wrote:
> Maybe Debug should be an interface ( perhaps with the current class
> as the
> default implementation ) and be passed in optionally?
>
>
> On February 5, 2018 at 07:21:11, Bruno P. Kinoshita (
> brunodepaulak@yahoo.com.br.invalid) wrote:
>
> Hello,
>
> If memory serves me well, some time ago we had a discussion around
> sanselan
> & commons-imaging 1.0. One of the issues with commons-imaging 1.0 was
> the
> Debug class.
>
> https://issues.apache.org/jira/browse/IMAGING-154
>
> I finished the pull request, but Gilles raised an important point,
> about
> discussing other alternatives first.
>
> Initially I am against logging in low level libraries, especially
> commons
> components. But some time ago I had to debug TIFF issues in
> commons-imaging, and having the dump methods was a tremendous help.
>
>
> The issue is that some imaging algorithms/processing have a lot of
> variables that can be altered. And keeping an eye on all of them in
> the
> debugger can be quite hard - though not impossible.
>
> So all in all, now I am more confident to proceed without the Debug
> class.
> But some users could have a hard time investigating possible issues
> in the
> library without seeing what's going on within the library.
>
> IMO, that could be solved with the logging/dump features... or
> through a
> better design, especially around exception handling/throwing.
They are not necessarily exclusive options.
I mean: (intending on) good design is necessary but, if achieved,
it doesn't imply that logging is never necessary.
> The latter is
> my preferred approach. Instead of logging, I prefer - whenever
> possible -
> that low level libraries throw exceptions and let me handle the
> logging.
I'd like to recall that logging is a tool primarily for _users_:
it helps them see how their data is handled by "lower" layers.
[Even if the code is fine, some input data might make it seem to
behave strangely, and it is not necessarily the job of the library
developer to figure out how and why this happens. Moreover, in
those cases, a debugger is not always the most productive tool.]
> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> logging
> added to commons-imaging.
+1 to remove plain "println"
-0 to not provide an helpful alternative
In the end, the main developers' and support team should be free
to take the decision (IMHO), being fully aware that they deprive
themselves from potentially useful tools and additional help. :-)
Regards,
Gilles
> Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Gilles <gi...@harfang.homelinux.org>.
On Mon, 5 Feb 2018 04:41:20 -0800, Otto Fowler wrote:
> Maybe Debug should be an interface ( perhaps with the current class
> as the
> default implementation ) and be passed in optionally?
>
>
> On February 5, 2018 at 07:21:11, Bruno P. Kinoshita (
> brunodepaulak@yahoo.com.br.invalid) wrote:
>
> Hello,
>
> If memory serves me well, some time ago we had a discussion around
> sanselan
> & commons-imaging 1.0. One of the issues with commons-imaging 1.0 was
> the
> Debug class.
>
> https://issues.apache.org/jira/browse/IMAGING-154
>
> I finished the pull request, but Gilles raised an important point,
> about
> discussing other alternatives first.
>
> Initially I am against logging in low level libraries, especially
> commons
> components. But some time ago I had to debug TIFF issues in
> commons-imaging, and having the dump methods was a tremendous help.
>
>
> The issue is that some imaging algorithms/processing have a lot of
> variables that can be altered. And keeping an eye on all of them in
> the
> debugger can be quite hard - though not impossible.
>
> So all in all, now I am more confident to proceed without the Debug
> class.
> But some users could have a hard time investigating possible issues
> in the
> library without seeing what's going on within the library.
>
> IMO, that could be solved with the logging/dump features... or
> through a
> better design, especially around exception handling/throwing.
They are not necessarily exclusive options.
I mean: (intending on) good design is necessary but, if achieved,
it doesn't imply that logging is never necessary.
> The latter is
> my preferred approach. Instead of logging, I prefer - whenever
> possible -
> that low level libraries throw exceptions and let me handle the
> logging.
I'd like to recall that logging is a tool primarily for _users_:
it helps them see how their data is handled by "lower" layers.
[Even if the code is fine, some input data might make it seem to
behave strangely, and it is not necessarily the job of the library
developer to figure out how and why this happens. Moreover, in
those cases, a debugger is not always the most productive tool.]
> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> logging
> added to commons-imaging.
+1 to remove plain "println"
-0 to not provide an helpful alternative
In the end, the main developers' and support team should be free
to take the decision (IMHO), being fully aware that they deprive
themselves from potentially useful tools and additional help. :-)
Regards,
Gilles
> Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Otto Fowler <ot...@gmail.com>.
Maybe Debug should be an interface ( perhaps with the current class as the
default implementation ) and be passed in optionally?
On February 5, 2018 at 07:21:11, Bruno P. Kinoshita (
brunodepaulak@yahoo.com.br.invalid) wrote:
Hello,
If memory serves me well, some time ago we had a discussion around sanselan
& commons-imaging 1.0. One of the issues with commons-imaging 1.0 was the
Debug class.
https://issues.apache.org/jira/browse/IMAGING-154
I finished the pull request, but Gilles raised an important point, about
discussing other alternatives first.
Initially I am against logging in low level libraries, especially commons
components. But some time ago I had to debug TIFF issues in
commons-imaging, and having the dump methods was a tremendous help.
The issue is that some imaging algorithms/processing have a lot of
variables that can be altered. And keeping an eye on all of them in the
debugger can be quite hard - though not impossible.
So all in all, now I am more confident to proceed without the Debug class.
But some users could have a hard time investigating possible issues in the
library without seeing what's going on within the library.
IMO, that could be solved with the logging/dump features... or through a
better design, especially around exception handling/throwing. The latter is
my preferred approach. Instead of logging, I prefer - whenever possible -
that low level libraries throw exceptions and let me handle the logging.
So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a logging
added to commons-imaging.
Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hello Gilles!
I was interested in hearing your opinion as you commented in the previous thread too.
>[Hmm... Does "internal" mean that minor release can break BC
>on such a class?]
I think so, yes. [1] is a commit to a temporary branch, where I renamed the .util package to internal, and updated the package-info.java, with a note. I am thinking about using that commit regardless of what's decided with the logging, so that users will be warned about the Debug class usage. Also added notes to Javadocs of Debug.
>[Depends on what "low-level" means here. "stdout"/"stderr" is
>indeed used in low-level utilities but is the intent the same
>here?]
I don't think so. My use case for Commons Imaging is to use it in the IIIF server Cantaloupe, to test and compare with other image libraries, with life sciences images. As the application will be running in the web, I would like to have proper logging, or at least be able to decide where and weather it is logged.
>> which means removing the verbose flags, the checks, and calls to
>> System.out in there.
>
>It would be a loss of potentially useful information (e.g. for
>debugging).
Indeed. Probably we should be looking for the alternatives that keep the existing verbose/logging... but probably allowing for more customisation I guess...
Thanks a lot Gilles!
Bruno
[1] https://github.com/kinow/commons-imaging/commit/736fd115c12642ecabb3b4ab73df83b1e5982076
________________________________
From: Gilles <gi...@harfang.homelinux.org>
To: dev@commons.apache.org
Sent: Monday, 13 August 2018 12:21 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
Hello Bruno.
On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> Hi all,
>
>
> I commented on IMAGING-154, but copying the last comment here as it
> contains the approach I would like to follow to fix the last change
> in
> the project blocking
> a 1.0 release:
>
>
> ---
>
> So went ahead to re-design the Debug class, in a way users could
> still enable/disable debugging, and also use a PrintStream so that
> other thing rather than System.out could be used.
>
>
>
> Then, realized removing System.out was the natural next step. But
> alas, the library uses System.out for debugging, but sometimes it
> uses
> it for writing to System.out in a "verbose mode". What is more
> complicated, is that sometimes classes methods like `toString()` are
> calling debug methods that receive a PrintStream already.
>
>
>
> So I spent some more time quickly comparing what other libraries I've
> seen being used / or used for image processing:
>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/.
> Turns out only very low level libraries, such as the JNI bridge for
> OpenCV, im4java, and Java's ImageIO can do with just throwing
> Exception's.
>
>
>
> All other libraries have one way or another of logging. Be it with
> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>
>
>
> My preferred compromise for this ticket was to keep Debug, making
> System.out possible but optional, and mark the class internal only.
> Now my preferred solution is to keep the Debug internal, but add a
> logger to it. And then also add logging to replace where System.out
> is
> used for the "verbose" mode.
> ---
>
>
>
> Any thoughts? Objections? If none, I will try to work on this issue
> next weekend, making the Debug class internal only, and replacing
> System.out by a logging utility. After that, we should be good to
> start preparing the vote for 1.0.
>
>
>
> * I know it's hard to get a consensus on having logging in Commons
> components, as we have normally low level libraries, where using
> logging is not always practical.
There are Log4j2 experts reading here. It would be interesting
to hear them about what is practical or not. There are several
aspects to "practical": simplicity, flexibility, compatibility,
performance, ...
How does Log4j2 fare in these areas?
Is there a known (through experience) limit in where it should
be used?
> But I would now argue that Java own
> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
> Imaging are located at a higher level, some times even using it for
> basic image handling/parsing/reading.
As with many discussions on this list, conflicting arguments occur
because people lack common (!) definitions.
So one goes: "You cannot do <something> in a low-level component"
but does not define "low-level"...
> * Feel free to cast a counter-argument for it, but please think
> whether you'd still be -0, +0 for this change. We have delayed 1.0
> for
> a while, so if you have a strong opinion on not adding a logger,
> please provide an alternative for IMAGING-154.
> Otherwise we may fail
> to prepare a 1.0 release yet again, and then somebody else may have
> to
> work on it in a few months/years...
We are there because the project is too rigid about itself as
a whole (cf. for example the [RNG] thread about BC).
IMHO, it's not the always least common denominator that is the
best decision...
As you noticed, components most easily stall in their development
for lack of proper review, or risk acceptance (i.e. assume that
those who are closer to the code (at a given time) probably know
best... :-/
My opinion is that we can take the risk to introduce logging, and
if people complain somehow, take it back later.
> one possible compromise for this,
> might be i) make Debug internal,
+1
[Hmm... Does "internal" mean that minor release can break BC
on such a class?]
> ii) remove all System.out calls,
+1 or
-1
[Depends on what "low-level" means here. "stdout"/"stderr" is
indeed used in low-level utilities but is the intent the same
here?]
> which means removing the verbose flags, the checks, and calls to
> System.out in there.
It would be a loss of potentially useful information (e.g. for
debugging).
Regards,
Gilles
>
> Thanks!
> Bruno
>
> ________________________________
> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> To: Commons Developers List <de...@commons.apache.org>
> Sent: Tuesday, 6 February 2018 11:30 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> Hi sebb,
>
>>Another aspect of debugging is ensuring that methods are small and
>
>>easily tested independently.
>>However this is difficult to do, and care must be taken to ensure
>> that
>>the public API is not unnecessarily extended..
>
> A very good point.
>
> The parsers in commons-imaging expose some #dump... methods
>
> (https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794).
>
> While I can see that parsers may need to dump the data they are
> holding in some structured way for inspecting, reporting,
> serializing,
> etc, it looks like some other classes were affected by it too. For
> example...
>
>
> A JPEG Segment has a #dump() method
>
>
>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>
>
> which gets defined in each subclass of Segment. It can be confusing
> to have a method such as #dump() in a Segment, from the point of view
> of someone writing a photo editor for example. The user could use
> that
> to pass his/her own logger's PrintWriter, which would make removing
> or
> changing logging in the future in commons-imaging.
>
>
> If we keep the Debug class, and make it internal, there would still
> be these methods to take care. And there are some methods where users
> can provide a PrintWriter, while others instead use System.out
>
> (e.g.https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70).
>
> Cheers
> Bruno
>
> ________________________________
> From: sebb <se...@gmail.com>
> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> Kinoshita <br...@yahoo.com.br>
> Sent: Tuesday, 6 February 2018 11:06 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> <br...@yahoo.com.br.invalid> wrote:
>> Hi Jorg,
>>
>> I'd be fine with that solution too. I think this one would cause the
>> smaller change to the code as is.
>>
>> I believe my preference is still to remove the Debug class. But
>> between logging and making Debug internal only, I'd choose making it
>> internal.
>
> +1
>
> I think making it internal means it can still be dropped later.
>
>> Looking forward to hearing what others think about these options.
>>
>
> Another aspect of debugging is ensuring that methods are small and
> easily tested independently.
> However this is difficult to do, and care must be taken to ensure
> that
> the public API is not unnecessarily extended..
>
>> Thanks
>> Bruno
>>
>>
>> ________________________________
>> From: Jörg Schaible <jo...@bpm-inspire.com>
>> To: dev@commons.apache.org
>> Sent: Tuesday, 6 February 2018 9:24 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> Hi Bruno,
>>
>>
>> if it might also be helpful to our users, why not keep and provide
>> it. As
>>
>> I understand it, the Debug class is a tool helping in development to
>>
>> analyze some behavior.
>>
>>
>> Nothing stops us from declaring this class internal (we might even
>> put it
>>
>> into a package "internal" or "debug") that might be changed without
>>
>> further comment. Nobody may rely on it in production code, but
>> during
>>
>> development it might be helpful. With such an approach we might not
>> have
>>
>> a need to find a better interface to provide this functionality.
>>
>>
>> Just my 2¢,
>>
>> Jörg
>>
>>
>>
>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>
>>
>>> Hello,
>>
>>>
>>
>>> If memory serves me well, some time ago we had a discussion around
>>
>>> sanselan & commons-imaging 1.0. One of the issues with
>>> commons-imaging
>>
>>> 1.0 was the Debug class.
>>
>>>
>>
>>> https://issues.apache.org/jira/browse/IMAGING-154
>>
>>>
>>
>>> I finished the pull request, but Gilles raised an important point,
>>> about
>>
>>> discussing other alternatives first.
>>
>>>
>>
>>> Initially I am against logging in low level libraries, especially
>>
>>> commons components. But some time ago I had to debug TIFF issues in
>>
>>> commons-imaging, and having the dump methods was a tremendous help.
>>
>>>
>>
>>>
>>
>>> The issue is that some imaging algorithms/processing have a lot of
>>
>>> variables that can be altered. And keeping an eye on all of them in
>>> the
>>
>>> debugger can be quite hard - though not impossible.
>>
>>>
>>
>>> So all in all, now I am more confident to proceed without the Debug
>>
>>> class. But some users could have a hard time investigating possible
>>
>>> issues in the library without seeing what's going on within the
>>> library.
>>
>>>
>>
>>> IMO, that could be solved with the logging/dump features... or
>>> through a
>>
>>> better design, especially around exception handling/throwing. The
>>> latter
>>
>>> is my preferred approach. Instead of logging, I prefer - whenever
>>
>>> possible - that low level libraries throw exceptions and let me
>>> handle
>>
>>> the logging.
>>
>>>
>>
>>>
>>
>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>
>>> logging added to commons-imaging.
>>
>>>
>>
>>> Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi Remko!
Thanks a lot for your reply, and for the great points.
As for dependencies, being an image library, I think eventually we may have dependencies in Commons Imaging. I am not keen to add dependencies myself, but there could be a case for a dependency in order to support some image type, compression algorithm, etc... though it could be an optional runtime dependency...
But I'd be OK with the JUL, though performance-wise I'm not sure if that's the best choice [1]
On with performance... I'd be OK if the logger picked was not so fast. I think we should keep the current design, where verbose and debug mode are OFF by default. Users would have to turn it on in order to enable logging. Errors are reported through exceptions. In Commons Imaging, we will use logging to print some algorithm tables, say whether we successfully parsed an image or not, what is the colour space of some image, and so it goes.
I'm also biased to using Log4j, though I deployed a few systems with slf4j+logback (mainly spring boot apps) and it wasn't that bad.
And on your final note, +1. I worked in a team as devops working closely with sysadmins, and that helped me to feel more empathy, and understand why proper logging is so important, why I must do everything I can to allow the system to be easily configurable, good error messages, etc. So +1 for err, if we have to choose between out/err.
Cheers
Bruno
[1] https://www.sitepoint.com/which-java-logging-framework-has-the-best-performance/
________________________________
From: Remko Popma <re...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Monday, 13 August 2018 2:00 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
There’s a couple of considerations about doing logging in a library, but I’ll just mention a few:
* dependencies
* performance
* ease of use
* Dependencies*
Will the library be less attractive to users if it requires an external dependency? Then don’t introduce one (so: use system err or JUL). On the other hand, if the vast majority of usages is in a context with many other external libraries (like in a web container) you have more freedom.
*Performance*
Please take a look at the log4j 2 performance page (https://logging.apache.org/log4j/2.x/performance.html#tradeoffs). Console logging is 50x (yes fifty times) slower than file logging.
That’s a strong argument against system err logging. I’m not a fan of JUL, but if you need to avoid dependencies you’re better off using JUL, that’s only 5x slower than log4j. Also depends on how much logging you expect to do in the worst case.
*Ease of use*
I’m biased and would say that Log4j 2 has the nicest and richest API. Console logging (System.err.printf) probably has the poorest API. Other libraries sit in the middle.
*Final note*
I would never log to System out, always use system err instead. This allows programs using your library to pipe output to other programs without their output getting mixed with your library’s diagnostic output.
Hope this helps,
Remko
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org> wrote:
>
> Hello Bruno.
>
>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>> Hi all,
>>
>>
>> I commented on IMAGING-154, but copying the last comment here as it
>> contains the approach I would like to follow to fix the last change in
>> the project blocking
>> a 1.0 release:
>>
>>
>> ---
>>
>> So went ahead to re-design the Debug class, in a way users could
>> still enable/disable debugging, and also use a PrintStream so that
>> other thing rather than System.out could be used.
>>
>>
>>
>> Then, realized removing System.out was the natural next step. But
>> alas, the library uses System.out for debugging, but sometimes it uses
>> it for writing to System.out in a "verbose mode". What is more
>> complicated, is that sometimes classes methods like `toString()` are
>> calling debug methods that receive a PrintStream already.
>>
>>
>>
>> So I spent some more time quickly comparing what other libraries I've
>> seen being used / or used for image processing:
>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/.
>> Turns out only very low level libraries, such as the JNI bridge for
>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>> Exception's.
>>
>>
>>
>> All other libraries have one way or another of logging. Be it with
>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>
>>
>>
>> My preferred compromise for this ticket was to keep Debug, making
>> System.out possible but optional, and mark the class internal only.
>> Now my preferred solution is to keep the Debug internal, but add a
>> logger to it. And then also add logging to replace where System.out is
>> used for the "verbose" mode.
>> ---
>>
>>
>>
>> Any thoughts? Objections? If none, I will try to work on this issue
>> next weekend, making the Debug class internal only, and replacing
>> System.out by a logging utility. After that, we should be good to
>> start preparing the vote for 1.0.
>>
>>
>>
>> * I know it's hard to get a consensus on having logging in Commons
>> components, as we have normally low level libraries, where using
>> logging is not always practical.
>
> There are Log4j2 experts reading here. It would be interesting
> to hear them about what is practical or not. There are several
> aspects to "practical": simplicity, flexibility, compatibility,
> performance, ...
> How does Log4j2 fare in these areas?
> Is there a known (through experience) limit in where it should
> be used?
>
>> But I would now argue that Java own
>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>> Imaging are located at a higher level, some times even using it for
>> basic image handling/parsing/reading.
>
> As with many discussions on this list, conflicting arguments occur
> because people lack common (!) definitions.
> So one goes: "You cannot do <something> in a low-level component"
> but does not define "low-level"...
>
>> * Feel free to cast a counter-argument for it, but please think
>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>> a while, so if you have a strong opinion on not adding a logger,
>> please provide an alternative for IMAGING-154.
>
>> Otherwise we may fail
>> to prepare a 1.0 release yet again, and then somebody else may have to
>> work on it in a few months/years...
>
> We are there because the project is too rigid about itself as
> a whole (cf. for example the [RNG] thread about BC).
> IMHO, it's not the always least common denominator that is the
> best decision...
> As you noticed, components most easily stall in their development
> for lack of proper review, or risk acceptance (i.e. assume that
> those who are closer to the code (at a given time) probably know
> best... :-/
>
> My opinion is that we can take the risk to introduce logging, and
> if people complain somehow, take it back later.
>
>> one possible compromise for this,
>> might be i) make Debug internal,
>
> +1
>
> [Hmm... Does "internal" mean that minor release can break BC
> on such a class?]
>
>> ii) remove all System.out calls,
>
> +1 or
> -1
>
> [Depends on what "low-level" means here. "stdout"/"stderr" is
> indeed used in low-level utilities but is the intent the same
> here?]
>
>> which means removing the verbose flags, the checks, and calls to
>> System.out in there.
>
> It would be a loss of potentially useful information (e.g. for
> debugging).
>
> Regards,
> Gilles
>
>>
>> Thanks!
>> Bruno
>>
>> ________________________________
>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>> To: Commons Developers List <de...@commons.apache.org>
>> Sent: Tuesday, 6 February 2018 11:30 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> Hi sebb,
>>
>>> Another aspect of debugging is ensuring that methods are small and
>>
>>> easily tested independently.
>>> However this is difficult to do, and care must be taken to ensure that
>>> the public API is not unnecessarily extended..
>>
>> A very good point.
>>
>> The parsers in commons-imaging expose some #dump... methods
>> (https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794).
>>
>> While I can see that parsers may need to dump the data they are
>> holding in some structured way for inspecting, reporting, serializing,
>> etc, it looks like some other classes were affected by it too. For
>> example...
>>
>>
>> A JPEG Segment has a #dump() method
>>
>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>
>>
>> which gets defined in each subclass of Segment. It can be confusing
>> to have a method such as #dump() in a Segment, from the point of view
>> of someone writing a photo editor for example. The user could use that
>> to pass his/her own logger's PrintWriter, which would make removing or
>> changing logging in the future in commons-imaging.
>>
>>
>> If we keep the Debug class, and make it internal, there would still
>> be these methods to take care. And there are some methods where users
>> can provide a PrintWriter, while others instead use System.out
>> (e.g.https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70).
>>
>> Cheers
>> Bruno
>>
>> ________________________________
>> From: sebb <se...@gmail.com>
>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>> Kinoshita <br...@yahoo.com.br>
>> Sent: Tuesday, 6 February 2018 11:06 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>> <br...@yahoo.com.br.invalid> wrote:
>>> Hi Jorg,
>>>
>>> I'd be fine with that solution too. I think this one would cause the smaller change to the code as is.
>>>
>>> I believe my preference is still to remove the Debug class. But between logging and making Debug internal only, I'd choose making it internal.
>>
>> +1
>>
>> I think making it internal means it can still be dropped later.
>>
>>> Looking forward to hearing what others think about these options.
>>>
>>
>> Another aspect of debugging is ensuring that methods are small and
>> easily tested independently.
>> However this is difficult to do, and care must be taken to ensure that
>> the public API is not unnecessarily extended..
>>
>>> Thanks
>>> Bruno
>>>
>>>
>>> ________________________________
>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>> To: dev@commons.apache.org
>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>
>>>
>>>
>>> Hi Bruno,
>>>
>>>
>>> if it might also be helpful to our users, why not keep and provide it. As
>>>
>>> I understand it, the Debug class is a tool helping in development to
>>>
>>> analyze some behavior.
>>>
>>>
>>> Nothing stops us from declaring this class internal (we might even put it
>>>
>>> into a package "internal" or "debug") that might be changed without
>>>
>>> further comment. Nobody may rely on it in production code, but during
>>>
>>> development it might be helpful. With such an approach we might not have
>>>
>>> a need to find a better interface to provide this functionality.
>>>
>>>
>>> Just my 2¢,
>>>
>>> Jörg
>>>
>>>
>>>
>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>
>>>
>>>> Hello,
>>>
>>>>
>>>
>>>> If memory serves me well, some time ago we had a discussion around
>>>
>>>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
>>>
>>>> 1.0 was the Debug class.
>>>
>>>>
>>>
>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>
>>>>
>>>
>>>> I finished the pull request, but Gilles raised an important point, about
>>>
>>>> discussing other alternatives first.
>>>
>>>>
>>>
>>>> Initially I am against logging in low level libraries, especially
>>>
>>>> commons components. But some time ago I had to debug TIFF issues in
>>>
>>>> commons-imaging, and having the dump methods was a tremendous help.
>>>
>>>>
>>>
>>>>
>>>
>>>> The issue is that some imaging algorithms/processing have a lot of
>>>
>>>> variables that can be altered. And keeping an eye on all of them in the
>>>
>>>> debugger can be quite hard - though not impossible.
>>>
>>>>
>>>
>>>> So all in all, now I am more confident to proceed without the Debug
>>>
>>>> class. But some users could have a hard time investigating possible
>>>
>>>> issues in the library without seeing what's going on within the library.
>>>
>>>>
>>>
>>>> IMO, that could be solved with the logging/dump features... or through a
>>>
>>>> better design, especially around exception handling/throwing. The latter
>>>
>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>>
>>>> possible - that low level libraries throw exceptions and let me handle
>>>
>>>> the logging.
>>>
>>>>
>>>
>>>>
>>>
>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>>
>>>> logging added to commons-imaging.
>>>
>>>>
>>>
>>>> Bruno
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Work on java.util.logging was done some days ago, and I've just updated it following suggestions from comments in GitHub.
https://github.com/apache/commons-imaging/pull/35
Will start working on the maven plugin versions, copying things from the pom.xml of rng & lang to match commons-parent version and properties (I assume that's a requirement for the new commons release plugin), and commit my work on a IMAGING-103 branch.
If there are no other comments or objections, will merge the jul work next weekend 25/26 aug.
And if I have the website updated and building locally, 1.0 vote should go out in September!
Thanks!
Bruno
________________________________
From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
To: Commons Developers List <de...@commons.apache.org>
Sent: Thursday, 16 August 2018 12:26 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
Hi,
Remko's suggestion sounded good, and the KISS principle resounded well with this issue. I think we are using very little of what's provided by a complete logging framework, so JUL should do the trick for now. Also decided to have a crack at it before weekend.
Pull request updated, where
1) Debug is in a "internal" package now, using JUL instead of System.out
2) Debug messages go to FINE level
3) Verbose messages, and messages that were printed without any flag, are now in INFO level
4) Removed a few lines that were printing empty lines
5) Tried to keep API the same the maximum I could
If approved & merged, planning to add a section to the web site with something about the items above, and an example on how to configure it.
Would someone have time to, please, review the pull request?
https://github.com/apache/commons-imaging/pull/35/files
Backed up the old branch with a different name (just in case).
Thanks you!
Bruno
________________________________
From: Matt Sicker <bo...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Wednesday, 15 August 2018 9:20 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
Depends on how complicated your log messages are. Parameterized logging and
automatic level-checking guards aren't available, but it's workable. If you
use Java 8 at least, they added a lambda version of log messages so you
don't even need to worry about string formatting having a performance issue
when logging is disabled.
On Tue, 14 Aug 2018 at 05:56, sebb <se...@gmail.com> wrote:
> On 13 August 2018 at 20:01, Matt Sicker <bo...@gmail.com> wrote:
> > As an end user of JUL in other projects, let me warn you that you'll
> miss a
> > lot of abstractions that log4j2 and slf4j provide. :)
>
> But do they matter in this context?
>
> Or is JUL (+ adapter) good enough?
>
> > On Mon, 13 Aug 2018 at 09:50, Gary Gregory <ga...@gmail.com>
> wrote:
> >
> >> I like Remko's suggestion, a nice application of the KISS principle ;-)
> >>
> >> Gary
> >>
> >> On Mon, Aug 13, 2018, 07:58 Remko Popma <re...@gmail.com> wrote:
> >>
> >> > If it was up to me I would use JUL in this particular case to keep the
> >> > library free of dependencies. JUL is reasonable since performance is
> not
> >> an
> >> > issue.
> >> >
> >> > Users that use a logging framework can redirect the JUL logging into
> >> their
> >> > log file with the JUL adapter of their logging library.
> >> >
> >> > But that’s just me.
> >> >
> >> > Remko
> >> >
> >> > (Shameless plug) Every java main() method deserves
> http://picocli.info
> >> >
> >> > > On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <
> >> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> >> > >
> >> > > I was thinking more about using that as an argument for using a
> logging
> >> > framework, but I think you are right. Probably slf4j/commons-logging +
> >> some
> >> > default binding, then allowing users to change the implementation.
> >> > >
> >> > > Perhaps slf4j + log4j?
> >> > >
> >> > >
> >> > > Bruno
> >> > >
> >> > > ________________________________
> >> > > From: Remko Popma <re...@gmail.com>
> >> > > To: Commons Developers List <de...@commons.apache.org>
> >> > > Sent: Monday, 13 August 2018 11:55 PM
> >> > > Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > > For new projects I would really avoid using Commons Logging. Ceki
> had a
> >> > point when he created SLF4J.
> >> > >
> >> > >
> >> > > The projects you mentioned that have a dependency on Commons Logging
> >> > were started before SLF4J (and perhaps JUL) were created, I believe.
> >> > >
> >> > >
> >> > >
> >> > > (Shameless plug) Every java main() method deserves
> http://picocli.info
> >> > >
> >> > >
> >> > >>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <
> >> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> >> > >
> >> > >> Right now that's where I am standing too. If adding a dependency to
> >> > log4j is a no-no, then I'd probably check if jul would be OK, or
> >> otherwise
> >> > maybe import just Log4J's LowLevelLogUtil into the project would work?
> >> > >
> >> > >
> >> > >
> >> > >> Commons DBCP, Commons Configuration, Commons Beanutils, Commons
> JEXL,
> >> > and Commons Validator. All of these have a compile dependency to
> Commons
> >> > Logging. So it wouldn't be creating a new precedent.
> >> > >
> >> > >
> >> > >
> >> > >> Commons Pool and Commons Compress have some optional dependencies,
> but
> >> > none for logging... maybe an optional dependency, with disabling the
> >> > logging by default **could** work?
> >> > >
> >> > >
> >> > >
> >> > >> Cheers
> >> > >
> >> > >> Bruno
> >> > >
> >> > >
> >> > >
> >> > >> ________________________________
> >> > >
> >> > >> From: Remko Popma <re...@gmail.com>
> >> > >
> >> > >> To: Commons Developers List <de...@commons.apache.org>
> >> > >
> >> > >> Sent: Monday, 13 August 2018 9:50 AM
> >> > >
> >> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >> If you want to avoid a dependency I would not create a custom
> logging
> >> > abstraction but just use JUL. Most logging libraries have JUL
> adapters so
> >> > clients can do the bridging on their side.
> >> > >
> >> > >
> >> > >> (Shameless plug) Every java main() method deserves
> >> http://picocli.info
> >> > >
> >> > >
> >> > >>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
> >> > >
> >> > >
> >> > >>> What I've seen done when trying to avoid a logging API dependency
> is
> >> to
> >> > >
> >> > >>> create a minimal logging API purely for framework use. This can
> have
> >> a
> >> > >
> >> > >>> default System.err style implementation, but the idea is to make
> it
> >> > easy
> >> > >
> >> > >>> (and performant hopefully) to bridge into the end user's choice of
> >> > >
> >> > >>> framework and configuration without actually requiring a real
> logging
> >> > >
> >> > >>> framework (at least until you want to use it in production).
> While it
> >> > seems
> >> > >
> >> > >>> overkill, the problem is that neither JUL nor System.err are
> >> > sufficient for
> >> > >
> >> > >>> logging. Even a simple API like Android's logging API can be good
> >> > enough to
> >> > >
> >> > >>> abstract it in a small library.
> >> > >
> >> > >
> >> > >>> For a look at the very simplest route, you can see how Log4j2
> handles
> >> > >
> >> > >>> logging before any logging classes have been initialized. It's
> >> > basically a
> >> > >
> >> > >>> configurable wrapper around System.err:
> >> > >
> >> > >>>
> >> >
> >>
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
> >> > >
> >> > >
> >> > >
> >> > >>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <
> garydgregory@gmail.com>
> >> > wrote:
> >> > >
> >> > >
> >> > >>>> You could also log to a pluggable print stream which could be sys
> >> err
> >> > by
> >> > >
> >> > >>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as
> >> well
> >> > :-)
> >> > >
> >> > >
> >> > >>>> Gary
> >> > >
> >> > >
> >> > >>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
> >> > wrote:
> >> > >
> >> > >
> >> > >>>>> There’s a couple of considerations about doing logging in a
> >> library,
> >> > but
> >> > >
> >> > >>>>> I’ll just mention a few:
> >> > >
> >> > >
> >> > >>>>> * dependencies
> >> > >
> >> > >>>>> * performance
> >> > >
> >> > >>>>> * ease of use
> >> > >
> >> > >
> >> > >>>>> * Dependencies*
> >> > >
> >> > >>>>> Will the library be less attractive to users if it requires an
> >> > external
> >> > >
> >> > >>>>> dependency? Then don’t introduce one (so: use system err or
> JUL).
> >> On
> >> > the
> >> > >
> >> > >>>>> other hand, if the vast majority of usages is in a context with
> >> many
> >> > >
> >> > >>>> other
> >> > >
> >> > >>>>> external libraries (like in a web container) you have more
> freedom.
> >> > >
> >> > >
> >> > >>>>> *Performance*
> >> > >
> >> > >>>>> Please take a look at the log4j 2 performance page (
> >> > >
> >> > >>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs
> ).
> >> > >
> >> > >>>> Console
> >> > >
> >> > >>>>> logging is 50x (yes fifty times) slower than file logging.
> >> > >
> >> > >>>>> That’s a strong argument against system err logging. I’m not a
> fan
> >> of
> >> > >
> >> > >>>> JUL,
> >> > >
> >> > >>>>> but if you need to avoid dependencies you’re better off using
> JUL,
> >> > that’s
> >> > >
> >> > >>>>> only 5x slower than log4j. Also depends on how much logging you
> >> > expect to
> >> > >
> >> > >>>>> do in the worst case.
> >> > >
> >> > >
> >> > >>>>> *Ease of use*
> >> > >
> >> > >>>>> I’m biased and would say that Log4j 2 has the nicest and richest
> >> API.
> >> > >
> >> > >>>>> Console logging (System.err.printf) probably has the poorest
> API.
> >> > Other
> >> > >
> >> > >>>>> libraries sit in the middle.
> >> > >
> >> > >
> >> > >>>>> *Final note*
> >> > >
> >> > >>>>> I would never log to System out, always use system err instead.
> >> This
> >> > >
> >> > >>>>> allows programs using your library to pipe output to other
> programs
> >> > >
> >> > >>>> without
> >> > >
> >> > >>>>> their output getting mixed with your library’s diagnostic
> output.
> >> > >
> >> > >
> >> > >>>>> Hope this helps,
> >> > >
> >> > >
> >> > >>>>> Remko
> >> > >
> >> > >
> >> > >>>>> (Shameless plug) Every java main() method deserves
> >> > http://picocli.info
> >> > >
> >> > >
> >> > >>>>>> On Aug 12, 2018, at 21:21, Gilles <
> gilles@harfang.homelinux.org>
> >> > >
> >> > >>>> wrote:
> >> > >
> >> > >
> >> > >>>>>> Hello Bruno.
> >> > >
> >> > >
> >> > >>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita
> >> wrote:
> >> > >
> >> > >>>>>>> Hi all,
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> I commented on IMAGING-154, but copying the last comment here
> as
> >> it
> >> > >
> >> > >>>>>>> contains the approach I would like to follow to fix the last
> >> > change in
> >> > >
> >> > >>>>>>> the project blocking
> >> > >
> >> > >>>>>>> a 1.0 release:
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> ---
> >> > >
> >> > >
> >> > >>>>>>> So went ahead to re-design the Debug class, in a way users
> could
> >> > >
> >> > >>>>>>> still enable/disable debugging, and also use a PrintStream so
> >> that
> >> > >
> >> > >>>>>>> other thing rather than System.out could be used.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Then, realized removing System.out was the natural next step.
> But
> >> > >
> >> > >>>>>>> alas, the library uses System.out for debugging, but
> sometimes it
> >> > uses
> >> > >
> >> > >>>>>>> it for writing to System.out in a "verbose mode". What is more
> >> > >
> >> > >>>>>>> complicated, is that sometimes classes methods like
> `toString()`
> >> > are
> >> > >
> >> > >>>>>>> calling debug methods that receive a PrintStream already.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> So I spent some more time quickly comparing what other
> libraries
> >> > I've
> >> > >
> >> > >>>>>>> seen being used / or used for image processing:
> >> > >
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> >> > >
> >> > >>>>> .
> >> > >
> >> > >>>>>>> Turns out only very low level libraries, such as the JNI
> bridge
> >> for
> >> > >
> >> > >>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
> >> > >
> >> > >>>>>>> Exception's.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> All other libraries have one way or another of logging. Be it
> >> with
> >> > >
> >> > >>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> My preferred compromise for this ticket was to keep Debug,
> making
> >> > >
> >> > >>>>>>> System.out possible but optional, and mark the class internal
> >> only.
> >> > >
> >> > >>>>>>> Now my preferred solution is to keep the Debug internal, but
> add
> >> a
> >> > >
> >> > >>>>>>> logger to it. And then also add logging to replace where
> >> > System.out is
> >> > >
> >> > >>>>>>> used for the "verbose" mode.
> >> > >
> >> > >>>>>>> ---
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Any thoughts? Objections? If none, I will try to work on this
> >> issue
> >> > >
> >> > >>>>>>> next weekend, making the Debug class internal only, and
> replacing
> >> > >
> >> > >>>>>>> System.out by a logging utility. After that, we should be
> good to
> >> > >
> >> > >>>>>>> start preparing the vote for 1.0.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> * I know it's hard to get a consensus on having logging in
> >> Commons
> >> > >
> >> > >>>>>>> components, as we have normally low level libraries, where
> using
> >> > >
> >> > >>>>>>> logging is not always practical.
> >> > >
> >> > >
> >> > >>>>>> There are Log4j2 experts reading here. It would be interesting
> >> > >
> >> > >>>>>> to hear them about what is practical or not. There are several
> >> > >
> >> > >>>>>> aspects to "practical": simplicity, flexibility, compatibility,
> >> > >
> >> > >>>>>> performance, ...
> >> > >
> >> > >>>>>> How does Log4j2 fare in these areas?
> >> > >
> >> > >>>>>> Is there a known (through experience) limit in where it should
> >> > >
> >> > >>>>>> be used?
> >> > >
> >> > >
> >> > >>>>>>> But I would now argue that Java own
> >> > >
> >> > >>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
> >> > Commons
> >> > >
> >> > >>>>>>> Imaging are located at a higher level, some times even using
> it
> >> for
> >> > >
> >> > >>>>>>> basic image handling/parsing/reading.
> >> > >
> >> > >
> >> > >>>>>> As with many discussions on this list, conflicting arguments
> occur
> >> > >
> >> > >>>>>> because people lack common (!) definitions.
> >> > >
> >> > >>>>>> So one goes: "You cannot do <something> in a low-level
> component"
> >> > >
> >> > >>>>>> but does not define "low-level"...
> >> > >
> >> > >
> >> > >>>>>>> * Feel free to cast a counter-argument for it, but please
> think
> >> > >
> >> > >>>>>>> whether you'd still be -0, +0 for this change. We have delayed
> >> 1.0
> >> > for
> >> > >
> >> > >>>>>>> a while, so if you have a strong opinion on not adding a
> logger,
> >> > >
> >> > >>>>>>> please provide an alternative for IMAGING-154.
> >> > >
> >> > >
> >> > >>>>>>> Otherwise we may fail
> >> > >
> >> > >>>>>>> to prepare a 1.0 release yet again, and then somebody else may
> >> > have to
> >> > >
> >> > >>>>>>> work on it in a few months/years...
> >> > >
> >> > >
> >> > >>>>>> We are there because the project is too rigid about itself as
> >> > >
> >> > >>>>>> a whole (cf. for example the [RNG] thread about BC).
> >> > >
> >> > >>>>>> IMHO, it's not the always least common denominator that is the
> >> > >
> >> > >>>>>> best decision...
> >> > >
> >> > >>>>>> As you noticed, components most easily stall in their
> development
> >> > >
> >> > >>>>>> for lack of proper review, or risk acceptance (i.e. assume that
> >> > >
> >> > >>>>>> those who are closer to the code (at a given time) probably
> know
> >> > >
> >> > >>>>>> best... :-/
> >> > >
> >> > >
> >> > >>>>>> My opinion is that we can take the risk to introduce logging,
> and
> >> > >
> >> > >>>>>> if people complain somehow, take it back later.
> >> > >
> >> > >
> >> > >>>>>>> one possible compromise for this,
> >> > >
> >> > >>>>>>> might be i) make Debug internal,
> >> > >
> >> > >
> >> > >>>>>> +1
> >> > >
> >> > >
> >> > >>>>>> [Hmm... Does "internal" mean that minor release can break BC
> >> > >
> >> > >>>>>> on such a class?]
> >> > >
> >> > >
> >> > >>>>>>> ii) remove all System.out calls,
> >> > >
> >> > >
> >> > >>>>>> +1 or
> >> > >
> >> > >>>>>> -1
> >> > >
> >> > >
> >> > >>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
> >> > >
> >> > >>>>>> indeed used in low-level utilities but is the intent the same
> >> > >
> >> > >>>>>> here?]
> >> > >
> >> > >
> >> > >>>>>>> which means removing the verbose flags, the checks, and calls
> to
> >> > >
> >> > >>>>>>> System.out in there.
> >> > >
> >> > >
> >> > >>>>>> It would be a loss of potentially useful information (e.g. for
> >> > >
> >> > >>>>>> debugging).
> >> > >
> >> > >
> >> > >>>>>> Regards,
> >> > >
> >> > >>>>>> Gilles
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Thanks!
> >> > >
> >> > >>>>>>> Bruno
> >> > >
> >> > >
> >> > >>>>>>> ________________________________
> >> > >
> >> > >>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> >> > >
> >> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>
> >> > >
> >> > >>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
> >> > >
> >> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Hi sebb,
> >> > >
> >> > >
> >> > >>>>>>>> Another aspect of debugging is ensuring that methods are
> small
> >> and
> >> > >
> >> > >
> >> > >>>>>>>> easily tested independently.
> >> > >
> >> > >>>>>>>> However this is difficult to do, and care must be taken to
> >> ensure
> >> > >
> >> > >>>> that
> >> > >
> >> > >>>>>>>> the public API is not unnecessarily extended..
> >> > >
> >> > >
> >> > >>>>>>> A very good point.
> >> > >
> >> > >
> >> > >>>>>>> The parsers in commons-imaging expose some #dump... methods
> >> > >
> >> > >>>>>>> (
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> >> > >
> >> > >>>>> ).
> >> > >
> >> > >
> >> > >>>>>>> While I can see that parsers may need to dump the data they
> are
> >> > >
> >> > >>>>>>> holding in some structured way for inspecting, reporting,
> >> > serializing,
> >> > >
> >> > >>>>>>> etc, it looks like some other classes were affected by it too.
> >> For
> >> > >
> >> > >>>>>>> example...
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> A JPEG Segment has a #dump() method
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> which gets defined in each subclass of Segment. It can be
> >> confusing
> >> > >
> >> > >>>>>>> to have a method such as #dump() in a Segment, from the point
> of
> >> > view
> >> > >
> >> > >>>>>>> of someone writing a photo editor for example. The user could
> use
> >> > that
> >> > >
> >> > >>>>>>> to pass his/her own logger's PrintWriter, which would make
> >> > removing or
> >> > >
> >> > >>>>>>> changing logging in the future in commons-imaging.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> If we keep the Debug class, and make it internal, there would
> >> still
> >> > >
> >> > >>>>>>> be these methods to take care. And there are some methods
> where
> >> > users
> >> > >
> >> > >>>>>>> can provide a PrintWriter, while others instead use System.out
> >> > >
> >> > >>>>>>> (e.g.
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> >> > >
> >> > >>>>> ).
> >> > >
> >> > >
> >> > >>>>>>> Cheers
> >> > >
> >> > >>>>>>> Bruno
> >> > >
> >> > >
> >> > >>>>>>> ________________________________
> >> > >
> >> > >>>>>>> From: sebb <se...@gmail.com>
> >> > >
> >> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno
> P.
> >> > >
> >> > >>>>>>> Kinoshita <br...@yahoo.com.br>
> >> > >
> >> > >>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
> >> > >
> >> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> >> > >
> >> > >>>>>>> <br...@yahoo.com.br.invalid> wrote:
> >> > >
> >> > >>>>>>>> Hi Jorg,
> >> > >
> >> > >
> >> > >>>>>>>> I'd be fine with that solution too. I think this one would
> cause
> >> > the
> >> > >
> >> > >>>>> smaller change to the code as is.
> >> > >
> >> > >
> >> > >>>>>>>> I believe my preference is still to remove the Debug class.
> But
> >> > >
> >> > >>>>> between logging and making Debug internal only, I'd choose
> making
> >> it
> >> > >
> >> > >>>>> internal.
> >> > >
> >> > >
> >> > >>>>>>> +1
> >> > >
> >> > >
> >> > >>>>>>> I think making it internal means it can still be dropped
> later.
> >> > >
> >> > >
> >> > >>>>>>>> Looking forward to hearing what others think about these
> >> options.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Another aspect of debugging is ensuring that methods are small
> >> and
> >> > >
> >> > >>>>>>> easily tested independently.
> >> > >
> >> > >>>>>>> However this is difficult to do, and care must be taken to
> ensure
> >> > that
> >> > >
> >> > >>>>>>> the public API is not unnecessarily extended..
> >> > >
> >> > >
> >> > >>>>>>>> Thanks
> >> > >
> >> > >>>>>>>> Bruno
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> ________________________________
> >> > >
> >> > >>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
> >> > >
> >> > >>>>>>>> To: dev@commons.apache.org
> >> > >
> >> > >>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
> >> > >
> >> > >>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Hi Bruno,
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> if it might also be helpful to our users, why not keep and
> >> provide
> >> > >
> >> > >>>> it.
> >> > >
> >> > >>>>> As
> >> > >
> >> > >
> >> > >>>>>>>> I understand it, the Debug class is a tool helping in
> >> development
> >> > to
> >> > >
> >> > >
> >> > >>>>>>>> analyze some behavior.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Nothing stops us from declaring this class internal (we might
> >> even
> >> > >
> >> > >>>> put
> >> > >
> >> > >>>>> it
> >> > >
> >> > >
> >> > >>>>>>>> into a package "internal" or "debug") that might be changed
> >> > without
> >> > >
> >> > >
> >> > >>>>>>>> further comment. Nobody may rely on it in production code,
> but
> >> > during
> >> > >
> >> > >
> >> > >>>>>>>> development it might be helpful. With such an approach we
> might
> >> > not
> >> > >
> >> > >>>>> have
> >> > >
> >> > >
> >> > >>>>>>>> a need to find a better interface to provide this
> functionality.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Just my 2¢,
> >> > >
> >> > >
> >> > >>>>>>>> Jörg
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P.
> Kinoshita:
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Hello,
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> If memory serves me well, some time ago we had a discussion
> >> > around
> >> > >
> >> > >
> >> > >>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
> >> > >
> >> > >>>> commons-imaging
> >> > >
> >> > >
> >> > >>>>>>>>> 1.0 was the Debug class.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> I finished the pull request, but Gilles raised an important
> >> > point,
> >> > >
> >> > >>>>> about
> >> > >
> >> > >
> >> > >>>>>>>>> discussing other alternatives first.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Initially I am against logging in low level libraries,
> >> especially
> >> > >
> >> > >
> >> > >>>>>>>>> commons components. But some time ago I had to debug TIFF
> >> issues
> >> > in
> >> > >
> >> > >
> >> > >>>>>>>>> commons-imaging, and having the dump methods was a
> tremendous
> >> > help.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> The issue is that some imaging algorithms/processing have a
> lot
> >> > of
> >> > >
> >> > >
> >> > >>>>>>>>> variables that can be altered. And keeping an eye on all of
> >> them
> >> > in
> >> > >
> >> > >>>>> the
> >> > >
> >> > >
> >> > >>>>>>>>> debugger can be quite hard - though not impossible.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> So all in all, now I am more confident to proceed without
> the
> >> > Debug
> >> > >
> >> > >
> >> > >>>>>>>>> class. But some users could have a hard time investigating
> >> > possible
> >> > >
> >> > >
> >> > >>>>>>>>> issues in the library without seeing what's going on within
> the
> >> > >
> >> > >>>>> library.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> IMO, that could be solved with the logging/dump features...
> or
> >> > >
> >> > >>>>> through a
> >> > >
> >> > >
> >> > >>>>>>>>> better design, especially around exception
> handling/throwing.
> >> The
> >> > >
> >> > >>>>> latter
> >> > >
> >> > >
> >> > >>>>>>>>> is my preferred approach. Instead of logging, I prefer -
> >> whenever
> >> > >
> >> > >
> >> > >>>>>>>>> possible - that low level libraries throw exceptions and
> let me
> >> > >
> >> > >>>> handle
> >> > >
> >> > >
> >> > >>>>>>>>> the logging.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and
> +0
> >> to
> >> > a
> >> > >
> >> > >
> >> > >>>>>>>>> logging added to commons-imaging.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Bruno
> >> > >
> >> > >
> >> > >
> >> > >>>>>>
> >> > ---------------------------------------------------------------------
> >> > >
> >> > >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >>>>>> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>> --
> >> > >
> >> > >>> Matt Sicker <bo...@gmail.com>
> >> > >
> >> > >
> >> > >
> >> > >>
> ---------------------------------------------------------------------
> >> > >
> >> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >>
> ---------------------------------------------------------------------
> >> > >
> >> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > >
> >> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > > For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > > For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> >
> >> > ---------------------------------------------------------------------
> >> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > For additional commands, e-mail: dev-help@commons.apache.org
> >> >
> >> >
> >>
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Matt Sicker <bo...@gmail.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi,
Remko's suggestion sounded good, and the KISS principle resounded well with this issue. I think we are using very little of what's provided by a complete logging framework, so JUL should do the trick for now. Also decided to have a crack at it before weekend.
Pull request updated, where
1) Debug is in a "internal" package now, using JUL instead of System.out
2) Debug messages go to FINE level
3) Verbose messages, and messages that were printed without any flag, are now in INFO level
4) Removed a few lines that were printing empty lines
5) Tried to keep API the same the maximum I could
If approved & merged, planning to add a section to the web site with something about the items above, and an example on how to configure it.
Would someone have time to, please, review the pull request?
https://github.com/apache/commons-imaging/pull/35/files
Backed up the old branch with a different name (just in case).
Thanks you!
Bruno
________________________________
From: Matt Sicker <bo...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Wednesday, 15 August 2018 9:20 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
Depends on how complicated your log messages are. Parameterized logging and
automatic level-checking guards aren't available, but it's workable. If you
use Java 8 at least, they added a lambda version of log messages so you
don't even need to worry about string formatting having a performance issue
when logging is disabled.
On Tue, 14 Aug 2018 at 05:56, sebb <se...@gmail.com> wrote:
> On 13 August 2018 at 20:01, Matt Sicker <bo...@gmail.com> wrote:
> > As an end user of JUL in other projects, let me warn you that you'll
> miss a
> > lot of abstractions that log4j2 and slf4j provide. :)
>
> But do they matter in this context?
>
> Or is JUL (+ adapter) good enough?
>
> > On Mon, 13 Aug 2018 at 09:50, Gary Gregory <ga...@gmail.com>
> wrote:
> >
> >> I like Remko's suggestion, a nice application of the KISS principle ;-)
> >>
> >> Gary
> >>
> >> On Mon, Aug 13, 2018, 07:58 Remko Popma <re...@gmail.com> wrote:
> >>
> >> > If it was up to me I would use JUL in this particular case to keep the
> >> > library free of dependencies. JUL is reasonable since performance is
> not
> >> an
> >> > issue.
> >> >
> >> > Users that use a logging framework can redirect the JUL logging into
> >> their
> >> > log file with the JUL adapter of their logging library.
> >> >
> >> > But that’s just me.
> >> >
> >> > Remko
> >> >
> >> > (Shameless plug) Every java main() method deserves
> http://picocli.info
> >> >
> >> > > On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <
> >> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> >> > >
> >> > > I was thinking more about using that as an argument for using a
> logging
> >> > framework, but I think you are right. Probably slf4j/commons-logging +
> >> some
> >> > default binding, then allowing users to change the implementation.
> >> > >
> >> > > Perhaps slf4j + log4j?
> >> > >
> >> > >
> >> > > Bruno
> >> > >
> >> > > ________________________________
> >> > > From: Remko Popma <re...@gmail.com>
> >> > > To: Commons Developers List <de...@commons.apache.org>
> >> > > Sent: Monday, 13 August 2018 11:55 PM
> >> > > Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > > For new projects I would really avoid using Commons Logging. Ceki
> had a
> >> > point when he created SLF4J.
> >> > >
> >> > >
> >> > > The projects you mentioned that have a dependency on Commons Logging
> >> > were started before SLF4J (and perhaps JUL) were created, I believe.
> >> > >
> >> > >
> >> > >
> >> > > (Shameless plug) Every java main() method deserves
> http://picocli.info
> >> > >
> >> > >
> >> > >>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <
> >> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> >> > >
> >> > >> Right now that's where I am standing too. If adding a dependency to
> >> > log4j is a no-no, then I'd probably check if jul would be OK, or
> >> otherwise
> >> > maybe import just Log4J's LowLevelLogUtil into the project would work?
> >> > >
> >> > >
> >> > >
> >> > >> Commons DBCP, Commons Configuration, Commons Beanutils, Commons
> JEXL,
> >> > and Commons Validator. All of these have a compile dependency to
> Commons
> >> > Logging. So it wouldn't be creating a new precedent.
> >> > >
> >> > >
> >> > >
> >> > >> Commons Pool and Commons Compress have some optional dependencies,
> but
> >> > none for logging... maybe an optional dependency, with disabling the
> >> > logging by default **could** work?
> >> > >
> >> > >
> >> > >
> >> > >> Cheers
> >> > >
> >> > >> Bruno
> >> > >
> >> > >
> >> > >
> >> > >> ________________________________
> >> > >
> >> > >> From: Remko Popma <re...@gmail.com>
> >> > >
> >> > >> To: Commons Developers List <de...@commons.apache.org>
> >> > >
> >> > >> Sent: Monday, 13 August 2018 9:50 AM
> >> > >
> >> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >> If you want to avoid a dependency I would not create a custom
> logging
> >> > abstraction but just use JUL. Most logging libraries have JUL
> adapters so
> >> > clients can do the bridging on their side.
> >> > >
> >> > >
> >> > >> (Shameless plug) Every java main() method deserves
> >> http://picocli.info
> >> > >
> >> > >
> >> > >>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
> >> > >
> >> > >
> >> > >>> What I've seen done when trying to avoid a logging API dependency
> is
> >> to
> >> > >
> >> > >>> create a minimal logging API purely for framework use. This can
> have
> >> a
> >> > >
> >> > >>> default System.err style implementation, but the idea is to make
> it
> >> > easy
> >> > >
> >> > >>> (and performant hopefully) to bridge into the end user's choice of
> >> > >
> >> > >>> framework and configuration without actually requiring a real
> logging
> >> > >
> >> > >>> framework (at least until you want to use it in production).
> While it
> >> > seems
> >> > >
> >> > >>> overkill, the problem is that neither JUL nor System.err are
> >> > sufficient for
> >> > >
> >> > >>> logging. Even a simple API like Android's logging API can be good
> >> > enough to
> >> > >
> >> > >>> abstract it in a small library.
> >> > >
> >> > >
> >> > >>> For a look at the very simplest route, you can see how Log4j2
> handles
> >> > >
> >> > >>> logging before any logging classes have been initialized. It's
> >> > basically a
> >> > >
> >> > >>> configurable wrapper around System.err:
> >> > >
> >> > >>>
> >> >
> >>
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
> >> > >
> >> > >
> >> > >
> >> > >>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <
> garydgregory@gmail.com>
> >> > wrote:
> >> > >
> >> > >
> >> > >>>> You could also log to a pluggable print stream which could be sys
> >> err
> >> > by
> >> > >
> >> > >>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as
> >> well
> >> > :-)
> >> > >
> >> > >
> >> > >>>> Gary
> >> > >
> >> > >
> >> > >>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
> >> > wrote:
> >> > >
> >> > >
> >> > >>>>> There’s a couple of considerations about doing logging in a
> >> library,
> >> > but
> >> > >
> >> > >>>>> I’ll just mention a few:
> >> > >
> >> > >
> >> > >>>>> * dependencies
> >> > >
> >> > >>>>> * performance
> >> > >
> >> > >>>>> * ease of use
> >> > >
> >> > >
> >> > >>>>> * Dependencies*
> >> > >
> >> > >>>>> Will the library be less attractive to users if it requires an
> >> > external
> >> > >
> >> > >>>>> dependency? Then don’t introduce one (so: use system err or
> JUL).
> >> On
> >> > the
> >> > >
> >> > >>>>> other hand, if the vast majority of usages is in a context with
> >> many
> >> > >
> >> > >>>> other
> >> > >
> >> > >>>>> external libraries (like in a web container) you have more
> freedom.
> >> > >
> >> > >
> >> > >>>>> *Performance*
> >> > >
> >> > >>>>> Please take a look at the log4j 2 performance page (
> >> > >
> >> > >>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs
> ).
> >> > >
> >> > >>>> Console
> >> > >
> >> > >>>>> logging is 50x (yes fifty times) slower than file logging.
> >> > >
> >> > >>>>> That’s a strong argument against system err logging. I’m not a
> fan
> >> of
> >> > >
> >> > >>>> JUL,
> >> > >
> >> > >>>>> but if you need to avoid dependencies you’re better off using
> JUL,
> >> > that’s
> >> > >
> >> > >>>>> only 5x slower than log4j. Also depends on how much logging you
> >> > expect to
> >> > >
> >> > >>>>> do in the worst case.
> >> > >
> >> > >
> >> > >>>>> *Ease of use*
> >> > >
> >> > >>>>> I’m biased and would say that Log4j 2 has the nicest and richest
> >> API.
> >> > >
> >> > >>>>> Console logging (System.err.printf) probably has the poorest
> API.
> >> > Other
> >> > >
> >> > >>>>> libraries sit in the middle.
> >> > >
> >> > >
> >> > >>>>> *Final note*
> >> > >
> >> > >>>>> I would never log to System out, always use system err instead.
> >> This
> >> > >
> >> > >>>>> allows programs using your library to pipe output to other
> programs
> >> > >
> >> > >>>> without
> >> > >
> >> > >>>>> their output getting mixed with your library’s diagnostic
> output.
> >> > >
> >> > >
> >> > >>>>> Hope this helps,
> >> > >
> >> > >
> >> > >>>>> Remko
> >> > >
> >> > >
> >> > >>>>> (Shameless plug) Every java main() method deserves
> >> > http://picocli.info
> >> > >
> >> > >
> >> > >>>>>> On Aug 12, 2018, at 21:21, Gilles <
> gilles@harfang.homelinux.org>
> >> > >
> >> > >>>> wrote:
> >> > >
> >> > >
> >> > >>>>>> Hello Bruno.
> >> > >
> >> > >
> >> > >>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita
> >> wrote:
> >> > >
> >> > >>>>>>> Hi all,
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> I commented on IMAGING-154, but copying the last comment here
> as
> >> it
> >> > >
> >> > >>>>>>> contains the approach I would like to follow to fix the last
> >> > change in
> >> > >
> >> > >>>>>>> the project blocking
> >> > >
> >> > >>>>>>> a 1.0 release:
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> ---
> >> > >
> >> > >
> >> > >>>>>>> So went ahead to re-design the Debug class, in a way users
> could
> >> > >
> >> > >>>>>>> still enable/disable debugging, and also use a PrintStream so
> >> that
> >> > >
> >> > >>>>>>> other thing rather than System.out could be used.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Then, realized removing System.out was the natural next step.
> But
> >> > >
> >> > >>>>>>> alas, the library uses System.out for debugging, but
> sometimes it
> >> > uses
> >> > >
> >> > >>>>>>> it for writing to System.out in a "verbose mode". What is more
> >> > >
> >> > >>>>>>> complicated, is that sometimes classes methods like
> `toString()`
> >> > are
> >> > >
> >> > >>>>>>> calling debug methods that receive a PrintStream already.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> So I spent some more time quickly comparing what other
> libraries
> >> > I've
> >> > >
> >> > >>>>>>> seen being used / or used for image processing:
> >> > >
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> >> > >
> >> > >>>>> .
> >> > >
> >> > >>>>>>> Turns out only very low level libraries, such as the JNI
> bridge
> >> for
> >> > >
> >> > >>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
> >> > >
> >> > >>>>>>> Exception's.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> All other libraries have one way or another of logging. Be it
> >> with
> >> > >
> >> > >>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> My preferred compromise for this ticket was to keep Debug,
> making
> >> > >
> >> > >>>>>>> System.out possible but optional, and mark the class internal
> >> only.
> >> > >
> >> > >>>>>>> Now my preferred solution is to keep the Debug internal, but
> add
> >> a
> >> > >
> >> > >>>>>>> logger to it. And then also add logging to replace where
> >> > System.out is
> >> > >
> >> > >>>>>>> used for the "verbose" mode.
> >> > >
> >> > >>>>>>> ---
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Any thoughts? Objections? If none, I will try to work on this
> >> issue
> >> > >
> >> > >>>>>>> next weekend, making the Debug class internal only, and
> replacing
> >> > >
> >> > >>>>>>> System.out by a logging utility. After that, we should be
> good to
> >> > >
> >> > >>>>>>> start preparing the vote for 1.0.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> * I know it's hard to get a consensus on having logging in
> >> Commons
> >> > >
> >> > >>>>>>> components, as we have normally low level libraries, where
> using
> >> > >
> >> > >>>>>>> logging is not always practical.
> >> > >
> >> > >
> >> > >>>>>> There are Log4j2 experts reading here. It would be interesting
> >> > >
> >> > >>>>>> to hear them about what is practical or not. There are several
> >> > >
> >> > >>>>>> aspects to "practical": simplicity, flexibility, compatibility,
> >> > >
> >> > >>>>>> performance, ...
> >> > >
> >> > >>>>>> How does Log4j2 fare in these areas?
> >> > >
> >> > >>>>>> Is there a known (through experience) limit in where it should
> >> > >
> >> > >>>>>> be used?
> >> > >
> >> > >
> >> > >>>>>>> But I would now argue that Java own
> >> > >
> >> > >>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
> >> > Commons
> >> > >
> >> > >>>>>>> Imaging are located at a higher level, some times even using
> it
> >> for
> >> > >
> >> > >>>>>>> basic image handling/parsing/reading.
> >> > >
> >> > >
> >> > >>>>>> As with many discussions on this list, conflicting arguments
> occur
> >> > >
> >> > >>>>>> because people lack common (!) definitions.
> >> > >
> >> > >>>>>> So one goes: "You cannot do <something> in a low-level
> component"
> >> > >
> >> > >>>>>> but does not define "low-level"...
> >> > >
> >> > >
> >> > >>>>>>> * Feel free to cast a counter-argument for it, but please
> think
> >> > >
> >> > >>>>>>> whether you'd still be -0, +0 for this change. We have delayed
> >> 1.0
> >> > for
> >> > >
> >> > >>>>>>> a while, so if you have a strong opinion on not adding a
> logger,
> >> > >
> >> > >>>>>>> please provide an alternative for IMAGING-154.
> >> > >
> >> > >
> >> > >>>>>>> Otherwise we may fail
> >> > >
> >> > >>>>>>> to prepare a 1.0 release yet again, and then somebody else may
> >> > have to
> >> > >
> >> > >>>>>>> work on it in a few months/years...
> >> > >
> >> > >
> >> > >>>>>> We are there because the project is too rigid about itself as
> >> > >
> >> > >>>>>> a whole (cf. for example the [RNG] thread about BC).
> >> > >
> >> > >>>>>> IMHO, it's not the always least common denominator that is the
> >> > >
> >> > >>>>>> best decision...
> >> > >
> >> > >>>>>> As you noticed, components most easily stall in their
> development
> >> > >
> >> > >>>>>> for lack of proper review, or risk acceptance (i.e. assume that
> >> > >
> >> > >>>>>> those who are closer to the code (at a given time) probably
> know
> >> > >
> >> > >>>>>> best... :-/
> >> > >
> >> > >
> >> > >>>>>> My opinion is that we can take the risk to introduce logging,
> and
> >> > >
> >> > >>>>>> if people complain somehow, take it back later.
> >> > >
> >> > >
> >> > >>>>>>> one possible compromise for this,
> >> > >
> >> > >>>>>>> might be i) make Debug internal,
> >> > >
> >> > >
> >> > >>>>>> +1
> >> > >
> >> > >
> >> > >>>>>> [Hmm... Does "internal" mean that minor release can break BC
> >> > >
> >> > >>>>>> on such a class?]
> >> > >
> >> > >
> >> > >>>>>>> ii) remove all System.out calls,
> >> > >
> >> > >
> >> > >>>>>> +1 or
> >> > >
> >> > >>>>>> -1
> >> > >
> >> > >
> >> > >>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
> >> > >
> >> > >>>>>> indeed used in low-level utilities but is the intent the same
> >> > >
> >> > >>>>>> here?]
> >> > >
> >> > >
> >> > >>>>>>> which means removing the verbose flags, the checks, and calls
> to
> >> > >
> >> > >>>>>>> System.out in there.
> >> > >
> >> > >
> >> > >>>>>> It would be a loss of potentially useful information (e.g. for
> >> > >
> >> > >>>>>> debugging).
> >> > >
> >> > >
> >> > >>>>>> Regards,
> >> > >
> >> > >>>>>> Gilles
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Thanks!
> >> > >
> >> > >>>>>>> Bruno
> >> > >
> >> > >
> >> > >>>>>>> ________________________________
> >> > >
> >> > >>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> >> > >
> >> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>
> >> > >
> >> > >>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
> >> > >
> >> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Hi sebb,
> >> > >
> >> > >
> >> > >>>>>>>> Another aspect of debugging is ensuring that methods are
> small
> >> and
> >> > >
> >> > >
> >> > >>>>>>>> easily tested independently.
> >> > >
> >> > >>>>>>>> However this is difficult to do, and care must be taken to
> >> ensure
> >> > >
> >> > >>>> that
> >> > >
> >> > >>>>>>>> the public API is not unnecessarily extended..
> >> > >
> >> > >
> >> > >>>>>>> A very good point.
> >> > >
> >> > >
> >> > >>>>>>> The parsers in commons-imaging expose some #dump... methods
> >> > >
> >> > >>>>>>> (
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> >> > >
> >> > >>>>> ).
> >> > >
> >> > >
> >> > >>>>>>> While I can see that parsers may need to dump the data they
> are
> >> > >
> >> > >>>>>>> holding in some structured way for inspecting, reporting,
> >> > serializing,
> >> > >
> >> > >>>>>>> etc, it looks like some other classes were affected by it too.
> >> For
> >> > >
> >> > >>>>>>> example...
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> A JPEG Segment has a #dump() method
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> which gets defined in each subclass of Segment. It can be
> >> confusing
> >> > >
> >> > >>>>>>> to have a method such as #dump() in a Segment, from the point
> of
> >> > view
> >> > >
> >> > >>>>>>> of someone writing a photo editor for example. The user could
> use
> >> > that
> >> > >
> >> > >>>>>>> to pass his/her own logger's PrintWriter, which would make
> >> > removing or
> >> > >
> >> > >>>>>>> changing logging in the future in commons-imaging.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> If we keep the Debug class, and make it internal, there would
> >> still
> >> > >
> >> > >>>>>>> be these methods to take care. And there are some methods
> where
> >> > users
> >> > >
> >> > >>>>>>> can provide a PrintWriter, while others instead use System.out
> >> > >
> >> > >>>>>>> (e.g.
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> >> > >
> >> > >>>>> ).
> >> > >
> >> > >
> >> > >>>>>>> Cheers
> >> > >
> >> > >>>>>>> Bruno
> >> > >
> >> > >
> >> > >>>>>>> ________________________________
> >> > >
> >> > >>>>>>> From: sebb <se...@gmail.com>
> >> > >
> >> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno
> P.
> >> > >
> >> > >>>>>>> Kinoshita <br...@yahoo.com.br>
> >> > >
> >> > >>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
> >> > >
> >> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> >> > >
> >> > >>>>>>> <br...@yahoo.com.br.invalid> wrote:
> >> > >
> >> > >>>>>>>> Hi Jorg,
> >> > >
> >> > >
> >> > >>>>>>>> I'd be fine with that solution too. I think this one would
> cause
> >> > the
> >> > >
> >> > >>>>> smaller change to the code as is.
> >> > >
> >> > >
> >> > >>>>>>>> I believe my preference is still to remove the Debug class.
> But
> >> > >
> >> > >>>>> between logging and making Debug internal only, I'd choose
> making
> >> it
> >> > >
> >> > >>>>> internal.
> >> > >
> >> > >
> >> > >>>>>>> +1
> >> > >
> >> > >
> >> > >>>>>>> I think making it internal means it can still be dropped
> later.
> >> > >
> >> > >
> >> > >>>>>>>> Looking forward to hearing what others think about these
> >> options.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Another aspect of debugging is ensuring that methods are small
> >> and
> >> > >
> >> > >>>>>>> easily tested independently.
> >> > >
> >> > >>>>>>> However this is difficult to do, and care must be taken to
> ensure
> >> > that
> >> > >
> >> > >>>>>>> the public API is not unnecessarily extended..
> >> > >
> >> > >
> >> > >>>>>>>> Thanks
> >> > >
> >> > >>>>>>>> Bruno
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> ________________________________
> >> > >
> >> > >>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
> >> > >
> >> > >>>>>>>> To: dev@commons.apache.org
> >> > >
> >> > >>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
> >> > >
> >> > >>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Hi Bruno,
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> if it might also be helpful to our users, why not keep and
> >> provide
> >> > >
> >> > >>>> it.
> >> > >
> >> > >>>>> As
> >> > >
> >> > >
> >> > >>>>>>>> I understand it, the Debug class is a tool helping in
> >> development
> >> > to
> >> > >
> >> > >
> >> > >>>>>>>> analyze some behavior.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Nothing stops us from declaring this class internal (we might
> >> even
> >> > >
> >> > >>>> put
> >> > >
> >> > >>>>> it
> >> > >
> >> > >
> >> > >>>>>>>> into a package "internal" or "debug") that might be changed
> >> > without
> >> > >
> >> > >
> >> > >>>>>>>> further comment. Nobody may rely on it in production code,
> but
> >> > during
> >> > >
> >> > >
> >> > >>>>>>>> development it might be helpful. With such an approach we
> might
> >> > not
> >> > >
> >> > >>>>> have
> >> > >
> >> > >
> >> > >>>>>>>> a need to find a better interface to provide this
> functionality.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Just my 2¢,
> >> > >
> >> > >
> >> > >>>>>>>> Jörg
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P.
> Kinoshita:
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Hello,
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> If memory serves me well, some time ago we had a discussion
> >> > around
> >> > >
> >> > >
> >> > >>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
> >> > >
> >> > >>>> commons-imaging
> >> > >
> >> > >
> >> > >>>>>>>>> 1.0 was the Debug class.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> I finished the pull request, but Gilles raised an important
> >> > point,
> >> > >
> >> > >>>>> about
> >> > >
> >> > >
> >> > >>>>>>>>> discussing other alternatives first.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Initially I am against logging in low level libraries,
> >> especially
> >> > >
> >> > >
> >> > >>>>>>>>> commons components. But some time ago I had to debug TIFF
> >> issues
> >> > in
> >> > >
> >> > >
> >> > >>>>>>>>> commons-imaging, and having the dump methods was a
> tremendous
> >> > help.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> The issue is that some imaging algorithms/processing have a
> lot
> >> > of
> >> > >
> >> > >
> >> > >>>>>>>>> variables that can be altered. And keeping an eye on all of
> >> them
> >> > in
> >> > >
> >> > >>>>> the
> >> > >
> >> > >
> >> > >>>>>>>>> debugger can be quite hard - though not impossible.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> So all in all, now I am more confident to proceed without
> the
> >> > Debug
> >> > >
> >> > >
> >> > >>>>>>>>> class. But some users could have a hard time investigating
> >> > possible
> >> > >
> >> > >
> >> > >>>>>>>>> issues in the library without seeing what's going on within
> the
> >> > >
> >> > >>>>> library.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> IMO, that could be solved with the logging/dump features...
> or
> >> > >
> >> > >>>>> through a
> >> > >
> >> > >
> >> > >>>>>>>>> better design, especially around exception
> handling/throwing.
> >> The
> >> > >
> >> > >>>>> latter
> >> > >
> >> > >
> >> > >>>>>>>>> is my preferred approach. Instead of logging, I prefer -
> >> whenever
> >> > >
> >> > >
> >> > >>>>>>>>> possible - that low level libraries throw exceptions and
> let me
> >> > >
> >> > >>>> handle
> >> > >
> >> > >
> >> > >>>>>>>>> the logging.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and
> +0
> >> to
> >> > a
> >> > >
> >> > >
> >> > >>>>>>>>> logging added to commons-imaging.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Bruno
> >> > >
> >> > >
> >> > >
> >> > >>>>>>
> >> > ---------------------------------------------------------------------
> >> > >
> >> > >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >>>>>> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>> --
> >> > >
> >> > >>> Matt Sicker <bo...@gmail.com>
> >> > >
> >> > >
> >> > >
> >> > >>
> ---------------------------------------------------------------------
> >> > >
> >> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >>
> ---------------------------------------------------------------------
> >> > >
> >> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > >
> >> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > > For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > > For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> >
> >> > ---------------------------------------------------------------------
> >> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > For additional commands, e-mail: dev-help@commons.apache.org
> >> >
> >> >
> >>
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Matt Sicker <bo...@gmail.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Matt Sicker <bo...@gmail.com>.
Depends on how complicated your log messages are. Parameterized logging and
automatic level-checking guards aren't available, but it's workable. If you
use Java 8 at least, they added a lambda version of log messages so you
don't even need to worry about string formatting having a performance issue
when logging is disabled.
On Tue, 14 Aug 2018 at 05:56, sebb <se...@gmail.com> wrote:
> On 13 August 2018 at 20:01, Matt Sicker <bo...@gmail.com> wrote:
> > As an end user of JUL in other projects, let me warn you that you'll
> miss a
> > lot of abstractions that log4j2 and slf4j provide. :)
>
> But do they matter in this context?
>
> Or is JUL (+ adapter) good enough?
>
> > On Mon, 13 Aug 2018 at 09:50, Gary Gregory <ga...@gmail.com>
> wrote:
> >
> >> I like Remko's suggestion, a nice application of the KISS principle ;-)
> >>
> >> Gary
> >>
> >> On Mon, Aug 13, 2018, 07:58 Remko Popma <re...@gmail.com> wrote:
> >>
> >> > If it was up to me I would use JUL in this particular case to keep the
> >> > library free of dependencies. JUL is reasonable since performance is
> not
> >> an
> >> > issue.
> >> >
> >> > Users that use a logging framework can redirect the JUL logging into
> >> their
> >> > log file with the JUL adapter of their logging library.
> >> >
> >> > But that’s just me.
> >> >
> >> > Remko
> >> >
> >> > (Shameless plug) Every java main() method deserves
> http://picocli.info
> >> >
> >> > > On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <
> >> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> >> > >
> >> > > I was thinking more about using that as an argument for using a
> logging
> >> > framework, but I think you are right. Probably slf4j/commons-logging +
> >> some
> >> > default binding, then allowing users to change the implementation.
> >> > >
> >> > > Perhaps slf4j + log4j?
> >> > >
> >> > >
> >> > > Bruno
> >> > >
> >> > > ________________________________
> >> > > From: Remko Popma <re...@gmail.com>
> >> > > To: Commons Developers List <de...@commons.apache.org>
> >> > > Sent: Monday, 13 August 2018 11:55 PM
> >> > > Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > > For new projects I would really avoid using Commons Logging. Ceki
> had a
> >> > point when he created SLF4J.
> >> > >
> >> > >
> >> > > The projects you mentioned that have a dependency on Commons Logging
> >> > were started before SLF4J (and perhaps JUL) were created, I believe.
> >> > >
> >> > >
> >> > >
> >> > > (Shameless plug) Every java main() method deserves
> http://picocli.info
> >> > >
> >> > >
> >> > >>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <
> >> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> >> > >
> >> > >> Right now that's where I am standing too. If adding a dependency to
> >> > log4j is a no-no, then I'd probably check if jul would be OK, or
> >> otherwise
> >> > maybe import just Log4J's LowLevelLogUtil into the project would work?
> >> > >
> >> > >
> >> > >
> >> > >> Commons DBCP, Commons Configuration, Commons Beanutils, Commons
> JEXL,
> >> > and Commons Validator. All of these have a compile dependency to
> Commons
> >> > Logging. So it wouldn't be creating a new precedent.
> >> > >
> >> > >
> >> > >
> >> > >> Commons Pool and Commons Compress have some optional dependencies,
> but
> >> > none for logging... maybe an optional dependency, with disabling the
> >> > logging by default **could** work?
> >> > >
> >> > >
> >> > >
> >> > >> Cheers
> >> > >
> >> > >> Bruno
> >> > >
> >> > >
> >> > >
> >> > >> ________________________________
> >> > >
> >> > >> From: Remko Popma <re...@gmail.com>
> >> > >
> >> > >> To: Commons Developers List <de...@commons.apache.org>
> >> > >
> >> > >> Sent: Monday, 13 August 2018 9:50 AM
> >> > >
> >> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >> If you want to avoid a dependency I would not create a custom
> logging
> >> > abstraction but just use JUL. Most logging libraries have JUL
> adapters so
> >> > clients can do the bridging on their side.
> >> > >
> >> > >
> >> > >> (Shameless plug) Every java main() method deserves
> >> http://picocli.info
> >> > >
> >> > >
> >> > >>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
> >> > >
> >> > >
> >> > >>> What I've seen done when trying to avoid a logging API dependency
> is
> >> to
> >> > >
> >> > >>> create a minimal logging API purely for framework use. This can
> have
> >> a
> >> > >
> >> > >>> default System.err style implementation, but the idea is to make
> it
> >> > easy
> >> > >
> >> > >>> (and performant hopefully) to bridge into the end user's choice of
> >> > >
> >> > >>> framework and configuration without actually requiring a real
> logging
> >> > >
> >> > >>> framework (at least until you want to use it in production).
> While it
> >> > seems
> >> > >
> >> > >>> overkill, the problem is that neither JUL nor System.err are
> >> > sufficient for
> >> > >
> >> > >>> logging. Even a simple API like Android's logging API can be good
> >> > enough to
> >> > >
> >> > >>> abstract it in a small library.
> >> > >
> >> > >
> >> > >>> For a look at the very simplest route, you can see how Log4j2
> handles
> >> > >
> >> > >>> logging before any logging classes have been initialized. It's
> >> > basically a
> >> > >
> >> > >>> configurable wrapper around System.err:
> >> > >
> >> > >>>
> >> >
> >>
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
> >> > >
> >> > >
> >> > >
> >> > >>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <
> garydgregory@gmail.com>
> >> > wrote:
> >> > >
> >> > >
> >> > >>>> You could also log to a pluggable print stream which could be sys
> >> err
> >> > by
> >> > >
> >> > >>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as
> >> well
> >> > :-)
> >> > >
> >> > >
> >> > >>>> Gary
> >> > >
> >> > >
> >> > >>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
> >> > wrote:
> >> > >
> >> > >
> >> > >>>>> There’s a couple of considerations about doing logging in a
> >> library,
> >> > but
> >> > >
> >> > >>>>> I’ll just mention a few:
> >> > >
> >> > >
> >> > >>>>> * dependencies
> >> > >
> >> > >>>>> * performance
> >> > >
> >> > >>>>> * ease of use
> >> > >
> >> > >
> >> > >>>>> * Dependencies*
> >> > >
> >> > >>>>> Will the library be less attractive to users if it requires an
> >> > external
> >> > >
> >> > >>>>> dependency? Then don’t introduce one (so: use system err or
> JUL).
> >> On
> >> > the
> >> > >
> >> > >>>>> other hand, if the vast majority of usages is in a context with
> >> many
> >> > >
> >> > >>>> other
> >> > >
> >> > >>>>> external libraries (like in a web container) you have more
> freedom.
> >> > >
> >> > >
> >> > >>>>> *Performance*
> >> > >
> >> > >>>>> Please take a look at the log4j 2 performance page (
> >> > >
> >> > >>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs
> ).
> >> > >
> >> > >>>> Console
> >> > >
> >> > >>>>> logging is 50x (yes fifty times) slower than file logging.
> >> > >
> >> > >>>>> That’s a strong argument against system err logging. I’m not a
> fan
> >> of
> >> > >
> >> > >>>> JUL,
> >> > >
> >> > >>>>> but if you need to avoid dependencies you’re better off using
> JUL,
> >> > that’s
> >> > >
> >> > >>>>> only 5x slower than log4j. Also depends on how much logging you
> >> > expect to
> >> > >
> >> > >>>>> do in the worst case.
> >> > >
> >> > >
> >> > >>>>> *Ease of use*
> >> > >
> >> > >>>>> I’m biased and would say that Log4j 2 has the nicest and richest
> >> API.
> >> > >
> >> > >>>>> Console logging (System.err.printf) probably has the poorest
> API.
> >> > Other
> >> > >
> >> > >>>>> libraries sit in the middle.
> >> > >
> >> > >
> >> > >>>>> *Final note*
> >> > >
> >> > >>>>> I would never log to System out, always use system err instead.
> >> This
> >> > >
> >> > >>>>> allows programs using your library to pipe output to other
> programs
> >> > >
> >> > >>>> without
> >> > >
> >> > >>>>> their output getting mixed with your library’s diagnostic
> output.
> >> > >
> >> > >
> >> > >>>>> Hope this helps,
> >> > >
> >> > >
> >> > >>>>> Remko
> >> > >
> >> > >
> >> > >>>>> (Shameless plug) Every java main() method deserves
> >> > http://picocli.info
> >> > >
> >> > >
> >> > >>>>>> On Aug 12, 2018, at 21:21, Gilles <
> gilles@harfang.homelinux.org>
> >> > >
> >> > >>>> wrote:
> >> > >
> >> > >
> >> > >>>>>> Hello Bruno.
> >> > >
> >> > >
> >> > >>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita
> >> wrote:
> >> > >
> >> > >>>>>>> Hi all,
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> I commented on IMAGING-154, but copying the last comment here
> as
> >> it
> >> > >
> >> > >>>>>>> contains the approach I would like to follow to fix the last
> >> > change in
> >> > >
> >> > >>>>>>> the project blocking
> >> > >
> >> > >>>>>>> a 1.0 release:
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> ---
> >> > >
> >> > >
> >> > >>>>>>> So went ahead to re-design the Debug class, in a way users
> could
> >> > >
> >> > >>>>>>> still enable/disable debugging, and also use a PrintStream so
> >> that
> >> > >
> >> > >>>>>>> other thing rather than System.out could be used.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Then, realized removing System.out was the natural next step.
> But
> >> > >
> >> > >>>>>>> alas, the library uses System.out for debugging, but
> sometimes it
> >> > uses
> >> > >
> >> > >>>>>>> it for writing to System.out in a "verbose mode". What is more
> >> > >
> >> > >>>>>>> complicated, is that sometimes classes methods like
> `toString()`
> >> > are
> >> > >
> >> > >>>>>>> calling debug methods that receive a PrintStream already.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> So I spent some more time quickly comparing what other
> libraries
> >> > I've
> >> > >
> >> > >>>>>>> seen being used / or used for image processing:
> >> > >
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> >> > >
> >> > >>>>> .
> >> > >
> >> > >>>>>>> Turns out only very low level libraries, such as the JNI
> bridge
> >> for
> >> > >
> >> > >>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
> >> > >
> >> > >>>>>>> Exception's.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> All other libraries have one way or another of logging. Be it
> >> with
> >> > >
> >> > >>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> My preferred compromise for this ticket was to keep Debug,
> making
> >> > >
> >> > >>>>>>> System.out possible but optional, and mark the class internal
> >> only.
> >> > >
> >> > >>>>>>> Now my preferred solution is to keep the Debug internal, but
> add
> >> a
> >> > >
> >> > >>>>>>> logger to it. And then also add logging to replace where
> >> > System.out is
> >> > >
> >> > >>>>>>> used for the "verbose" mode.
> >> > >
> >> > >>>>>>> ---
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Any thoughts? Objections? If none, I will try to work on this
> >> issue
> >> > >
> >> > >>>>>>> next weekend, making the Debug class internal only, and
> replacing
> >> > >
> >> > >>>>>>> System.out by a logging utility. After that, we should be
> good to
> >> > >
> >> > >>>>>>> start preparing the vote for 1.0.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> * I know it's hard to get a consensus on having logging in
> >> Commons
> >> > >
> >> > >>>>>>> components, as we have normally low level libraries, where
> using
> >> > >
> >> > >>>>>>> logging is not always practical.
> >> > >
> >> > >
> >> > >>>>>> There are Log4j2 experts reading here. It would be interesting
> >> > >
> >> > >>>>>> to hear them about what is practical or not. There are several
> >> > >
> >> > >>>>>> aspects to "practical": simplicity, flexibility, compatibility,
> >> > >
> >> > >>>>>> performance, ...
> >> > >
> >> > >>>>>> How does Log4j2 fare in these areas?
> >> > >
> >> > >>>>>> Is there a known (through experience) limit in where it should
> >> > >
> >> > >>>>>> be used?
> >> > >
> >> > >
> >> > >>>>>>> But I would now argue that Java own
> >> > >
> >> > >>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
> >> > Commons
> >> > >
> >> > >>>>>>> Imaging are located at a higher level, some times even using
> it
> >> for
> >> > >
> >> > >>>>>>> basic image handling/parsing/reading.
> >> > >
> >> > >
> >> > >>>>>> As with many discussions on this list, conflicting arguments
> occur
> >> > >
> >> > >>>>>> because people lack common (!) definitions.
> >> > >
> >> > >>>>>> So one goes: "You cannot do <something> in a low-level
> component"
> >> > >
> >> > >>>>>> but does not define "low-level"...
> >> > >
> >> > >
> >> > >>>>>>> * Feel free to cast a counter-argument for it, but please
> think
> >> > >
> >> > >>>>>>> whether you'd still be -0, +0 for this change. We have delayed
> >> 1.0
> >> > for
> >> > >
> >> > >>>>>>> a while, so if you have a strong opinion on not adding a
> logger,
> >> > >
> >> > >>>>>>> please provide an alternative for IMAGING-154.
> >> > >
> >> > >
> >> > >>>>>>> Otherwise we may fail
> >> > >
> >> > >>>>>>> to prepare a 1.0 release yet again, and then somebody else may
> >> > have to
> >> > >
> >> > >>>>>>> work on it in a few months/years...
> >> > >
> >> > >
> >> > >>>>>> We are there because the project is too rigid about itself as
> >> > >
> >> > >>>>>> a whole (cf. for example the [RNG] thread about BC).
> >> > >
> >> > >>>>>> IMHO, it's not the always least common denominator that is the
> >> > >
> >> > >>>>>> best decision...
> >> > >
> >> > >>>>>> As you noticed, components most easily stall in their
> development
> >> > >
> >> > >>>>>> for lack of proper review, or risk acceptance (i.e. assume that
> >> > >
> >> > >>>>>> those who are closer to the code (at a given time) probably
> know
> >> > >
> >> > >>>>>> best... :-/
> >> > >
> >> > >
> >> > >>>>>> My opinion is that we can take the risk to introduce logging,
> and
> >> > >
> >> > >>>>>> if people complain somehow, take it back later.
> >> > >
> >> > >
> >> > >>>>>>> one possible compromise for this,
> >> > >
> >> > >>>>>>> might be i) make Debug internal,
> >> > >
> >> > >
> >> > >>>>>> +1
> >> > >
> >> > >
> >> > >>>>>> [Hmm... Does "internal" mean that minor release can break BC
> >> > >
> >> > >>>>>> on such a class?]
> >> > >
> >> > >
> >> > >>>>>>> ii) remove all System.out calls,
> >> > >
> >> > >
> >> > >>>>>> +1 or
> >> > >
> >> > >>>>>> -1
> >> > >
> >> > >
> >> > >>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
> >> > >
> >> > >>>>>> indeed used in low-level utilities but is the intent the same
> >> > >
> >> > >>>>>> here?]
> >> > >
> >> > >
> >> > >>>>>>> which means removing the verbose flags, the checks, and calls
> to
> >> > >
> >> > >>>>>>> System.out in there.
> >> > >
> >> > >
> >> > >>>>>> It would be a loss of potentially useful information (e.g. for
> >> > >
> >> > >>>>>> debugging).
> >> > >
> >> > >
> >> > >>>>>> Regards,
> >> > >
> >> > >>>>>> Gilles
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Thanks!
> >> > >
> >> > >>>>>>> Bruno
> >> > >
> >> > >
> >> > >>>>>>> ________________________________
> >> > >
> >> > >>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> >> > >
> >> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>
> >> > >
> >> > >>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
> >> > >
> >> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Hi sebb,
> >> > >
> >> > >
> >> > >>>>>>>> Another aspect of debugging is ensuring that methods are
> small
> >> and
> >> > >
> >> > >
> >> > >>>>>>>> easily tested independently.
> >> > >
> >> > >>>>>>>> However this is difficult to do, and care must be taken to
> >> ensure
> >> > >
> >> > >>>> that
> >> > >
> >> > >>>>>>>> the public API is not unnecessarily extended..
> >> > >
> >> > >
> >> > >>>>>>> A very good point.
> >> > >
> >> > >
> >> > >>>>>>> The parsers in commons-imaging expose some #dump... methods
> >> > >
> >> > >>>>>>> (
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> >> > >
> >> > >>>>> ).
> >> > >
> >> > >
> >> > >>>>>>> While I can see that parsers may need to dump the data they
> are
> >> > >
> >> > >>>>>>> holding in some structured way for inspecting, reporting,
> >> > serializing,
> >> > >
> >> > >>>>>>> etc, it looks like some other classes were affected by it too.
> >> For
> >> > >
> >> > >>>>>>> example...
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> A JPEG Segment has a #dump() method
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> which gets defined in each subclass of Segment. It can be
> >> confusing
> >> > >
> >> > >>>>>>> to have a method such as #dump() in a Segment, from the point
> of
> >> > view
> >> > >
> >> > >>>>>>> of someone writing a photo editor for example. The user could
> use
> >> > that
> >> > >
> >> > >>>>>>> to pass his/her own logger's PrintWriter, which would make
> >> > removing or
> >> > >
> >> > >>>>>>> changing logging in the future in commons-imaging.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> If we keep the Debug class, and make it internal, there would
> >> still
> >> > >
> >> > >>>>>>> be these methods to take care. And there are some methods
> where
> >> > users
> >> > >
> >> > >>>>>>> can provide a PrintWriter, while others instead use System.out
> >> > >
> >> > >>>>>>> (e.g.
> >> > >
> >> > >
> >> > >>>>
> >> >
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> >> > >
> >> > >>>>> ).
> >> > >
> >> > >
> >> > >>>>>>> Cheers
> >> > >
> >> > >>>>>>> Bruno
> >> > >
> >> > >
> >> > >>>>>>> ________________________________
> >> > >
> >> > >>>>>>> From: sebb <se...@gmail.com>
> >> > >
> >> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno
> P.
> >> > >
> >> > >>>>>>> Kinoshita <br...@yahoo.com.br>
> >> > >
> >> > >>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
> >> > >
> >> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> >> > >
> >> > >>>>>>> <br...@yahoo.com.br.invalid> wrote:
> >> > >
> >> > >>>>>>>> Hi Jorg,
> >> > >
> >> > >
> >> > >>>>>>>> I'd be fine with that solution too. I think this one would
> cause
> >> > the
> >> > >
> >> > >>>>> smaller change to the code as is.
> >> > >
> >> > >
> >> > >>>>>>>> I believe my preference is still to remove the Debug class.
> But
> >> > >
> >> > >>>>> between logging and making Debug internal only, I'd choose
> making
> >> it
> >> > >
> >> > >>>>> internal.
> >> > >
> >> > >
> >> > >>>>>>> +1
> >> > >
> >> > >
> >> > >>>>>>> I think making it internal means it can still be dropped
> later.
> >> > >
> >> > >
> >> > >>>>>>>> Looking forward to hearing what others think about these
> >> options.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>> Another aspect of debugging is ensuring that methods are small
> >> and
> >> > >
> >> > >>>>>>> easily tested independently.
> >> > >
> >> > >>>>>>> However this is difficult to do, and care must be taken to
> ensure
> >> > that
> >> > >
> >> > >>>>>>> the public API is not unnecessarily extended..
> >> > >
> >> > >
> >> > >>>>>>>> Thanks
> >> > >
> >> > >>>>>>>> Bruno
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> ________________________________
> >> > >
> >> > >>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
> >> > >
> >> > >>>>>>>> To: dev@commons.apache.org
> >> > >
> >> > >>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
> >> > >
> >> > >>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Hi Bruno,
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> if it might also be helpful to our users, why not keep and
> >> provide
> >> > >
> >> > >>>> it.
> >> > >
> >> > >>>>> As
> >> > >
> >> > >
> >> > >>>>>>>> I understand it, the Debug class is a tool helping in
> >> development
> >> > to
> >> > >
> >> > >
> >> > >>>>>>>> analyze some behavior.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Nothing stops us from declaring this class internal (we might
> >> even
> >> > >
> >> > >>>> put
> >> > >
> >> > >>>>> it
> >> > >
> >> > >
> >> > >>>>>>>> into a package "internal" or "debug") that might be changed
> >> > without
> >> > >
> >> > >
> >> > >>>>>>>> further comment. Nobody may rely on it in production code,
> but
> >> > during
> >> > >
> >> > >
> >> > >>>>>>>> development it might be helpful. With such an approach we
> might
> >> > not
> >> > >
> >> > >>>>> have
> >> > >
> >> > >
> >> > >>>>>>>> a need to find a better interface to provide this
> functionality.
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Just my 2¢,
> >> > >
> >> > >
> >> > >>>>>>>> Jörg
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P.
> Kinoshita:
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Hello,
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> If memory serves me well, some time ago we had a discussion
> >> > around
> >> > >
> >> > >
> >> > >>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
> >> > >
> >> > >>>> commons-imaging
> >> > >
> >> > >
> >> > >>>>>>>>> 1.0 was the Debug class.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> I finished the pull request, but Gilles raised an important
> >> > point,
> >> > >
> >> > >>>>> about
> >> > >
> >> > >
> >> > >>>>>>>>> discussing other alternatives first.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Initially I am against logging in low level libraries,
> >> especially
> >> > >
> >> > >
> >> > >>>>>>>>> commons components. But some time ago I had to debug TIFF
> >> issues
> >> > in
> >> > >
> >> > >
> >> > >>>>>>>>> commons-imaging, and having the dump methods was a
> tremendous
> >> > help.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> The issue is that some imaging algorithms/processing have a
> lot
> >> > of
> >> > >
> >> > >
> >> > >>>>>>>>> variables that can be altered. And keeping an eye on all of
> >> them
> >> > in
> >> > >
> >> > >>>>> the
> >> > >
> >> > >
> >> > >>>>>>>>> debugger can be quite hard - though not impossible.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> So all in all, now I am more confident to proceed without
> the
> >> > Debug
> >> > >
> >> > >
> >> > >>>>>>>>> class. But some users could have a hard time investigating
> >> > possible
> >> > >
> >> > >
> >> > >>>>>>>>> issues in the library without seeing what's going on within
> the
> >> > >
> >> > >>>>> library.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> IMO, that could be solved with the logging/dump features...
> or
> >> > >
> >> > >>>>> through a
> >> > >
> >> > >
> >> > >>>>>>>>> better design, especially around exception
> handling/throwing.
> >> The
> >> > >
> >> > >>>>> latter
> >> > >
> >> > >
> >> > >>>>>>>>> is my preferred approach. Instead of logging, I prefer -
> >> whenever
> >> > >
> >> > >
> >> > >>>>>>>>> possible - that low level libraries throw exceptions and
> let me
> >> > >
> >> > >>>> handle
> >> > >
> >> > >
> >> > >>>>>>>>> the logging.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and
> +0
> >> to
> >> > a
> >> > >
> >> > >
> >> > >>>>>>>>> logging added to commons-imaging.
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>>>>>>>> Bruno
> >> > >
> >> > >
> >> > >
> >> > >>>>>>
> >> > ---------------------------------------------------------------------
> >> > >
> >> > >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >>>>>> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >
> >> > >>> --
> >> > >
> >> > >>> Matt Sicker <bo...@gmail.com>
> >> > >
> >> > >
> >> > >
> >> > >>
> ---------------------------------------------------------------------
> >> > >
> >> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >>
> ---------------------------------------------------------------------
> >> > >
> >> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > >> For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > >
> >> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > >
> >> > > For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > > For additional commands, e-mail: dev-help@commons.apache.org
> >> > >
> >> >
> >> > ---------------------------------------------------------------------
> >> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> > For additional commands, e-mail: dev-help@commons.apache.org
> >> >
> >> >
> >>
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
Matt Sicker <bo...@gmail.com>
Re: [imaging] IMAGING-154 remove Debug class
Posted by sebb <se...@gmail.com>.
On 13 August 2018 at 20:01, Matt Sicker <bo...@gmail.com> wrote:
> As an end user of JUL in other projects, let me warn you that you'll miss a
> lot of abstractions that log4j2 and slf4j provide. :)
But do they matter in this context?
Or is JUL (+ adapter) good enough?
> On Mon, 13 Aug 2018 at 09:50, Gary Gregory <ga...@gmail.com> wrote:
>
>> I like Remko's suggestion, a nice application of the KISS principle ;-)
>>
>> Gary
>>
>> On Mon, Aug 13, 2018, 07:58 Remko Popma <re...@gmail.com> wrote:
>>
>> > If it was up to me I would use JUL in this particular case to keep the
>> > library free of dependencies. JUL is reasonable since performance is not
>> an
>> > issue.
>> >
>> > Users that use a logging framework can redirect the JUL logging into
>> their
>> > log file with the JUL adapter of their logging library.
>> >
>> > But that’s just me.
>> >
>> > Remko
>> >
>> > (Shameless plug) Every java main() method deserves http://picocli.info
>> >
>> > > On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <
>> > brunodepaulak@yahoo.com.br.INVALID> wrote:
>> > >
>> > > I was thinking more about using that as an argument for using a logging
>> > framework, but I think you are right. Probably slf4j/commons-logging +
>> some
>> > default binding, then allowing users to change the implementation.
>> > >
>> > > Perhaps slf4j + log4j?
>> > >
>> > >
>> > > Bruno
>> > >
>> > > ________________________________
>> > > From: Remko Popma <re...@gmail.com>
>> > > To: Commons Developers List <de...@commons.apache.org>
>> > > Sent: Monday, 13 August 2018 11:55 PM
>> > > Subject: Re: [imaging] IMAGING-154 remove Debug class
>> > >
>> > >
>> > >
>> > > For new projects I would really avoid using Commons Logging. Ceki had a
>> > point when he created SLF4J.
>> > >
>> > >
>> > > The projects you mentioned that have a dependency on Commons Logging
>> > were started before SLF4J (and perhaps JUL) were created, I believe.
>> > >
>> > >
>> > >
>> > > (Shameless plug) Every java main() method deserves http://picocli.info
>> > >
>> > >
>> > >>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <
>> > brunodepaulak@yahoo.com.br.INVALID> wrote:
>> > >
>> > >> Right now that's where I am standing too. If adding a dependency to
>> > log4j is a no-no, then I'd probably check if jul would be OK, or
>> otherwise
>> > maybe import just Log4J's LowLevelLogUtil into the project would work?
>> > >
>> > >
>> > >
>> > >> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL,
>> > and Commons Validator. All of these have a compile dependency to Commons
>> > Logging. So it wouldn't be creating a new precedent.
>> > >
>> > >
>> > >
>> > >> Commons Pool and Commons Compress have some optional dependencies, but
>> > none for logging... maybe an optional dependency, with disabling the
>> > logging by default **could** work?
>> > >
>> > >
>> > >
>> > >> Cheers
>> > >
>> > >> Bruno
>> > >
>> > >
>> > >
>> > >> ________________________________
>> > >
>> > >> From: Remko Popma <re...@gmail.com>
>> > >
>> > >> To: Commons Developers List <de...@commons.apache.org>
>> > >
>> > >> Sent: Monday, 13 August 2018 9:50 AM
>> > >
>> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
>> > >
>> > >
>> > >
>> > >
>> > >> If you want to avoid a dependency I would not create a custom logging
>> > abstraction but just use JUL. Most logging libraries have JUL adapters so
>> > clients can do the bridging on their side.
>> > >
>> > >
>> > >> (Shameless plug) Every java main() method deserves
>> http://picocli.info
>> > >
>> > >
>> > >>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>> > >
>> > >
>> > >>> What I've seen done when trying to avoid a logging API dependency is
>> to
>> > >
>> > >>> create a minimal logging API purely for framework use. This can have
>> a
>> > >
>> > >>> default System.err style implementation, but the idea is to make it
>> > easy
>> > >
>> > >>> (and performant hopefully) to bridge into the end user's choice of
>> > >
>> > >>> framework and configuration without actually requiring a real logging
>> > >
>> > >>> framework (at least until you want to use it in production). While it
>> > seems
>> > >
>> > >>> overkill, the problem is that neither JUL nor System.err are
>> > sufficient for
>> > >
>> > >>> logging. Even a simple API like Android's logging API can be good
>> > enough to
>> > >
>> > >>> abstract it in a small library.
>> > >
>> > >
>> > >>> For a look at the very simplest route, you can see how Log4j2 handles
>> > >
>> > >>> logging before any logging classes have been initialized. It's
>> > basically a
>> > >
>> > >>> configurable wrapper around System.err:
>> > >
>> > >>>
>> >
>> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>> > >
>> > >
>> > >
>> > >>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com>
>> > wrote:
>> > >
>> > >
>> > >>>> You could also log to a pluggable print stream which could be sys
>> err
>> > by
>> > >
>> > >>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as
>> well
>> > :-)
>> > >
>> > >
>> > >>>> Gary
>> > >
>> > >
>> > >>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
>> > wrote:
>> > >
>> > >
>> > >>>>> There’s a couple of considerations about doing logging in a
>> library,
>> > but
>> > >
>> > >>>>> I’ll just mention a few:
>> > >
>> > >
>> > >>>>> * dependencies
>> > >
>> > >>>>> * performance
>> > >
>> > >>>>> * ease of use
>> > >
>> > >
>> > >>>>> * Dependencies*
>> > >
>> > >>>>> Will the library be less attractive to users if it requires an
>> > external
>> > >
>> > >>>>> dependency? Then don’t introduce one (so: use system err or JUL).
>> On
>> > the
>> > >
>> > >>>>> other hand, if the vast majority of usages is in a context with
>> many
>> > >
>> > >>>> other
>> > >
>> > >>>>> external libraries (like in a web container) you have more freedom.
>> > >
>> > >
>> > >>>>> *Performance*
>> > >
>> > >>>>> Please take a look at the log4j 2 performance page (
>> > >
>> > >>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>> > >
>> > >>>> Console
>> > >
>> > >>>>> logging is 50x (yes fifty times) slower than file logging.
>> > >
>> > >>>>> That’s a strong argument against system err logging. I’m not a fan
>> of
>> > >
>> > >>>> JUL,
>> > >
>> > >>>>> but if you need to avoid dependencies you’re better off using JUL,
>> > that’s
>> > >
>> > >>>>> only 5x slower than log4j. Also depends on how much logging you
>> > expect to
>> > >
>> > >>>>> do in the worst case.
>> > >
>> > >
>> > >>>>> *Ease of use*
>> > >
>> > >>>>> I’m biased and would say that Log4j 2 has the nicest and richest
>> API.
>> > >
>> > >>>>> Console logging (System.err.printf) probably has the poorest API.
>> > Other
>> > >
>> > >>>>> libraries sit in the middle.
>> > >
>> > >
>> > >>>>> *Final note*
>> > >
>> > >>>>> I would never log to System out, always use system err instead.
>> This
>> > >
>> > >>>>> allows programs using your library to pipe output to other programs
>> > >
>> > >>>> without
>> > >
>> > >>>>> their output getting mixed with your library’s diagnostic output.
>> > >
>> > >
>> > >>>>> Hope this helps,
>> > >
>> > >
>> > >>>>> Remko
>> > >
>> > >
>> > >>>>> (Shameless plug) Every java main() method deserves
>> > http://picocli.info
>> > >
>> > >
>> > >>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>> > >
>> > >>>> wrote:
>> > >
>> > >
>> > >>>>>> Hello Bruno.
>> > >
>> > >
>> > >>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita
>> wrote:
>> > >
>> > >>>>>>> Hi all,
>> > >
>> > >
>> > >
>> > >>>>>>> I commented on IMAGING-154, but copying the last comment here as
>> it
>> > >
>> > >>>>>>> contains the approach I would like to follow to fix the last
>> > change in
>> > >
>> > >>>>>>> the project blocking
>> > >
>> > >>>>>>> a 1.0 release:
>> > >
>> > >
>> > >
>> > >>>>>>> ---
>> > >
>> > >
>> > >>>>>>> So went ahead to re-design the Debug class, in a way users could
>> > >
>> > >>>>>>> still enable/disable debugging, and also use a PrintStream so
>> that
>> > >
>> > >>>>>>> other thing rather than System.out could be used.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> Then, realized removing System.out was the natural next step. But
>> > >
>> > >>>>>>> alas, the library uses System.out for debugging, but sometimes it
>> > uses
>> > >
>> > >>>>>>> it for writing to System.out in a "verbose mode". What is more
>> > >
>> > >>>>>>> complicated, is that sometimes classes methods like `toString()`
>> > are
>> > >
>> > >>>>>>> calling debug methods that receive a PrintStream already.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> So I spent some more time quickly comparing what other libraries
>> > I've
>> > >
>> > >>>>>>> seen being used / or used for image processing:
>> > >
>> > >
>> > >
>> > >>>>
>> >
>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>> > >
>> > >>>>> .
>> > >
>> > >>>>>>> Turns out only very low level libraries, such as the JNI bridge
>> for
>> > >
>> > >>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>> > >
>> > >>>>>>> Exception's.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> All other libraries have one way or another of logging. Be it
>> with
>> > >
>> > >>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> My preferred compromise for this ticket was to keep Debug, making
>> > >
>> > >>>>>>> System.out possible but optional, and mark the class internal
>> only.
>> > >
>> > >>>>>>> Now my preferred solution is to keep the Debug internal, but add
>> a
>> > >
>> > >>>>>>> logger to it. And then also add logging to replace where
>> > System.out is
>> > >
>> > >>>>>>> used for the "verbose" mode.
>> > >
>> > >>>>>>> ---
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> Any thoughts? Objections? If none, I will try to work on this
>> issue
>> > >
>> > >>>>>>> next weekend, making the Debug class internal only, and replacing
>> > >
>> > >>>>>>> System.out by a logging utility. After that, we should be good to
>> > >
>> > >>>>>>> start preparing the vote for 1.0.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> * I know it's hard to get a consensus on having logging in
>> Commons
>> > >
>> > >>>>>>> components, as we have normally low level libraries, where using
>> > >
>> > >>>>>>> logging is not always practical.
>> > >
>> > >
>> > >>>>>> There are Log4j2 experts reading here. It would be interesting
>> > >
>> > >>>>>> to hear them about what is practical or not. There are several
>> > >
>> > >>>>>> aspects to "practical": simplicity, flexibility, compatibility,
>> > >
>> > >>>>>> performance, ...
>> > >
>> > >>>>>> How does Log4j2 fare in these areas?
>> > >
>> > >>>>>> Is there a known (through experience) limit in where it should
>> > >
>> > >>>>>> be used?
>> > >
>> > >
>> > >>>>>>> But I would now argue that Java own
>> > >
>> > >>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
>> > Commons
>> > >
>> > >>>>>>> Imaging are located at a higher level, some times even using it
>> for
>> > >
>> > >>>>>>> basic image handling/parsing/reading.
>> > >
>> > >
>> > >>>>>> As with many discussions on this list, conflicting arguments occur
>> > >
>> > >>>>>> because people lack common (!) definitions.
>> > >
>> > >>>>>> So one goes: "You cannot do <something> in a low-level component"
>> > >
>> > >>>>>> but does not define "low-level"...
>> > >
>> > >
>> > >>>>>>> * Feel free to cast a counter-argument for it, but please think
>> > >
>> > >>>>>>> whether you'd still be -0, +0 for this change. We have delayed
>> 1.0
>> > for
>> > >
>> > >>>>>>> a while, so if you have a strong opinion on not adding a logger,
>> > >
>> > >>>>>>> please provide an alternative for IMAGING-154.
>> > >
>> > >
>> > >>>>>>> Otherwise we may fail
>> > >
>> > >>>>>>> to prepare a 1.0 release yet again, and then somebody else may
>> > have to
>> > >
>> > >>>>>>> work on it in a few months/years...
>> > >
>> > >
>> > >>>>>> We are there because the project is too rigid about itself as
>> > >
>> > >>>>>> a whole (cf. for example the [RNG] thread about BC).
>> > >
>> > >>>>>> IMHO, it's not the always least common denominator that is the
>> > >
>> > >>>>>> best decision...
>> > >
>> > >>>>>> As you noticed, components most easily stall in their development
>> > >
>> > >>>>>> for lack of proper review, or risk acceptance (i.e. assume that
>> > >
>> > >>>>>> those who are closer to the code (at a given time) probably know
>> > >
>> > >>>>>> best... :-/
>> > >
>> > >
>> > >>>>>> My opinion is that we can take the risk to introduce logging, and
>> > >
>> > >>>>>> if people complain somehow, take it back later.
>> > >
>> > >
>> > >>>>>>> one possible compromise for this,
>> > >
>> > >>>>>>> might be i) make Debug internal,
>> > >
>> > >
>> > >>>>>> +1
>> > >
>> > >
>> > >>>>>> [Hmm... Does "internal" mean that minor release can break BC
>> > >
>> > >>>>>> on such a class?]
>> > >
>> > >
>> > >>>>>>> ii) remove all System.out calls,
>> > >
>> > >
>> > >>>>>> +1 or
>> > >
>> > >>>>>> -1
>> > >
>> > >
>> > >>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>> > >
>> > >>>>>> indeed used in low-level utilities but is the intent the same
>> > >
>> > >>>>>> here?]
>> > >
>> > >
>> > >>>>>>> which means removing the verbose flags, the checks, and calls to
>> > >
>> > >>>>>>> System.out in there.
>> > >
>> > >
>> > >>>>>> It would be a loss of potentially useful information (e.g. for
>> > >
>> > >>>>>> debugging).
>> > >
>> > >
>> > >>>>>> Regards,
>> > >
>> > >>>>>> Gilles
>> > >
>> > >
>> > >
>> > >>>>>>> Thanks!
>> > >
>> > >>>>>>> Bruno
>> > >
>> > >
>> > >>>>>>> ________________________________
>> > >
>> > >>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>> > >
>> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>
>> > >
>> > >>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>> > >
>> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> Hi sebb,
>> > >
>> > >
>> > >>>>>>>> Another aspect of debugging is ensuring that methods are small
>> and
>> > >
>> > >
>> > >>>>>>>> easily tested independently.
>> > >
>> > >>>>>>>> However this is difficult to do, and care must be taken to
>> ensure
>> > >
>> > >>>> that
>> > >
>> > >>>>>>>> the public API is not unnecessarily extended..
>> > >
>> > >
>> > >>>>>>> A very good point.
>> > >
>> > >
>> > >>>>>>> The parsers in commons-imaging expose some #dump... methods
>> > >
>> > >>>>>>> (
>> > >
>> > >
>> > >>>>
>> >
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>> > >
>> > >>>>> ).
>> > >
>> > >
>> > >>>>>>> While I can see that parsers may need to dump the data they are
>> > >
>> > >>>>>>> holding in some structured way for inspecting, reporting,
>> > serializing,
>> > >
>> > >>>>>>> etc, it looks like some other classes were affected by it too.
>> For
>> > >
>> > >>>>>>> example...
>> > >
>> > >
>> > >
>> > >>>>>>> A JPEG Segment has a #dump() method
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >>>>
>> >
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>> > >
>> > >
>> > >
>> > >>>>>>> which gets defined in each subclass of Segment. It can be
>> confusing
>> > >
>> > >>>>>>> to have a method such as #dump() in a Segment, from the point of
>> > view
>> > >
>> > >>>>>>> of someone writing a photo editor for example. The user could use
>> > that
>> > >
>> > >>>>>>> to pass his/her own logger's PrintWriter, which would make
>> > removing or
>> > >
>> > >>>>>>> changing logging in the future in commons-imaging.
>> > >
>> > >
>> > >
>> > >>>>>>> If we keep the Debug class, and make it internal, there would
>> still
>> > >
>> > >>>>>>> be these methods to take care. And there are some methods where
>> > users
>> > >
>> > >>>>>>> can provide a PrintWriter, while others instead use System.out
>> > >
>> > >>>>>>> (e.g.
>> > >
>> > >
>> > >>>>
>> >
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>> > >
>> > >>>>> ).
>> > >
>> > >
>> > >>>>>>> Cheers
>> > >
>> > >>>>>>> Bruno
>> > >
>> > >
>> > >>>>>>> ________________________________
>> > >
>> > >>>>>>> From: sebb <se...@gmail.com>
>> > >
>> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>> > >
>> > >>>>>>> Kinoshita <br...@yahoo.com.br>
>> > >
>> > >>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>> > >
>> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>> > >
>> > >>>>>>> <br...@yahoo.com.br.invalid> wrote:
>> > >
>> > >>>>>>>> Hi Jorg,
>> > >
>> > >
>> > >>>>>>>> I'd be fine with that solution too. I think this one would cause
>> > the
>> > >
>> > >>>>> smaller change to the code as is.
>> > >
>> > >
>> > >>>>>>>> I believe my preference is still to remove the Debug class. But
>> > >
>> > >>>>> between logging and making Debug internal only, I'd choose making
>> it
>> > >
>> > >>>>> internal.
>> > >
>> > >
>> > >>>>>>> +1
>> > >
>> > >
>> > >>>>>>> I think making it internal means it can still be dropped later.
>> > >
>> > >
>> > >>>>>>>> Looking forward to hearing what others think about these
>> options.
>> > >
>> > >
>> > >
>> > >>>>>>> Another aspect of debugging is ensuring that methods are small
>> and
>> > >
>> > >>>>>>> easily tested independently.
>> > >
>> > >>>>>>> However this is difficult to do, and care must be taken to ensure
>> > that
>> > >
>> > >>>>>>> the public API is not unnecessarily extended..
>> > >
>> > >
>> > >>>>>>>> Thanks
>> > >
>> > >>>>>>>> Bruno
>> > >
>> > >
>> > >
>> > >>>>>>>> ________________________________
>> > >
>> > >>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>> > >
>> > >>>>>>>> To: dev@commons.apache.org
>> > >
>> > >>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>> > >
>> > >>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>> Hi Bruno,
>> > >
>> > >
>> > >
>> > >>>>>>>> if it might also be helpful to our users, why not keep and
>> provide
>> > >
>> > >>>> it.
>> > >
>> > >>>>> As
>> > >
>> > >
>> > >>>>>>>> I understand it, the Debug class is a tool helping in
>> development
>> > to
>> > >
>> > >
>> > >>>>>>>> analyze some behavior.
>> > >
>> > >
>> > >
>> > >>>>>>>> Nothing stops us from declaring this class internal (we might
>> even
>> > >
>> > >>>> put
>> > >
>> > >>>>> it
>> > >
>> > >
>> > >>>>>>>> into a package "internal" or "debug") that might be changed
>> > without
>> > >
>> > >
>> > >>>>>>>> further comment. Nobody may rely on it in production code, but
>> > during
>> > >
>> > >
>> > >>>>>>>> development it might be helpful. With such an approach we might
>> > not
>> > >
>> > >>>>> have
>> > >
>> > >
>> > >>>>>>>> a need to find a better interface to provide this functionality.
>> > >
>> > >
>> > >
>> > >>>>>>>> Just my 2¢,
>> > >
>> > >
>> > >>>>>>>> Jörg
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>> > >
>> > >
>> > >
>> > >>>>>>>>> Hello,
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> If memory serves me well, some time ago we had a discussion
>> > around
>> > >
>> > >
>> > >>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>> > >
>> > >>>> commons-imaging
>> > >
>> > >
>> > >>>>>>>>> 1.0 was the Debug class.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> I finished the pull request, but Gilles raised an important
>> > point,
>> > >
>> > >>>>> about
>> > >
>> > >
>> > >>>>>>>>> discussing other alternatives first.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> Initially I am against logging in low level libraries,
>> especially
>> > >
>> > >
>> > >>>>>>>>> commons components. But some time ago I had to debug TIFF
>> issues
>> > in
>> > >
>> > >
>> > >>>>>>>>> commons-imaging, and having the dump methods was a tremendous
>> > help.
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> The issue is that some imaging algorithms/processing have a lot
>> > of
>> > >
>> > >
>> > >>>>>>>>> variables that can be altered. And keeping an eye on all of
>> them
>> > in
>> > >
>> > >>>>> the
>> > >
>> > >
>> > >>>>>>>>> debugger can be quite hard - though not impossible.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> So all in all, now I am more confident to proceed without the
>> > Debug
>> > >
>> > >
>> > >>>>>>>>> class. But some users could have a hard time investigating
>> > possible
>> > >
>> > >
>> > >>>>>>>>> issues in the library without seeing what's going on within the
>> > >
>> > >>>>> library.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> IMO, that could be solved with the logging/dump features... or
>> > >
>> > >>>>> through a
>> > >
>> > >
>> > >>>>>>>>> better design, especially around exception handling/throwing.
>> The
>> > >
>> > >>>>> latter
>> > >
>> > >
>> > >>>>>>>>> is my preferred approach. Instead of logging, I prefer -
>> whenever
>> > >
>> > >
>> > >>>>>>>>> possible - that low level libraries throw exceptions and let me
>> > >
>> > >>>> handle
>> > >
>> > >
>> > >>>>>>>>> the logging.
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0
>> to
>> > a
>> > >
>> > >
>> > >>>>>>>>> logging added to commons-imaging.
>> > >
>> > >
>> > >
>> > >
>> > >>>>>>>>> Bruno
>> > >
>> > >
>> > >
>> > >>>>>>
>> > ---------------------------------------------------------------------
>> > >
>> > >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > >
>> > >>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >
>> > >>> --
>> > >
>> > >>> Matt Sicker <bo...@gmail.com>
>> > >
>> > >
>> > >
>> > >> ---------------------------------------------------------------------
>> > >
>> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > >
>> > >> For additional commands, e-mail: dev-help@commons.apache.org
>> > >
>> > >
>> > >> ---------------------------------------------------------------------
>> > >
>> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > >
>> > >> For additional commands, e-mail: dev-help@commons.apache.org
>> > >
>> > >
>> > >
>> > > ---------------------------------------------------------------------
>> > >
>> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > >
>> > > For additional commands, e-mail: dev-help@commons.apache.org
>> > >
>> > > ---------------------------------------------------------------------
>> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > > For additional commands, e-mail: dev-help@commons.apache.org
>> > >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> > For additional commands, e-mail: dev-help@commons.apache.org
>> >
>> >
>>
>
>
> --
> Matt Sicker <bo...@gmail.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Matt Sicker <bo...@gmail.com>.
As an end user of JUL in other projects, let me warn you that you'll miss a
lot of abstractions that log4j2 and slf4j provide. :)
On Mon, 13 Aug 2018 at 09:50, Gary Gregory <ga...@gmail.com> wrote:
> I like Remko's suggestion, a nice application of the KISS principle ;-)
>
> Gary
>
> On Mon, Aug 13, 2018, 07:58 Remko Popma <re...@gmail.com> wrote:
>
> > If it was up to me I would use JUL in this particular case to keep the
> > library free of dependencies. JUL is reasonable since performance is not
> an
> > issue.
> >
> > Users that use a logging framework can redirect the JUL logging into
> their
> > log file with the JUL adapter of their logging library.
> >
> > But that’s just me.
> >
> > Remko
> >
> > (Shameless plug) Every java main() method deserves http://picocli.info
> >
> > > On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <
> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> > >
> > > I was thinking more about using that as an argument for using a logging
> > framework, but I think you are right. Probably slf4j/commons-logging +
> some
> > default binding, then allowing users to change the implementation.
> > >
> > > Perhaps slf4j + log4j?
> > >
> > >
> > > Bruno
> > >
> > > ________________________________
> > > From: Remko Popma <re...@gmail.com>
> > > To: Commons Developers List <de...@commons.apache.org>
> > > Sent: Monday, 13 August 2018 11:55 PM
> > > Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >
> > >
> > >
> > > For new projects I would really avoid using Commons Logging. Ceki had a
> > point when he created SLF4J.
> > >
> > >
> > > The projects you mentioned that have a dependency on Commons Logging
> > were started before SLF4J (and perhaps JUL) were created, I believe.
> > >
> > >
> > >
> > > (Shameless plug) Every java main() method deserves http://picocli.info
> > >
> > >
> > >>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <
> > brunodepaulak@yahoo.com.br.INVALID> wrote:
> > >
> > >> Right now that's where I am standing too. If adding a dependency to
> > log4j is a no-no, then I'd probably check if jul would be OK, or
> otherwise
> > maybe import just Log4J's LowLevelLogUtil into the project would work?
> > >
> > >
> > >
> > >> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL,
> > and Commons Validator. All of these have a compile dependency to Commons
> > Logging. So it wouldn't be creating a new precedent.
> > >
> > >
> > >
> > >> Commons Pool and Commons Compress have some optional dependencies, but
> > none for logging... maybe an optional dependency, with disabling the
> > logging by default **could** work?
> > >
> > >
> > >
> > >> Cheers
> > >
> > >> Bruno
> > >
> > >
> > >
> > >> ________________________________
> > >
> > >> From: Remko Popma <re...@gmail.com>
> > >
> > >> To: Commons Developers List <de...@commons.apache.org>
> > >
> > >> Sent: Monday, 13 August 2018 9:50 AM
> > >
> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >
> > >
> > >
> > >
> > >> If you want to avoid a dependency I would not create a custom logging
> > abstraction but just use JUL. Most logging libraries have JUL adapters so
> > clients can do the bridging on their side.
> > >
> > >
> > >> (Shameless plug) Every java main() method deserves
> http://picocli.info
> > >
> > >
> > >>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
> > >
> > >
> > >>> What I've seen done when trying to avoid a logging API dependency is
> to
> > >
> > >>> create a minimal logging API purely for framework use. This can have
> a
> > >
> > >>> default System.err style implementation, but the idea is to make it
> > easy
> > >
> > >>> (and performant hopefully) to bridge into the end user's choice of
> > >
> > >>> framework and configuration without actually requiring a real logging
> > >
> > >>> framework (at least until you want to use it in production). While it
> > seems
> > >
> > >>> overkill, the problem is that neither JUL nor System.err are
> > sufficient for
> > >
> > >>> logging. Even a simple API like Android's logging API can be good
> > enough to
> > >
> > >>> abstract it in a small library.
> > >
> > >
> > >>> For a look at the very simplest route, you can see how Log4j2 handles
> > >
> > >>> logging before any logging classes have been initialized. It's
> > basically a
> > >
> > >>> configurable wrapper around System.err:
> > >
> > >>>
> >
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
> > >
> > >
> > >
> > >>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com>
> > wrote:
> > >
> > >
> > >>>> You could also log to a pluggable print stream which could be sys
> err
> > by
> > >
> > >>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as
> well
> > :-)
> > >
> > >
> > >>>> Gary
> > >
> > >
> > >>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
> > wrote:
> > >
> > >
> > >>>>> There’s a couple of considerations about doing logging in a
> library,
> > but
> > >
> > >>>>> I’ll just mention a few:
> > >
> > >
> > >>>>> * dependencies
> > >
> > >>>>> * performance
> > >
> > >>>>> * ease of use
> > >
> > >
> > >>>>> * Dependencies*
> > >
> > >>>>> Will the library be less attractive to users if it requires an
> > external
> > >
> > >>>>> dependency? Then don’t introduce one (so: use system err or JUL).
> On
> > the
> > >
> > >>>>> other hand, if the vast majority of usages is in a context with
> many
> > >
> > >>>> other
> > >
> > >>>>> external libraries (like in a web container) you have more freedom.
> > >
> > >
> > >>>>> *Performance*
> > >
> > >>>>> Please take a look at the log4j 2 performance page (
> > >
> > >>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
> > >
> > >>>> Console
> > >
> > >>>>> logging is 50x (yes fifty times) slower than file logging.
> > >
> > >>>>> That’s a strong argument against system err logging. I’m not a fan
> of
> > >
> > >>>> JUL,
> > >
> > >>>>> but if you need to avoid dependencies you’re better off using JUL,
> > that’s
> > >
> > >>>>> only 5x slower than log4j. Also depends on how much logging you
> > expect to
> > >
> > >>>>> do in the worst case.
> > >
> > >
> > >>>>> *Ease of use*
> > >
> > >>>>> I’m biased and would say that Log4j 2 has the nicest and richest
> API.
> > >
> > >>>>> Console logging (System.err.printf) probably has the poorest API.
> > Other
> > >
> > >>>>> libraries sit in the middle.
> > >
> > >
> > >>>>> *Final note*
> > >
> > >>>>> I would never log to System out, always use system err instead.
> This
> > >
> > >>>>> allows programs using your library to pipe output to other programs
> > >
> > >>>> without
> > >
> > >>>>> their output getting mixed with your library’s diagnostic output.
> > >
> > >
> > >>>>> Hope this helps,
> > >
> > >
> > >>>>> Remko
> > >
> > >
> > >>>>> (Shameless plug) Every java main() method deserves
> > http://picocli.info
> > >
> > >
> > >>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
> > >
> > >>>> wrote:
> > >
> > >
> > >>>>>> Hello Bruno.
> > >
> > >
> > >>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita
> wrote:
> > >
> > >>>>>>> Hi all,
> > >
> > >
> > >
> > >>>>>>> I commented on IMAGING-154, but copying the last comment here as
> it
> > >
> > >>>>>>> contains the approach I would like to follow to fix the last
> > change in
> > >
> > >>>>>>> the project blocking
> > >
> > >>>>>>> a 1.0 release:
> > >
> > >
> > >
> > >>>>>>> ---
> > >
> > >
> > >>>>>>> So went ahead to re-design the Debug class, in a way users could
> > >
> > >>>>>>> still enable/disable debugging, and also use a PrintStream so
> that
> > >
> > >>>>>>> other thing rather than System.out could be used.
> > >
> > >
> > >
> > >
> > >>>>>>> Then, realized removing System.out was the natural next step. But
> > >
> > >>>>>>> alas, the library uses System.out for debugging, but sometimes it
> > uses
> > >
> > >>>>>>> it for writing to System.out in a "verbose mode". What is more
> > >
> > >>>>>>> complicated, is that sometimes classes methods like `toString()`
> > are
> > >
> > >>>>>>> calling debug methods that receive a PrintStream already.
> > >
> > >
> > >
> > >
> > >>>>>>> So I spent some more time quickly comparing what other libraries
> > I've
> > >
> > >>>>>>> seen being used / or used for image processing:
> > >
> > >
> > >
> > >>>>
> >
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> > >
> > >>>>> .
> > >
> > >>>>>>> Turns out only very low level libraries, such as the JNI bridge
> for
> > >
> > >>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
> > >
> > >>>>>>> Exception's.
> > >
> > >
> > >
> > >
> > >>>>>>> All other libraries have one way or another of logging. Be it
> with
> > >
> > >>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> > >
> > >
> > >
> > >
> > >>>>>>> My preferred compromise for this ticket was to keep Debug, making
> > >
> > >>>>>>> System.out possible but optional, and mark the class internal
> only.
> > >
> > >>>>>>> Now my preferred solution is to keep the Debug internal, but add
> a
> > >
> > >>>>>>> logger to it. And then also add logging to replace where
> > System.out is
> > >
> > >>>>>>> used for the "verbose" mode.
> > >
> > >>>>>>> ---
> > >
> > >
> > >
> > >
> > >>>>>>> Any thoughts? Objections? If none, I will try to work on this
> issue
> > >
> > >>>>>>> next weekend, making the Debug class internal only, and replacing
> > >
> > >>>>>>> System.out by a logging utility. After that, we should be good to
> > >
> > >>>>>>> start preparing the vote for 1.0.
> > >
> > >
> > >
> > >
> > >>>>>>> * I know it's hard to get a consensus on having logging in
> Commons
> > >
> > >>>>>>> components, as we have normally low level libraries, where using
> > >
> > >>>>>>> logging is not always practical.
> > >
> > >
> > >>>>>> There are Log4j2 experts reading here. It would be interesting
> > >
> > >>>>>> to hear them about what is practical or not. There are several
> > >
> > >>>>>> aspects to "practical": simplicity, flexibility, compatibility,
> > >
> > >>>>>> performance, ...
> > >
> > >>>>>> How does Log4j2 fare in these areas?
> > >
> > >>>>>> Is there a known (through experience) limit in where it should
> > >
> > >>>>>> be used?
> > >
> > >
> > >>>>>>> But I would now argue that Java own
> > >
> > >>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
> > Commons
> > >
> > >>>>>>> Imaging are located at a higher level, some times even using it
> for
> > >
> > >>>>>>> basic image handling/parsing/reading.
> > >
> > >
> > >>>>>> As with many discussions on this list, conflicting arguments occur
> > >
> > >>>>>> because people lack common (!) definitions.
> > >
> > >>>>>> So one goes: "You cannot do <something> in a low-level component"
> > >
> > >>>>>> but does not define "low-level"...
> > >
> > >
> > >>>>>>> * Feel free to cast a counter-argument for it, but please think
> > >
> > >>>>>>> whether you'd still be -0, +0 for this change. We have delayed
> 1.0
> > for
> > >
> > >>>>>>> a while, so if you have a strong opinion on not adding a logger,
> > >
> > >>>>>>> please provide an alternative for IMAGING-154.
> > >
> > >
> > >>>>>>> Otherwise we may fail
> > >
> > >>>>>>> to prepare a 1.0 release yet again, and then somebody else may
> > have to
> > >
> > >>>>>>> work on it in a few months/years...
> > >
> > >
> > >>>>>> We are there because the project is too rigid about itself as
> > >
> > >>>>>> a whole (cf. for example the [RNG] thread about BC).
> > >
> > >>>>>> IMHO, it's not the always least common denominator that is the
> > >
> > >>>>>> best decision...
> > >
> > >>>>>> As you noticed, components most easily stall in their development
> > >
> > >>>>>> for lack of proper review, or risk acceptance (i.e. assume that
> > >
> > >>>>>> those who are closer to the code (at a given time) probably know
> > >
> > >>>>>> best... :-/
> > >
> > >
> > >>>>>> My opinion is that we can take the risk to introduce logging, and
> > >
> > >>>>>> if people complain somehow, take it back later.
> > >
> > >
> > >>>>>>> one possible compromise for this,
> > >
> > >>>>>>> might be i) make Debug internal,
> > >
> > >
> > >>>>>> +1
> > >
> > >
> > >>>>>> [Hmm... Does "internal" mean that minor release can break BC
> > >
> > >>>>>> on such a class?]
> > >
> > >
> > >>>>>>> ii) remove all System.out calls,
> > >
> > >
> > >>>>>> +1 or
> > >
> > >>>>>> -1
> > >
> > >
> > >>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
> > >
> > >>>>>> indeed used in low-level utilities but is the intent the same
> > >
> > >>>>>> here?]
> > >
> > >
> > >>>>>>> which means removing the verbose flags, the checks, and calls to
> > >
> > >>>>>>> System.out in there.
> > >
> > >
> > >>>>>> It would be a loss of potentially useful information (e.g. for
> > >
> > >>>>>> debugging).
> > >
> > >
> > >>>>>> Regards,
> > >
> > >>>>>> Gilles
> > >
> > >
> > >
> > >>>>>>> Thanks!
> > >
> > >>>>>>> Bruno
> > >
> > >
> > >>>>>>> ________________________________
> > >
> > >>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> > >
> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>
> > >
> > >>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
> > >
> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >
> > >
> > >
> > >
> > >>>>>>> Hi sebb,
> > >
> > >
> > >>>>>>>> Another aspect of debugging is ensuring that methods are small
> and
> > >
> > >
> > >>>>>>>> easily tested independently.
> > >
> > >>>>>>>> However this is difficult to do, and care must be taken to
> ensure
> > >
> > >>>> that
> > >
> > >>>>>>>> the public API is not unnecessarily extended..
> > >
> > >
> > >>>>>>> A very good point.
> > >
> > >
> > >>>>>>> The parsers in commons-imaging expose some #dump... methods
> > >
> > >>>>>>> (
> > >
> > >
> > >>>>
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> > >
> > >>>>> ).
> > >
> > >
> > >>>>>>> While I can see that parsers may need to dump the data they are
> > >
> > >>>>>>> holding in some structured way for inspecting, reporting,
> > serializing,
> > >
> > >>>>>>> etc, it looks like some other classes were affected by it too.
> For
> > >
> > >>>>>>> example...
> > >
> > >
> > >
> > >>>>>>> A JPEG Segment has a #dump() method
> > >
> > >
> > >
> > >
> > >
> > >>>>
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> > >
> > >
> > >
> > >>>>>>> which gets defined in each subclass of Segment. It can be
> confusing
> > >
> > >>>>>>> to have a method such as #dump() in a Segment, from the point of
> > view
> > >
> > >>>>>>> of someone writing a photo editor for example. The user could use
> > that
> > >
> > >>>>>>> to pass his/her own logger's PrintWriter, which would make
> > removing or
> > >
> > >>>>>>> changing logging in the future in commons-imaging.
> > >
> > >
> > >
> > >>>>>>> If we keep the Debug class, and make it internal, there would
> still
> > >
> > >>>>>>> be these methods to take care. And there are some methods where
> > users
> > >
> > >>>>>>> can provide a PrintWriter, while others instead use System.out
> > >
> > >>>>>>> (e.g.
> > >
> > >
> > >>>>
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> > >
> > >>>>> ).
> > >
> > >
> > >>>>>>> Cheers
> > >
> > >>>>>>> Bruno
> > >
> > >
> > >>>>>>> ________________________________
> > >
> > >>>>>>> From: sebb <se...@gmail.com>
> > >
> > >>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> > >
> > >>>>>>> Kinoshita <br...@yahoo.com.br>
> > >
> > >>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
> > >
> > >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >
> > >
> > >
> > >
> > >>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> > >
> > >>>>>>> <br...@yahoo.com.br.invalid> wrote:
> > >
> > >>>>>>>> Hi Jorg,
> > >
> > >
> > >>>>>>>> I'd be fine with that solution too. I think this one would cause
> > the
> > >
> > >>>>> smaller change to the code as is.
> > >
> > >
> > >>>>>>>> I believe my preference is still to remove the Debug class. But
> > >
> > >>>>> between logging and making Debug internal only, I'd choose making
> it
> > >
> > >>>>> internal.
> > >
> > >
> > >>>>>>> +1
> > >
> > >
> > >>>>>>> I think making it internal means it can still be dropped later.
> > >
> > >
> > >>>>>>>> Looking forward to hearing what others think about these
> options.
> > >
> > >
> > >
> > >>>>>>> Another aspect of debugging is ensuring that methods are small
> and
> > >
> > >>>>>>> easily tested independently.
> > >
> > >>>>>>> However this is difficult to do, and care must be taken to ensure
> > that
> > >
> > >>>>>>> the public API is not unnecessarily extended..
> > >
> > >
> > >>>>>>>> Thanks
> > >
> > >>>>>>>> Bruno
> > >
> > >
> > >
> > >>>>>>>> ________________________________
> > >
> > >>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
> > >
> > >>>>>>>> To: dev@commons.apache.org
> > >
> > >>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
> > >
> > >>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >
> > >
> > >
> > >
> > >>>>>>>> Hi Bruno,
> > >
> > >
> > >
> > >>>>>>>> if it might also be helpful to our users, why not keep and
> provide
> > >
> > >>>> it.
> > >
> > >>>>> As
> > >
> > >
> > >>>>>>>> I understand it, the Debug class is a tool helping in
> development
> > to
> > >
> > >
> > >>>>>>>> analyze some behavior.
> > >
> > >
> > >
> > >>>>>>>> Nothing stops us from declaring this class internal (we might
> even
> > >
> > >>>> put
> > >
> > >>>>> it
> > >
> > >
> > >>>>>>>> into a package "internal" or "debug") that might be changed
> > without
> > >
> > >
> > >>>>>>>> further comment. Nobody may rely on it in production code, but
> > during
> > >
> > >
> > >>>>>>>> development it might be helpful. With such an approach we might
> > not
> > >
> > >>>>> have
> > >
> > >
> > >>>>>>>> a need to find a better interface to provide this functionality.
> > >
> > >
> > >
> > >>>>>>>> Just my 2¢,
> > >
> > >
> > >>>>>>>> Jörg
> > >
> > >
> > >
> > >
> > >>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> > >
> > >
> > >
> > >>>>>>>>> Hello,
> > >
> > >
> > >
> > >
> > >>>>>>>>> If memory serves me well, some time ago we had a discussion
> > around
> > >
> > >
> > >>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
> > >
> > >>>> commons-imaging
> > >
> > >
> > >>>>>>>>> 1.0 was the Debug class.
> > >
> > >
> > >
> > >
> > >>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
> > >
> > >
> > >
> > >
> > >>>>>>>>> I finished the pull request, but Gilles raised an important
> > point,
> > >
> > >>>>> about
> > >
> > >
> > >>>>>>>>> discussing other alternatives first.
> > >
> > >
> > >
> > >
> > >>>>>>>>> Initially I am against logging in low level libraries,
> especially
> > >
> > >
> > >>>>>>>>> commons components. But some time ago I had to debug TIFF
> issues
> > in
> > >
> > >
> > >>>>>>>>> commons-imaging, and having the dump methods was a tremendous
> > help.
> > >
> > >
> > >
> > >
> > >
> > >
> > >>>>>>>>> The issue is that some imaging algorithms/processing have a lot
> > of
> > >
> > >
> > >>>>>>>>> variables that can be altered. And keeping an eye on all of
> them
> > in
> > >
> > >>>>> the
> > >
> > >
> > >>>>>>>>> debugger can be quite hard - though not impossible.
> > >
> > >
> > >
> > >
> > >>>>>>>>> So all in all, now I am more confident to proceed without the
> > Debug
> > >
> > >
> > >>>>>>>>> class. But some users could have a hard time investigating
> > possible
> > >
> > >
> > >>>>>>>>> issues in the library without seeing what's going on within the
> > >
> > >>>>> library.
> > >
> > >
> > >
> > >
> > >>>>>>>>> IMO, that could be solved with the logging/dump features... or
> > >
> > >>>>> through a
> > >
> > >
> > >>>>>>>>> better design, especially around exception handling/throwing.
> The
> > >
> > >>>>> latter
> > >
> > >
> > >>>>>>>>> is my preferred approach. Instead of logging, I prefer -
> whenever
> > >
> > >
> > >>>>>>>>> possible - that low level libraries throw exceptions and let me
> > >
> > >>>> handle
> > >
> > >
> > >>>>>>>>> the logging.
> > >
> > >
> > >
> > >
> > >
> > >
> > >>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0
> to
> > a
> > >
> > >
> > >>>>>>>>> logging added to commons-imaging.
> > >
> > >
> > >
> > >
> > >>>>>>>>> Bruno
> > >
> > >
> > >
> > >>>>>>
> > ---------------------------------------------------------------------
> > >
> > >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > >
> > >>>>>> For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> > >
> > >
> > >
> > >
> > >>> --
> > >
> > >>> Matt Sicker <bo...@gmail.com>
> > >
> > >
> > >
> > >> ---------------------------------------------------------------------
> > >
> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > >
> > >> For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> > >> ---------------------------------------------------------------------
> > >
> > >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > >
> > >> For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> > >
> > > ---------------------------------------------------------------------
> > >
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > >
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
--
Matt Sicker <bo...@gmail.com>
Re: [imaging] IMAGING-154 remove Debug class
Posted by Gary Gregory <ga...@gmail.com>.
I like Remko's suggestion, a nice application of the KISS principle ;-)
Gary
On Mon, Aug 13, 2018, 07:58 Remko Popma <re...@gmail.com> wrote:
> If it was up to me I would use JUL in this particular case to keep the
> library free of dependencies. JUL is reasonable since performance is not an
> issue.
>
> Users that use a logging framework can redirect the JUL logging into their
> log file with the JUL adapter of their logging library.
>
> But that’s just me.
>
> Remko
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
> > On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <
> brunodepaulak@yahoo.com.br.INVALID> wrote:
> >
> > I was thinking more about using that as an argument for using a logging
> framework, but I think you are right. Probably slf4j/commons-logging + some
> default binding, then allowing users to change the implementation.
> >
> > Perhaps slf4j + log4j?
> >
> >
> > Bruno
> >
> > ________________________________
> > From: Remko Popma <re...@gmail.com>
> > To: Commons Developers List <de...@commons.apache.org>
> > Sent: Monday, 13 August 2018 11:55 PM
> > Subject: Re: [imaging] IMAGING-154 remove Debug class
> >
> >
> >
> > For new projects I would really avoid using Commons Logging. Ceki had a
> point when he created SLF4J.
> >
> >
> > The projects you mentioned that have a dependency on Commons Logging
> were started before SLF4J (and perhaps JUL) were created, I believe.
> >
> >
> >
> > (Shameless plug) Every java main() method deserves http://picocli.info
> >
> >
> >>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <
> brunodepaulak@yahoo.com.br.INVALID> wrote:
> >
> >> Right now that's where I am standing too. If adding a dependency to
> log4j is a no-no, then I'd probably check if jul would be OK, or otherwise
> maybe import just Log4J's LowLevelLogUtil into the project would work?
> >
> >
> >
> >> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL,
> and Commons Validator. All of these have a compile dependency to Commons
> Logging. So it wouldn't be creating a new precedent.
> >
> >
> >
> >> Commons Pool and Commons Compress have some optional dependencies, but
> none for logging... maybe an optional dependency, with disabling the
> logging by default **could** work?
> >
> >
> >
> >> Cheers
> >
> >> Bruno
> >
> >
> >
> >> ________________________________
> >
> >> From: Remko Popma <re...@gmail.com>
> >
> >> To: Commons Developers List <de...@commons.apache.org>
> >
> >> Sent: Monday, 13 August 2018 9:50 AM
> >
> >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >
> >
> >
> >
> >> If you want to avoid a dependency I would not create a custom logging
> abstraction but just use JUL. Most logging libraries have JUL adapters so
> clients can do the bridging on their side.
> >
> >
> >> (Shameless plug) Every java main() method deserves http://picocli.info
> >
> >
> >>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
> >
> >
> >>> What I've seen done when trying to avoid a logging API dependency is to
> >
> >>> create a minimal logging API purely for framework use. This can have a
> >
> >>> default System.err style implementation, but the idea is to make it
> easy
> >
> >>> (and performant hopefully) to bridge into the end user's choice of
> >
> >>> framework and configuration without actually requiring a real logging
> >
> >>> framework (at least until you want to use it in production). While it
> seems
> >
> >>> overkill, the problem is that neither JUL nor System.err are
> sufficient for
> >
> >>> logging. Even a simple API like Android's logging API can be good
> enough to
> >
> >>> abstract it in a small library.
> >
> >
> >>> For a look at the very simplest route, you can see how Log4j2 handles
> >
> >>> logging before any logging classes have been initialized. It's
> basically a
> >
> >>> configurable wrapper around System.err:
> >
> >>>
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
> >
> >
> >
> >>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com>
> wrote:
> >
> >
> >>>> You could also log to a pluggable print stream which could be sys err
> by
> >
> >>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well
> :-)
> >
> >
> >>>> Gary
> >
> >
> >>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
> wrote:
> >
> >
> >>>>> There’s a couple of considerations about doing logging in a library,
> but
> >
> >>>>> I’ll just mention a few:
> >
> >
> >>>>> * dependencies
> >
> >>>>> * performance
> >
> >>>>> * ease of use
> >
> >
> >>>>> * Dependencies*
> >
> >>>>> Will the library be less attractive to users if it requires an
> external
> >
> >>>>> dependency? Then don’t introduce one (so: use system err or JUL). On
> the
> >
> >>>>> other hand, if the vast majority of usages is in a context with many
> >
> >>>> other
> >
> >>>>> external libraries (like in a web container) you have more freedom.
> >
> >
> >>>>> *Performance*
> >
> >>>>> Please take a look at the log4j 2 performance page (
> >
> >>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
> >
> >>>> Console
> >
> >>>>> logging is 50x (yes fifty times) slower than file logging.
> >
> >>>>> That’s a strong argument against system err logging. I’m not a fan of
> >
> >>>> JUL,
> >
> >>>>> but if you need to avoid dependencies you’re better off using JUL,
> that’s
> >
> >>>>> only 5x slower than log4j. Also depends on how much logging you
> expect to
> >
> >>>>> do in the worst case.
> >
> >
> >>>>> *Ease of use*
> >
> >>>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
> >
> >>>>> Console logging (System.err.printf) probably has the poorest API.
> Other
> >
> >>>>> libraries sit in the middle.
> >
> >
> >>>>> *Final note*
> >
> >>>>> I would never log to System out, always use system err instead. This
> >
> >>>>> allows programs using your library to pipe output to other programs
> >
> >>>> without
> >
> >>>>> their output getting mixed with your library’s diagnostic output.
> >
> >
> >>>>> Hope this helps,
> >
> >
> >>>>> Remko
> >
> >
> >>>>> (Shameless plug) Every java main() method deserves
> http://picocli.info
> >
> >
> >>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
> >
> >>>> wrote:
> >
> >
> >>>>>> Hello Bruno.
> >
> >
> >>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> >
> >>>>>>> Hi all,
> >
> >
> >
> >>>>>>> I commented on IMAGING-154, but copying the last comment here as it
> >
> >>>>>>> contains the approach I would like to follow to fix the last
> change in
> >
> >>>>>>> the project blocking
> >
> >>>>>>> a 1.0 release:
> >
> >
> >
> >>>>>>> ---
> >
> >
> >>>>>>> So went ahead to re-design the Debug class, in a way users could
> >
> >>>>>>> still enable/disable debugging, and also use a PrintStream so that
> >
> >>>>>>> other thing rather than System.out could be used.
> >
> >
> >
> >
> >>>>>>> Then, realized removing System.out was the natural next step. But
> >
> >>>>>>> alas, the library uses System.out for debugging, but sometimes it
> uses
> >
> >>>>>>> it for writing to System.out in a "verbose mode". What is more
> >
> >>>>>>> complicated, is that sometimes classes methods like `toString()`
> are
> >
> >>>>>>> calling debug methods that receive a PrintStream already.
> >
> >
> >
> >
> >>>>>>> So I spent some more time quickly comparing what other libraries
> I've
> >
> >>>>>>> seen being used / or used for image processing:
> >
> >
> >
> >>>>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> >
> >>>>> .
> >
> >>>>>>> Turns out only very low level libraries, such as the JNI bridge for
> >
> >>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
> >
> >>>>>>> Exception's.
> >
> >
> >
> >
> >>>>>>> All other libraries have one way or another of logging. Be it with
> >
> >>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> >
> >
> >
> >
> >>>>>>> My preferred compromise for this ticket was to keep Debug, making
> >
> >>>>>>> System.out possible but optional, and mark the class internal only.
> >
> >>>>>>> Now my preferred solution is to keep the Debug internal, but add a
> >
> >>>>>>> logger to it. And then also add logging to replace where
> System.out is
> >
> >>>>>>> used for the "verbose" mode.
> >
> >>>>>>> ---
> >
> >
> >
> >
> >>>>>>> Any thoughts? Objections? If none, I will try to work on this issue
> >
> >>>>>>> next weekend, making the Debug class internal only, and replacing
> >
> >>>>>>> System.out by a logging utility. After that, we should be good to
> >
> >>>>>>> start preparing the vote for 1.0.
> >
> >
> >
> >
> >>>>>>> * I know it's hard to get a consensus on having logging in Commons
> >
> >>>>>>> components, as we have normally low level libraries, where using
> >
> >>>>>>> logging is not always practical.
> >
> >
> >>>>>> There are Log4j2 experts reading here. It would be interesting
> >
> >>>>>> to hear them about what is practical or not. There are several
> >
> >>>>>> aspects to "practical": simplicity, flexibility, compatibility,
> >
> >>>>>> performance, ...
> >
> >>>>>> How does Log4j2 fare in these areas?
> >
> >>>>>> Is there a known (through experience) limit in where it should
> >
> >>>>>> be used?
> >
> >
> >>>>>>> But I would now argue that Java own
> >
> >>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
> Commons
> >
> >>>>>>> Imaging are located at a higher level, some times even using it for
> >
> >>>>>>> basic image handling/parsing/reading.
> >
> >
> >>>>>> As with many discussions on this list, conflicting arguments occur
> >
> >>>>>> because people lack common (!) definitions.
> >
> >>>>>> So one goes: "You cannot do <something> in a low-level component"
> >
> >>>>>> but does not define "low-level"...
> >
> >
> >>>>>>> * Feel free to cast a counter-argument for it, but please think
> >
> >>>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0
> for
> >
> >>>>>>> a while, so if you have a strong opinion on not adding a logger,
> >
> >>>>>>> please provide an alternative for IMAGING-154.
> >
> >
> >>>>>>> Otherwise we may fail
> >
> >>>>>>> to prepare a 1.0 release yet again, and then somebody else may
> have to
> >
> >>>>>>> work on it in a few months/years...
> >
> >
> >>>>>> We are there because the project is too rigid about itself as
> >
> >>>>>> a whole (cf. for example the [RNG] thread about BC).
> >
> >>>>>> IMHO, it's not the always least common denominator that is the
> >
> >>>>>> best decision...
> >
> >>>>>> As you noticed, components most easily stall in their development
> >
> >>>>>> for lack of proper review, or risk acceptance (i.e. assume that
> >
> >>>>>> those who are closer to the code (at a given time) probably know
> >
> >>>>>> best... :-/
> >
> >
> >>>>>> My opinion is that we can take the risk to introduce logging, and
> >
> >>>>>> if people complain somehow, take it back later.
> >
> >
> >>>>>>> one possible compromise for this,
> >
> >>>>>>> might be i) make Debug internal,
> >
> >
> >>>>>> +1
> >
> >
> >>>>>> [Hmm... Does "internal" mean that minor release can break BC
> >
> >>>>>> on such a class?]
> >
> >
> >>>>>>> ii) remove all System.out calls,
> >
> >
> >>>>>> +1 or
> >
> >>>>>> -1
> >
> >
> >>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
> >
> >>>>>> indeed used in low-level utilities but is the intent the same
> >
> >>>>>> here?]
> >
> >
> >>>>>>> which means removing the verbose flags, the checks, and calls to
> >
> >>>>>>> System.out in there.
> >
> >
> >>>>>> It would be a loss of potentially useful information (e.g. for
> >
> >>>>>> debugging).
> >
> >
> >>>>>> Regards,
> >
> >>>>>> Gilles
> >
> >
> >
> >>>>>>> Thanks!
> >
> >>>>>>> Bruno
> >
> >
> >>>>>>> ________________________________
> >
> >>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> >
> >>>>>>> To: Commons Developers List <de...@commons.apache.org>
> >
> >>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
> >
> >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >
> >
> >
> >
> >>>>>>> Hi sebb,
> >
> >
> >>>>>>>> Another aspect of debugging is ensuring that methods are small and
> >
> >
> >>>>>>>> easily tested independently.
> >
> >>>>>>>> However this is difficult to do, and care must be taken to ensure
> >
> >>>> that
> >
> >>>>>>>> the public API is not unnecessarily extended..
> >
> >
> >>>>>>> A very good point.
> >
> >
> >>>>>>> The parsers in commons-imaging expose some #dump... methods
> >
> >>>>>>> (
> >
> >
> >>>>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> >
> >>>>> ).
> >
> >
> >>>>>>> While I can see that parsers may need to dump the data they are
> >
> >>>>>>> holding in some structured way for inspecting, reporting,
> serializing,
> >
> >>>>>>> etc, it looks like some other classes were affected by it too. For
> >
> >>>>>>> example...
> >
> >
> >
> >>>>>>> A JPEG Segment has a #dump() method
> >
> >
> >
> >
> >
> >>>>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> >
> >
> >
> >>>>>>> which gets defined in each subclass of Segment. It can be confusing
> >
> >>>>>>> to have a method such as #dump() in a Segment, from the point of
> view
> >
> >>>>>>> of someone writing a photo editor for example. The user could use
> that
> >
> >>>>>>> to pass his/her own logger's PrintWriter, which would make
> removing or
> >
> >>>>>>> changing logging in the future in commons-imaging.
> >
> >
> >
> >>>>>>> If we keep the Debug class, and make it internal, there would still
> >
> >>>>>>> be these methods to take care. And there are some methods where
> users
> >
> >>>>>>> can provide a PrintWriter, while others instead use System.out
> >
> >>>>>>> (e.g.
> >
> >
> >>>>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> >
> >>>>> ).
> >
> >
> >>>>>>> Cheers
> >
> >>>>>>> Bruno
> >
> >
> >>>>>>> ________________________________
> >
> >>>>>>> From: sebb <se...@gmail.com>
> >
> >>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> >
> >>>>>>> Kinoshita <br...@yahoo.com.br>
> >
> >>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
> >
> >>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >
> >
> >
> >
> >>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> >
> >>>>>>> <br...@yahoo.com.br.invalid> wrote:
> >
> >>>>>>>> Hi Jorg,
> >
> >
> >>>>>>>> I'd be fine with that solution too. I think this one would cause
> the
> >
> >>>>> smaller change to the code as is.
> >
> >
> >>>>>>>> I believe my preference is still to remove the Debug class. But
> >
> >>>>> between logging and making Debug internal only, I'd choose making it
> >
> >>>>> internal.
> >
> >
> >>>>>>> +1
> >
> >
> >>>>>>> I think making it internal means it can still be dropped later.
> >
> >
> >>>>>>>> Looking forward to hearing what others think about these options.
> >
> >
> >
> >>>>>>> Another aspect of debugging is ensuring that methods are small and
> >
> >>>>>>> easily tested independently.
> >
> >>>>>>> However this is difficult to do, and care must be taken to ensure
> that
> >
> >>>>>>> the public API is not unnecessarily extended..
> >
> >
> >>>>>>>> Thanks
> >
> >>>>>>>> Bruno
> >
> >
> >
> >>>>>>>> ________________________________
> >
> >>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
> >
> >>>>>>>> To: dev@commons.apache.org
> >
> >>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
> >
> >>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >
> >
> >
> >
> >>>>>>>> Hi Bruno,
> >
> >
> >
> >>>>>>>> if it might also be helpful to our users, why not keep and provide
> >
> >>>> it.
> >
> >>>>> As
> >
> >
> >>>>>>>> I understand it, the Debug class is a tool helping in development
> to
> >
> >
> >>>>>>>> analyze some behavior.
> >
> >
> >
> >>>>>>>> Nothing stops us from declaring this class internal (we might even
> >
> >>>> put
> >
> >>>>> it
> >
> >
> >>>>>>>> into a package "internal" or "debug") that might be changed
> without
> >
> >
> >>>>>>>> further comment. Nobody may rely on it in production code, but
> during
> >
> >
> >>>>>>>> development it might be helpful. With such an approach we might
> not
> >
> >>>>> have
> >
> >
> >>>>>>>> a need to find a better interface to provide this functionality.
> >
> >
> >
> >>>>>>>> Just my 2¢,
> >
> >
> >>>>>>>> Jörg
> >
> >
> >
> >
> >>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> >
> >
> >
> >>>>>>>>> Hello,
> >
> >
> >
> >
> >>>>>>>>> If memory serves me well, some time ago we had a discussion
> around
> >
> >
> >>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
> >
> >>>> commons-imaging
> >
> >
> >>>>>>>>> 1.0 was the Debug class.
> >
> >
> >
> >
> >>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
> >
> >
> >
> >
> >>>>>>>>> I finished the pull request, but Gilles raised an important
> point,
> >
> >>>>> about
> >
> >
> >>>>>>>>> discussing other alternatives first.
> >
> >
> >
> >
> >>>>>>>>> Initially I am against logging in low level libraries, especially
> >
> >
> >>>>>>>>> commons components. But some time ago I had to debug TIFF issues
> in
> >
> >
> >>>>>>>>> commons-imaging, and having the dump methods was a tremendous
> help.
> >
> >
> >
> >
> >
> >
> >>>>>>>>> The issue is that some imaging algorithms/processing have a lot
> of
> >
> >
> >>>>>>>>> variables that can be altered. And keeping an eye on all of them
> in
> >
> >>>>> the
> >
> >
> >>>>>>>>> debugger can be quite hard - though not impossible.
> >
> >
> >
> >
> >>>>>>>>> So all in all, now I am more confident to proceed without the
> Debug
> >
> >
> >>>>>>>>> class. But some users could have a hard time investigating
> possible
> >
> >
> >>>>>>>>> issues in the library without seeing what's going on within the
> >
> >>>>> library.
> >
> >
> >
> >
> >>>>>>>>> IMO, that could be solved with the logging/dump features... or
> >
> >>>>> through a
> >
> >
> >>>>>>>>> better design, especially around exception handling/throwing. The
> >
> >>>>> latter
> >
> >
> >>>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
> >
> >
> >>>>>>>>> possible - that low level libraries throw exceptions and let me
> >
> >>>> handle
> >
> >
> >>>>>>>>> the logging.
> >
> >
> >
> >
> >
> >
> >>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to
> a
> >
> >
> >>>>>>>>> logging added to commons-imaging.
> >
> >
> >
> >
> >>>>>>>>> Bruno
> >
> >
> >
> >>>>>>
> ---------------------------------------------------------------------
> >
> >>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >
> >>>>>> For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
> >
> >
> >
> >
> >>> --
> >
> >>> Matt Sicker <bo...@gmail.com>
> >
> >
> >
> >> ---------------------------------------------------------------------
> >
> >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
> >> ---------------------------------------------------------------------
> >
> >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
> >
> > ---------------------------------------------------------------------
> >
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [imaging] IMAGING-154 remove Debug class
Posted by sebb <se...@gmail.com>.
On 13 August 2018 at 14:57, Remko Popma <re...@gmail.com> wrote:
> If it was up to me I would use JUL in this particular case to keep the library free of dependencies. JUL is reasonable since performance is not an issue.
>
> Users that use a logging framework can redirect the JUL logging into their log file with the JUL adapter of their logging library.
>
> But that’s just me.
+1, seems good to me as well.
> Remko
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
>> On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <br...@yahoo.com.br.INVALID> wrote:
>>
>> I was thinking more about using that as an argument for using a logging framework, but I think you are right. Probably slf4j/commons-logging + some default binding, then allowing users to change the implementation.
>>
>> Perhaps slf4j + log4j?
>>
>>
>> Bruno
>>
>> ________________________________
>> From: Remko Popma <re...@gmail.com>
>> To: Commons Developers List <de...@commons.apache.org>
>> Sent: Monday, 13 August 2018 11:55 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> For new projects I would really avoid using Commons Logging. Ceki had a point when he created SLF4J.
>>
>>
>> The projects you mentioned that have a dependency on Commons Logging were started before SLF4J (and perhaps JUL) were created, I believe.
>>
>>
>>
>> (Shameless plug) Every java main() method deserves http://picocli.info
>>
>>
>>>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <br...@yahoo.com.br.INVALID> wrote:
>>
>>> Right now that's where I am standing too. If adding a dependency to log4j is a no-no, then I'd probably check if jul would be OK, or otherwise maybe import just Log4J's LowLevelLogUtil into the project would work?
>>
>>
>>
>>> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL, and Commons Validator. All of these have a compile dependency to Commons Logging. So it wouldn't be creating a new precedent.
>>
>>
>>
>>> Commons Pool and Commons Compress have some optional dependencies, but none for logging... maybe an optional dependency, with disabling the logging by default **could** work?
>>
>>
>>
>>> Cheers
>>
>>> Bruno
>>
>>
>>
>>> ________________________________
>>
>>> From: Remko Popma <re...@gmail.com>
>>
>>> To: Commons Developers List <de...@commons.apache.org>
>>
>>> Sent: Monday, 13 August 2018 9:50 AM
>>
>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>>
>>> If you want to avoid a dependency I would not create a custom logging abstraction but just use JUL. Most logging libraries have JUL adapters so clients can do the bridging on their side.
>>
>>
>>> (Shameless plug) Every java main() method deserves http://picocli.info
>>
>>
>>>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>>
>>
>>>> What I've seen done when trying to avoid a logging API dependency is to
>>
>>>> create a minimal logging API purely for framework use. This can have a
>>
>>>> default System.err style implementation, but the idea is to make it easy
>>
>>>> (and performant hopefully) to bridge into the end user's choice of
>>
>>>> framework and configuration without actually requiring a real logging
>>
>>>> framework (at least until you want to use it in production). While it seems
>>
>>>> overkill, the problem is that neither JUL nor System.err are sufficient for
>>
>>>> logging. Even a simple API like Android's logging API can be good enough to
>>
>>>> abstract it in a small library.
>>
>>
>>>> For a look at the very simplest route, you can see how Log4j2 handles
>>
>>>> logging before any logging classes have been initialized. It's basically a
>>
>>>> configurable wrapper around System.err:
>>
>>>> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>>
>>
>>
>>>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
>>
>>
>>>>> You could also log to a pluggable print stream which could be sys err by
>>
>>>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>>
>>
>>>>> Gary
>>
>>
>>>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>>
>>
>>>>>> There’s a couple of considerations about doing logging in a library, but
>>
>>>>>> I’ll just mention a few:
>>
>>
>>>>>> * dependencies
>>
>>>>>> * performance
>>
>>>>>> * ease of use
>>
>>
>>>>>> * Dependencies*
>>
>>>>>> Will the library be less attractive to users if it requires an external
>>
>>>>>> dependency? Then don’t introduce one (so: use system err or JUL). On the
>>
>>>>>> other hand, if the vast majority of usages is in a context with many
>>
>>>>> other
>>
>>>>>> external libraries (like in a web container) you have more freedom.
>>
>>
>>>>>> *Performance*
>>
>>>>>> Please take a look at the log4j 2 performance page (
>>
>>>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>>
>>>>> Console
>>
>>>>>> logging is 50x (yes fifty times) slower than file logging.
>>
>>>>>> That’s a strong argument against system err logging. I’m not a fan of
>>
>>>>> JUL,
>>
>>>>>> but if you need to avoid dependencies you’re better off using JUL, that’s
>>
>>>>>> only 5x slower than log4j. Also depends on how much logging you expect to
>>
>>>>>> do in the worst case.
>>
>>
>>>>>> *Ease of use*
>>
>>>>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
>>
>>>>>> Console logging (System.err.printf) probably has the poorest API. Other
>>
>>>>>> libraries sit in the middle.
>>
>>
>>>>>> *Final note*
>>
>>>>>> I would never log to System out, always use system err instead. This
>>
>>>>>> allows programs using your library to pipe output to other programs
>>
>>>>> without
>>
>>>>>> their output getting mixed with your library’s diagnostic output.
>>
>>
>>>>>> Hope this helps,
>>
>>
>>>>>> Remko
>>
>>
>>>>>> (Shameless plug) Every java main() method deserves http://picocli.info
>>
>>
>>>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>>
>>>>> wrote:
>>
>>
>>>>>>> Hello Bruno.
>>
>>
>>>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>>
>>>>>>>> Hi all,
>>
>>
>>
>>>>>>>> I commented on IMAGING-154, but copying the last comment here as it
>>
>>>>>>>> contains the approach I would like to follow to fix the last change in
>>
>>>>>>>> the project blocking
>>
>>>>>>>> a 1.0 release:
>>
>>
>>
>>>>>>>> ---
>>
>>
>>>>>>>> So went ahead to re-design the Debug class, in a way users could
>>
>>>>>>>> still enable/disable debugging, and also use a PrintStream so that
>>
>>>>>>>> other thing rather than System.out could be used.
>>
>>
>>
>>
>>>>>>>> Then, realized removing System.out was the natural next step. But
>>
>>>>>>>> alas, the library uses System.out for debugging, but sometimes it uses
>>
>>>>>>>> it for writing to System.out in a "verbose mode". What is more
>>
>>>>>>>> complicated, is that sometimes classes methods like `toString()` are
>>
>>>>>>>> calling debug methods that receive a PrintStream already.
>>
>>
>>
>>
>>>>>>>> So I spent some more time quickly comparing what other libraries I've
>>
>>>>>>>> seen being used / or used for image processing:
>>
>>
>>
>>>>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>>
>>>>>> .
>>
>>>>>>>> Turns out only very low level libraries, such as the JNI bridge for
>>
>>>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>>
>>>>>>>> Exception's.
>>
>>
>>
>>
>>>>>>>> All other libraries have one way or another of logging. Be it with
>>
>>>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>
>>
>>
>>
>>>>>>>> My preferred compromise for this ticket was to keep Debug, making
>>
>>>>>>>> System.out possible but optional, and mark the class internal only.
>>
>>>>>>>> Now my preferred solution is to keep the Debug internal, but add a
>>
>>>>>>>> logger to it. And then also add logging to replace where System.out is
>>
>>>>>>>> used for the "verbose" mode.
>>
>>>>>>>> ---
>>
>>
>>
>>
>>>>>>>> Any thoughts? Objections? If none, I will try to work on this issue
>>
>>>>>>>> next weekend, making the Debug class internal only, and replacing
>>
>>>>>>>> System.out by a logging utility. After that, we should be good to
>>
>>>>>>>> start preparing the vote for 1.0.
>>
>>
>>
>>
>>>>>>>> * I know it's hard to get a consensus on having logging in Commons
>>
>>>>>>>> components, as we have normally low level libraries, where using
>>
>>>>>>>> logging is not always practical.
>>
>>
>>>>>>> There are Log4j2 experts reading here. It would be interesting
>>
>>>>>>> to hear them about what is practical or not. There are several
>>
>>>>>>> aspects to "practical": simplicity, flexibility, compatibility,
>>
>>>>>>> performance, ...
>>
>>>>>>> How does Log4j2 fare in these areas?
>>
>>>>>>> Is there a known (through experience) limit in where it should
>>
>>>>>>> be used?
>>
>>
>>>>>>>> But I would now argue that Java own
>>
>>>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>>
>>>>>>>> Imaging are located at a higher level, some times even using it for
>>
>>>>>>>> basic image handling/parsing/reading.
>>
>>
>>>>>>> As with many discussions on this list, conflicting arguments occur
>>
>>>>>>> because people lack common (!) definitions.
>>
>>>>>>> So one goes: "You cannot do <something> in a low-level component"
>>
>>>>>>> but does not define "low-level"...
>>
>>
>>>>>>>> * Feel free to cast a counter-argument for it, but please think
>>
>>>>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>>
>>>>>>>> a while, so if you have a strong opinion on not adding a logger,
>>
>>>>>>>> please provide an alternative for IMAGING-154.
>>
>>
>>>>>>>> Otherwise we may fail
>>
>>>>>>>> to prepare a 1.0 release yet again, and then somebody else may have to
>>
>>>>>>>> work on it in a few months/years...
>>
>>
>>>>>>> We are there because the project is too rigid about itself as
>>
>>>>>>> a whole (cf. for example the [RNG] thread about BC).
>>
>>>>>>> IMHO, it's not the always least common denominator that is the
>>
>>>>>>> best decision...
>>
>>>>>>> As you noticed, components most easily stall in their development
>>
>>>>>>> for lack of proper review, or risk acceptance (i.e. assume that
>>
>>>>>>> those who are closer to the code (at a given time) probably know
>>
>>>>>>> best... :-/
>>
>>
>>>>>>> My opinion is that we can take the risk to introduce logging, and
>>
>>>>>>> if people complain somehow, take it back later.
>>
>>
>>>>>>>> one possible compromise for this,
>>
>>>>>>>> might be i) make Debug internal,
>>
>>
>>>>>>> +1
>>
>>
>>>>>>> [Hmm... Does "internal" mean that minor release can break BC
>>
>>>>>>> on such a class?]
>>
>>
>>>>>>>> ii) remove all System.out calls,
>>
>>
>>>>>>> +1 or
>>
>>>>>>> -1
>>
>>
>>>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>>
>>>>>>> indeed used in low-level utilities but is the intent the same
>>
>>>>>>> here?]
>>
>>
>>>>>>>> which means removing the verbose flags, the checks, and calls to
>>
>>>>>>>> System.out in there.
>>
>>
>>>>>>> It would be a loss of potentially useful information (e.g. for
>>
>>>>>>> debugging).
>>
>>
>>>>>>> Regards,
>>
>>>>>>> Gilles
>>
>>
>>
>>>>>>>> Thanks!
>>
>>>>>>>> Bruno
>>
>>
>>>>>>>> ________________________________
>>
>>>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>>
>>>>>>>> To: Commons Developers List <de...@commons.apache.org>
>>
>>>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>>
>>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>>
>>>>>>>> Hi sebb,
>>
>>
>>>>>>>>> Another aspect of debugging is ensuring that methods are small and
>>
>>
>>>>>>>>> easily tested independently.
>>
>>>>>>>>> However this is difficult to do, and care must be taken to ensure
>>
>>>>> that
>>
>>>>>>>>> the public API is not unnecessarily extended..
>>
>>
>>>>>>>> A very good point.
>>
>>
>>>>>>>> The parsers in commons-imaging expose some #dump... methods
>>
>>>>>>>> (
>>
>>
>>>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>>
>>>>>> ).
>>
>>
>>>>>>>> While I can see that parsers may need to dump the data they are
>>
>>>>>>>> holding in some structured way for inspecting, reporting, serializing,
>>
>>>>>>>> etc, it looks like some other classes were affected by it too. For
>>
>>>>>>>> example...
>>
>>
>>
>>>>>>>> A JPEG Segment has a #dump() method
>>
>>
>>
>>
>>
>>>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>
>>
>>
>>>>>>>> which gets defined in each subclass of Segment. It can be confusing
>>
>>>>>>>> to have a method such as #dump() in a Segment, from the point of view
>>
>>>>>>>> of someone writing a photo editor for example. The user could use that
>>
>>>>>>>> to pass his/her own logger's PrintWriter, which would make removing or
>>
>>>>>>>> changing logging in the future in commons-imaging.
>>
>>
>>
>>>>>>>> If we keep the Debug class, and make it internal, there would still
>>
>>>>>>>> be these methods to take care. And there are some methods where users
>>
>>>>>>>> can provide a PrintWriter, while others instead use System.out
>>
>>>>>>>> (e.g.
>>
>>
>>>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>>
>>>>>> ).
>>
>>
>>>>>>>> Cheers
>>
>>>>>>>> Bruno
>>
>>
>>>>>>>> ________________________________
>>
>>>>>>>> From: sebb <se...@gmail.com>
>>
>>>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>>
>>>>>>>> Kinoshita <br...@yahoo.com.br>
>>
>>>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>>
>>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>>
>>>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>>
>>>>>>>> <br...@yahoo.com.br.invalid> wrote:
>>
>>>>>>>>> Hi Jorg,
>>
>>
>>>>>>>>> I'd be fine with that solution too. I think this one would cause the
>>
>>>>>> smaller change to the code as is.
>>
>>
>>>>>>>>> I believe my preference is still to remove the Debug class. But
>>
>>>>>> between logging and making Debug internal only, I'd choose making it
>>
>>>>>> internal.
>>
>>
>>>>>>>> +1
>>
>>
>>>>>>>> I think making it internal means it can still be dropped later.
>>
>>
>>>>>>>>> Looking forward to hearing what others think about these options.
>>
>>
>>
>>>>>>>> Another aspect of debugging is ensuring that methods are small and
>>
>>>>>>>> easily tested independently.
>>
>>>>>>>> However this is difficult to do, and care must be taken to ensure that
>>
>>>>>>>> the public API is not unnecessarily extended..
>>
>>
>>>>>>>>> Thanks
>>
>>>>>>>>> Bruno
>>
>>
>>
>>>>>>>>> ________________________________
>>
>>>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>
>>>>>>>>> To: dev@commons.apache.org
>>
>>>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>
>>>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>>
>>>>>>>>> Hi Bruno,
>>
>>
>>
>>>>>>>>> if it might also be helpful to our users, why not keep and provide
>>
>>>>> it.
>>
>>>>>> As
>>
>>
>>>>>>>>> I understand it, the Debug class is a tool helping in development to
>>
>>
>>>>>>>>> analyze some behavior.
>>
>>
>>
>>>>>>>>> Nothing stops us from declaring this class internal (we might even
>>
>>>>> put
>>
>>>>>> it
>>
>>
>>>>>>>>> into a package "internal" or "debug") that might be changed without
>>
>>
>>>>>>>>> further comment. Nobody may rely on it in production code, but during
>>
>>
>>>>>>>>> development it might be helpful. With such an approach we might not
>>
>>>>>> have
>>
>>
>>>>>>>>> a need to find a better interface to provide this functionality.
>>
>>
>>
>>>>>>>>> Just my 2¢,
>>
>>
>>>>>>>>> Jörg
>>
>>
>>
>>
>>>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>
>>
>>
>>>>>>>>>> Hello,
>>
>>
>>
>>
>>>>>>>>>> If memory serves me well, some time ago we had a discussion around
>>
>>
>>>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>>
>>>>> commons-imaging
>>
>>
>>>>>>>>>> 1.0 was the Debug class.
>>
>>
>>
>>
>>>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>
>>
>>
>>
>>>>>>>>>> I finished the pull request, but Gilles raised an important point,
>>
>>>>>> about
>>
>>
>>>>>>>>>> discussing other alternatives first.
>>
>>
>>
>>
>>>>>>>>>> Initially I am against logging in low level libraries, especially
>>
>>
>>>>>>>>>> commons components. But some time ago I had to debug TIFF issues in
>>
>>
>>>>>>>>>> commons-imaging, and having the dump methods was a tremendous help.
>>
>>
>>
>>
>>
>>
>>>>>>>>>> The issue is that some imaging algorithms/processing have a lot of
>>
>>
>>>>>>>>>> variables that can be altered. And keeping an eye on all of them in
>>
>>>>>> the
>>
>>
>>>>>>>>>> debugger can be quite hard - though not impossible.
>>
>>
>>
>>
>>>>>>>>>> So all in all, now I am more confident to proceed without the Debug
>>
>>
>>>>>>>>>> class. But some users could have a hard time investigating possible
>>
>>
>>>>>>>>>> issues in the library without seeing what's going on within the
>>
>>>>>> library.
>>
>>
>>
>>
>>>>>>>>>> IMO, that could be solved with the logging/dump features... or
>>
>>>>>> through a
>>
>>
>>>>>>>>>> better design, especially around exception handling/throwing. The
>>
>>>>>> latter
>>
>>
>>>>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>
>>
>>>>>>>>>> possible - that low level libraries throw exceptions and let me
>>
>>>>> handle
>>
>>
>>>>>>>>>> the logging.
>>
>>
>>
>>
>>
>>
>>>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>
>>
>>>>>>>>>> logging added to commons-imaging.
>>
>>
>>
>>
>>>>>>>>>> Bruno
>>
>>
>>
>>>>>>> ---------------------------------------------------------------------
>>
>>>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>
>>>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>>
>>
>>
>>
>>>> --
>>
>>>> Matt Sicker <bo...@gmail.com>
>>
>>
>>
>>> ---------------------------------------------------------------------
>>
>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>
>>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>>> ---------------------------------------------------------------------
>>
>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>
>>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>>
>> ---------------------------------------------------------------------
>>
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Remko Popma <re...@gmail.com>.
If it was up to me I would use JUL in this particular case to keep the library free of dependencies. JUL is reasonable since performance is not an issue.
Users that use a logging framework can redirect the JUL logging into their log file with the JUL adapter of their logging library.
But that’s just me.
Remko
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 13, 2018, at 21:05, Bruno P. Kinoshita <br...@yahoo.com.br.INVALID> wrote:
>
> I was thinking more about using that as an argument for using a logging framework, but I think you are right. Probably slf4j/commons-logging + some default binding, then allowing users to change the implementation.
>
> Perhaps slf4j + log4j?
>
>
> Bruno
>
> ________________________________
> From: Remko Popma <re...@gmail.com>
> To: Commons Developers List <de...@commons.apache.org>
> Sent: Monday, 13 August 2018 11:55 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> For new projects I would really avoid using Commons Logging. Ceki had a point when he created SLF4J.
>
>
> The projects you mentioned that have a dependency on Commons Logging were started before SLF4J (and perhaps JUL) were created, I believe.
>
>
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
>
>>> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <br...@yahoo.com.br.INVALID> wrote:
>
>> Right now that's where I am standing too. If adding a dependency to log4j is a no-no, then I'd probably check if jul would be OK, or otherwise maybe import just Log4J's LowLevelLogUtil into the project would work?
>
>
>
>> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL, and Commons Validator. All of these have a compile dependency to Commons Logging. So it wouldn't be creating a new precedent.
>
>
>
>> Commons Pool and Commons Compress have some optional dependencies, but none for logging... maybe an optional dependency, with disabling the logging by default **could** work?
>
>
>
>> Cheers
>
>> Bruno
>
>
>
>> ________________________________
>
>> From: Remko Popma <re...@gmail.com>
>
>> To: Commons Developers List <de...@commons.apache.org>
>
>> Sent: Monday, 13 August 2018 9:50 AM
>
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
>
>> If you want to avoid a dependency I would not create a custom logging abstraction but just use JUL. Most logging libraries have JUL adapters so clients can do the bridging on their side.
>
>
>> (Shameless plug) Every java main() method deserves http://picocli.info
>
>
>>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>
>
>>> What I've seen done when trying to avoid a logging API dependency is to
>
>>> create a minimal logging API purely for framework use. This can have a
>
>>> default System.err style implementation, but the idea is to make it easy
>
>>> (and performant hopefully) to bridge into the end user's choice of
>
>>> framework and configuration without actually requiring a real logging
>
>>> framework (at least until you want to use it in production). While it seems
>
>>> overkill, the problem is that neither JUL nor System.err are sufficient for
>
>>> logging. Even a simple API like Android's logging API can be good enough to
>
>>> abstract it in a small library.
>
>
>>> For a look at the very simplest route, you can see how Log4j2 handles
>
>>> logging before any logging classes have been initialized. It's basically a
>
>>> configurable wrapper around System.err:
>
>>> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>
>
>
>>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
>
>
>>>> You could also log to a pluggable print stream which could be sys err by
>
>>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>
>
>>>> Gary
>
>
>>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>
>
>>>>> There’s a couple of considerations about doing logging in a library, but
>
>>>>> I’ll just mention a few:
>
>
>>>>> * dependencies
>
>>>>> * performance
>
>>>>> * ease of use
>
>
>>>>> * Dependencies*
>
>>>>> Will the library be less attractive to users if it requires an external
>
>>>>> dependency? Then don’t introduce one (so: use system err or JUL). On the
>
>>>>> other hand, if the vast majority of usages is in a context with many
>
>>>> other
>
>>>>> external libraries (like in a web container) you have more freedom.
>
>
>>>>> *Performance*
>
>>>>> Please take a look at the log4j 2 performance page (
>
>>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>
>>>> Console
>
>>>>> logging is 50x (yes fifty times) slower than file logging.
>
>>>>> That’s a strong argument against system err logging. I’m not a fan of
>
>>>> JUL,
>
>>>>> but if you need to avoid dependencies you’re better off using JUL, that’s
>
>>>>> only 5x slower than log4j. Also depends on how much logging you expect to
>
>>>>> do in the worst case.
>
>
>>>>> *Ease of use*
>
>>>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
>
>>>>> Console logging (System.err.printf) probably has the poorest API. Other
>
>>>>> libraries sit in the middle.
>
>
>>>>> *Final note*
>
>>>>> I would never log to System out, always use system err instead. This
>
>>>>> allows programs using your library to pipe output to other programs
>
>>>> without
>
>>>>> their output getting mixed with your library’s diagnostic output.
>
>
>>>>> Hope this helps,
>
>
>>>>> Remko
>
>
>>>>> (Shameless plug) Every java main() method deserves http://picocli.info
>
>
>>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>
>>>> wrote:
>
>
>>>>>> Hello Bruno.
>
>
>>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>
>>>>>>> Hi all,
>
>
>
>>>>>>> I commented on IMAGING-154, but copying the last comment here as it
>
>>>>>>> contains the approach I would like to follow to fix the last change in
>
>>>>>>> the project blocking
>
>>>>>>> a 1.0 release:
>
>
>
>>>>>>> ---
>
>
>>>>>>> So went ahead to re-design the Debug class, in a way users could
>
>>>>>>> still enable/disable debugging, and also use a PrintStream so that
>
>>>>>>> other thing rather than System.out could be used.
>
>
>
>
>>>>>>> Then, realized removing System.out was the natural next step. But
>
>>>>>>> alas, the library uses System.out for debugging, but sometimes it uses
>
>>>>>>> it for writing to System.out in a "verbose mode". What is more
>
>>>>>>> complicated, is that sometimes classes methods like `toString()` are
>
>>>>>>> calling debug methods that receive a PrintStream already.
>
>
>
>
>>>>>>> So I spent some more time quickly comparing what other libraries I've
>
>>>>>>> seen being used / or used for image processing:
>
>
>
>>>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>
>>>>> .
>
>>>>>>> Turns out only very low level libraries, such as the JNI bridge for
>
>>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>
>>>>>>> Exception's.
>
>
>
>
>>>>>>> All other libraries have one way or another of logging. Be it with
>
>>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>
>
>
>
>>>>>>> My preferred compromise for this ticket was to keep Debug, making
>
>>>>>>> System.out possible but optional, and mark the class internal only.
>
>>>>>>> Now my preferred solution is to keep the Debug internal, but add a
>
>>>>>>> logger to it. And then also add logging to replace where System.out is
>
>>>>>>> used for the "verbose" mode.
>
>>>>>>> ---
>
>
>
>
>>>>>>> Any thoughts? Objections? If none, I will try to work on this issue
>
>>>>>>> next weekend, making the Debug class internal only, and replacing
>
>>>>>>> System.out by a logging utility. After that, we should be good to
>
>>>>>>> start preparing the vote for 1.0.
>
>
>
>
>>>>>>> * I know it's hard to get a consensus on having logging in Commons
>
>>>>>>> components, as we have normally low level libraries, where using
>
>>>>>>> logging is not always practical.
>
>
>>>>>> There are Log4j2 experts reading here. It would be interesting
>
>>>>>> to hear them about what is practical or not. There are several
>
>>>>>> aspects to "practical": simplicity, flexibility, compatibility,
>
>>>>>> performance, ...
>
>>>>>> How does Log4j2 fare in these areas?
>
>>>>>> Is there a known (through experience) limit in where it should
>
>>>>>> be used?
>
>
>>>>>>> But I would now argue that Java own
>
>>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>
>>>>>>> Imaging are located at a higher level, some times even using it for
>
>>>>>>> basic image handling/parsing/reading.
>
>
>>>>>> As with many discussions on this list, conflicting arguments occur
>
>>>>>> because people lack common (!) definitions.
>
>>>>>> So one goes: "You cannot do <something> in a low-level component"
>
>>>>>> but does not define "low-level"...
>
>
>>>>>>> * Feel free to cast a counter-argument for it, but please think
>
>>>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>
>>>>>>> a while, so if you have a strong opinion on not adding a logger,
>
>>>>>>> please provide an alternative for IMAGING-154.
>
>
>>>>>>> Otherwise we may fail
>
>>>>>>> to prepare a 1.0 release yet again, and then somebody else may have to
>
>>>>>>> work on it in a few months/years...
>
>
>>>>>> We are there because the project is too rigid about itself as
>
>>>>>> a whole (cf. for example the [RNG] thread about BC).
>
>>>>>> IMHO, it's not the always least common denominator that is the
>
>>>>>> best decision...
>
>>>>>> As you noticed, components most easily stall in their development
>
>>>>>> for lack of proper review, or risk acceptance (i.e. assume that
>
>>>>>> those who are closer to the code (at a given time) probably know
>
>>>>>> best... :-/
>
>
>>>>>> My opinion is that we can take the risk to introduce logging, and
>
>>>>>> if people complain somehow, take it back later.
>
>
>>>>>>> one possible compromise for this,
>
>>>>>>> might be i) make Debug internal,
>
>
>>>>>> +1
>
>
>>>>>> [Hmm... Does "internal" mean that minor release can break BC
>
>>>>>> on such a class?]
>
>
>>>>>>> ii) remove all System.out calls,
>
>
>>>>>> +1 or
>
>>>>>> -1
>
>
>>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>
>>>>>> indeed used in low-level utilities but is the intent the same
>
>>>>>> here?]
>
>
>>>>>>> which means removing the verbose flags, the checks, and calls to
>
>>>>>>> System.out in there.
>
>
>>>>>> It would be a loss of potentially useful information (e.g. for
>
>>>>>> debugging).
>
>
>>>>>> Regards,
>
>>>>>> Gilles
>
>
>
>>>>>>> Thanks!
>
>>>>>>> Bruno
>
>
>>>>>>> ________________________________
>
>>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>
>>>>>>> To: Commons Developers List <de...@commons.apache.org>
>
>>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>
>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
>
>>>>>>> Hi sebb,
>
>
>>>>>>>> Another aspect of debugging is ensuring that methods are small and
>
>
>>>>>>>> easily tested independently.
>
>>>>>>>> However this is difficult to do, and care must be taken to ensure
>
>>>> that
>
>>>>>>>> the public API is not unnecessarily extended..
>
>
>>>>>>> A very good point.
>
>
>>>>>>> The parsers in commons-imaging expose some #dump... methods
>
>>>>>>> (
>
>
>>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>
>>>>> ).
>
>
>>>>>>> While I can see that parsers may need to dump the data they are
>
>>>>>>> holding in some structured way for inspecting, reporting, serializing,
>
>>>>>>> etc, it looks like some other classes were affected by it too. For
>
>>>>>>> example...
>
>
>
>>>>>>> A JPEG Segment has a #dump() method
>
>
>
>
>
>>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>
>
>
>>>>>>> which gets defined in each subclass of Segment. It can be confusing
>
>>>>>>> to have a method such as #dump() in a Segment, from the point of view
>
>>>>>>> of someone writing a photo editor for example. The user could use that
>
>>>>>>> to pass his/her own logger's PrintWriter, which would make removing or
>
>>>>>>> changing logging in the future in commons-imaging.
>
>
>
>>>>>>> If we keep the Debug class, and make it internal, there would still
>
>>>>>>> be these methods to take care. And there are some methods where users
>
>>>>>>> can provide a PrintWriter, while others instead use System.out
>
>>>>>>> (e.g.
>
>
>>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>
>>>>> ).
>
>
>>>>>>> Cheers
>
>>>>>>> Bruno
>
>
>>>>>>> ________________________________
>
>>>>>>> From: sebb <se...@gmail.com>
>
>>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>
>>>>>>> Kinoshita <br...@yahoo.com.br>
>
>>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>
>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
>
>>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>
>>>>>>> <br...@yahoo.com.br.invalid> wrote:
>
>>>>>>>> Hi Jorg,
>
>
>>>>>>>> I'd be fine with that solution too. I think this one would cause the
>
>>>>> smaller change to the code as is.
>
>
>>>>>>>> I believe my preference is still to remove the Debug class. But
>
>>>>> between logging and making Debug internal only, I'd choose making it
>
>>>>> internal.
>
>
>>>>>>> +1
>
>
>>>>>>> I think making it internal means it can still be dropped later.
>
>
>>>>>>>> Looking forward to hearing what others think about these options.
>
>
>
>>>>>>> Another aspect of debugging is ensuring that methods are small and
>
>>>>>>> easily tested independently.
>
>>>>>>> However this is difficult to do, and care must be taken to ensure that
>
>>>>>>> the public API is not unnecessarily extended..
>
>
>>>>>>>> Thanks
>
>>>>>>>> Bruno
>
>
>
>>>>>>>> ________________________________
>
>>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>
>>>>>>>> To: dev@commons.apache.org
>
>>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>
>>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
>
>>>>>>>> Hi Bruno,
>
>
>
>>>>>>>> if it might also be helpful to our users, why not keep and provide
>
>>>> it.
>
>>>>> As
>
>
>>>>>>>> I understand it, the Debug class is a tool helping in development to
>
>
>>>>>>>> analyze some behavior.
>
>
>
>>>>>>>> Nothing stops us from declaring this class internal (we might even
>
>>>> put
>
>>>>> it
>
>
>>>>>>>> into a package "internal" or "debug") that might be changed without
>
>
>>>>>>>> further comment. Nobody may rely on it in production code, but during
>
>
>>>>>>>> development it might be helpful. With such an approach we might not
>
>>>>> have
>
>
>>>>>>>> a need to find a better interface to provide this functionality.
>
>
>
>>>>>>>> Just my 2¢,
>
>
>>>>>>>> Jörg
>
>
>
>
>>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>
>
>
>>>>>>>>> Hello,
>
>
>
>
>>>>>>>>> If memory serves me well, some time ago we had a discussion around
>
>
>>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>
>>>> commons-imaging
>
>
>>>>>>>>> 1.0 was the Debug class.
>
>
>
>
>>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>
>
>
>
>>>>>>>>> I finished the pull request, but Gilles raised an important point,
>
>>>>> about
>
>
>>>>>>>>> discussing other alternatives first.
>
>
>
>
>>>>>>>>> Initially I am against logging in low level libraries, especially
>
>
>>>>>>>>> commons components. But some time ago I had to debug TIFF issues in
>
>
>>>>>>>>> commons-imaging, and having the dump methods was a tremendous help.
>
>
>
>
>
>
>>>>>>>>> The issue is that some imaging algorithms/processing have a lot of
>
>
>>>>>>>>> variables that can be altered. And keeping an eye on all of them in
>
>>>>> the
>
>
>>>>>>>>> debugger can be quite hard - though not impossible.
>
>
>
>
>>>>>>>>> So all in all, now I am more confident to proceed without the Debug
>
>
>>>>>>>>> class. But some users could have a hard time investigating possible
>
>
>>>>>>>>> issues in the library without seeing what's going on within the
>
>>>>> library.
>
>
>
>
>>>>>>>>> IMO, that could be solved with the logging/dump features... or
>
>>>>> through a
>
>
>>>>>>>>> better design, especially around exception handling/throwing. The
>
>>>>> latter
>
>
>>>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
>
>
>>>>>>>>> possible - that low level libraries throw exceptions and let me
>
>>>> handle
>
>
>>>>>>>>> the logging.
>
>
>
>
>
>
>>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>
>
>>>>>>>>> logging added to commons-imaging.
>
>
>
>
>>>>>>>>> Bruno
>
>
>
>>>>>> ---------------------------------------------------------------------
>
>>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
>>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>
>
>
>
>
>
>>> --
>
>>> Matt Sicker <bo...@gmail.com>
>
>
>
>> ---------------------------------------------------------------------
>
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
>> For additional commands, e-mail: dev-help@commons.apache.org
>
>
>> ---------------------------------------------------------------------
>
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
>> For additional commands, e-mail: dev-help@commons.apache.org
>
>
>
> ---------------------------------------------------------------------
>
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
I was thinking more about using that as an argument for using a logging framework, but I think you are right. Probably slf4j/commons-logging + some default binding, then allowing users to change the implementation.
Perhaps slf4j + log4j?
Bruno
________________________________
From: Remko Popma <re...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Monday, 13 August 2018 11:55 PM
Subject: Re: [imaging] IMAGING-154 remove Debug class
For new projects I would really avoid using Commons Logging. Ceki had a point when he created SLF4J.
The projects you mentioned that have a dependency on Commons Logging were started before SLF4J (and perhaps JUL) were created, I believe.
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <br...@yahoo.com.br.INVALID> wrote:
>
> Right now that's where I am standing too. If adding a dependency to log4j is a no-no, then I'd probably check if jul would be OK, or otherwise maybe import just Log4J's LowLevelLogUtil into the project would work?
>
>
> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL, and Commons Validator. All of these have a compile dependency to Commons Logging. So it wouldn't be creating a new precedent.
>
>
> Commons Pool and Commons Compress have some optional dependencies, but none for logging... maybe an optional dependency, with disabling the logging by default **could** work?
>
>
> Cheers
> Bruno
>
>
> ________________________________
> From: Remko Popma <re...@gmail.com>
> To: Commons Developers List <de...@commons.apache.org>
> Sent: Monday, 13 August 2018 9:50 AM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> If you want to avoid a dependency I would not create a custom logging abstraction but just use JUL. Most logging libraries have JUL adapters so clients can do the bridging on their side.
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>>
>> What I've seen done when trying to avoid a logging API dependency is to
>> create a minimal logging API purely for framework use. This can have a
>> default System.err style implementation, but the idea is to make it easy
>> (and performant hopefully) to bridge into the end user's choice of
>> framework and configuration without actually requiring a real logging
>> framework (at least until you want to use it in production). While it seems
>> overkill, the problem is that neither JUL nor System.err are sufficient for
>> logging. Even a simple API like Android's logging API can be good enough to
>> abstract it in a small library.
>>
>> For a look at the very simplest route, you can see how Log4j2 handles
>> logging before any logging classes have been initialized. It's basically a
>> configurable wrapper around System.err:
>> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>>
>>
>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
>>>
>>> You could also log to a pluggable print stream which could be sys err by
>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>>>
>>> Gary
>>>
>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>>>>
>>>> There’s a couple of considerations about doing logging in a library, but
>>>> I’ll just mention a few:
>>>>
>>>> * dependencies
>>>> * performance
>>>> * ease of use
>>>>
>>>> * Dependencies*
>>>> Will the library be less attractive to users if it requires an external
>>>> dependency? Then don’t introduce one (so: use system err or JUL). On the
>>>> other hand, if the vast majority of usages is in a context with many
>>> other
>>>> external libraries (like in a web container) you have more freedom.
>>>>
>>>> *Performance*
>>>> Please take a look at the log4j 2 performance page (
>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>>> Console
>>>> logging is 50x (yes fifty times) slower than file logging.
>>>> That’s a strong argument against system err logging. I’m not a fan of
>>> JUL,
>>>> but if you need to avoid dependencies you’re better off using JUL, that’s
>>>> only 5x slower than log4j. Also depends on how much logging you expect to
>>>> do in the worst case.
>>>>
>>>> *Ease of use*
>>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
>>>> Console logging (System.err.printf) probably has the poorest API. Other
>>>> libraries sit in the middle.
>>>>
>>>> *Final note*
>>>> I would never log to System out, always use system err instead. This
>>>> allows programs using your library to pipe output to other programs
>>> without
>>>> their output getting mixed with your library’s diagnostic output.
>>>>
>>>> Hope this helps,
>>>>
>>>> Remko
>>>>
>>>> (Shameless plug) Every java main() method deserves http://picocli.info
>>>>
>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>>> wrote:
>>>>>
>>>>> Hello Bruno.
>>>>>
>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>>>>>> Hi all,
>>>>>>
>>>>>>
>>>>>> I commented on IMAGING-154, but copying the last comment here as it
>>>>>> contains the approach I would like to follow to fix the last change in
>>>>>> the project blocking
>>>>>> a 1.0 release:
>>>>>>
>>>>>>
>>>>>> ---
>>>>>>
>>>>>> So went ahead to re-design the Debug class, in a way users could
>>>>>> still enable/disable debugging, and also use a PrintStream so that
>>>>>> other thing rather than System.out could be used.
>>>>>>
>>>>>>
>>>>>>
>>>>>> Then, realized removing System.out was the natural next step. But
>>>>>> alas, the library uses System.out for debugging, but sometimes it uses
>>>>>> it for writing to System.out in a "verbose mode". What is more
>>>>>> complicated, is that sometimes classes methods like `toString()` are
>>>>>> calling debug methods that receive a PrintStream already.
>>>>>>
>>>>>>
>>>>>>
>>>>>> So I spent some more time quickly comparing what other libraries I've
>>>>>> seen being used / or used for image processing:
>>>>>>
>>>>
>>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>>>> .
>>>>>> Turns out only very low level libraries, such as the JNI bridge for
>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>>>>>> Exception's.
>>>>>>
>>>>>>
>>>>>>
>>>>>> All other libraries have one way or another of logging. Be it with
>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>>>>>
>>>>>>
>>>>>>
>>>>>> My preferred compromise for this ticket was to keep Debug, making
>>>>>> System.out possible but optional, and mark the class internal only.
>>>>>> Now my preferred solution is to keep the Debug internal, but add a
>>>>>> logger to it. And then also add logging to replace where System.out is
>>>>>> used for the "verbose" mode.
>>>>>> ---
>>>>>>
>>>>>>
>>>>>>
>>>>>> Any thoughts? Objections? If none, I will try to work on this issue
>>>>>> next weekend, making the Debug class internal only, and replacing
>>>>>> System.out by a logging utility. After that, we should be good to
>>>>>> start preparing the vote for 1.0.
>>>>>>
>>>>>>
>>>>>>
>>>>>> * I know it's hard to get a consensus on having logging in Commons
>>>>>> components, as we have normally low level libraries, where using
>>>>>> logging is not always practical.
>>>>>
>>>>> There are Log4j2 experts reading here. It would be interesting
>>>>> to hear them about what is practical or not. There are several
>>>>> aspects to "practical": simplicity, flexibility, compatibility,
>>>>> performance, ...
>>>>> How does Log4j2 fare in these areas?
>>>>> Is there a known (through experience) limit in where it should
>>>>> be used?
>>>>>
>>>>>> But I would now argue that Java own
>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>>>>>> Imaging are located at a higher level, some times even using it for
>>>>>> basic image handling/parsing/reading.
>>>>>
>>>>> As with many discussions on this list, conflicting arguments occur
>>>>> because people lack common (!) definitions.
>>>>> So one goes: "You cannot do <something> in a low-level component"
>>>>> but does not define "low-level"...
>>>>>
>>>>>> * Feel free to cast a counter-argument for it, but please think
>>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>>>>>> a while, so if you have a strong opinion on not adding a logger,
>>>>>> please provide an alternative for IMAGING-154.
>>>>>
>>>>>> Otherwise we may fail
>>>>>> to prepare a 1.0 release yet again, and then somebody else may have to
>>>>>> work on it in a few months/years...
>>>>>
>>>>> We are there because the project is too rigid about itself as
>>>>> a whole (cf. for example the [RNG] thread about BC).
>>>>> IMHO, it's not the always least common denominator that is the
>>>>> best decision...
>>>>> As you noticed, components most easily stall in their development
>>>>> for lack of proper review, or risk acceptance (i.e. assume that
>>>>> those who are closer to the code (at a given time) probably know
>>>>> best... :-/
>>>>>
>>>>> My opinion is that we can take the risk to introduce logging, and
>>>>> if people complain somehow, take it back later.
>>>>>
>>>>>> one possible compromise for this,
>>>>>> might be i) make Debug internal,
>>>>>
>>>>> +1
>>>>>
>>>>> [Hmm... Does "internal" mean that minor release can break BC
>>>>> on such a class?]
>>>>>
>>>>>> ii) remove all System.out calls,
>>>>>
>>>>> +1 or
>>>>> -1
>>>>>
>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>>>>> indeed used in low-level utilities but is the intent the same
>>>>> here?]
>>>>>
>>>>>> which means removing the verbose flags, the checks, and calls to
>>>>>> System.out in there.
>>>>>
>>>>> It would be a loss of potentially useful information (e.g. for
>>>>> debugging).
>>>>>
>>>>> Regards,
>>>>> Gilles
>>>>>
>>>>>>
>>>>>> Thanks!
>>>>>> Bruno
>>>>>>
>>>>>> ________________________________
>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>>>>>> To: Commons Developers List <de...@commons.apache.org>
>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> Hi sebb,
>>>>>>
>>>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>>>
>>>>>>> easily tested independently.
>>>>>>> However this is difficult to do, and care must be taken to ensure
>>> that
>>>>>>> the public API is not unnecessarily extended..
>>>>>>
>>>>>> A very good point.
>>>>>>
>>>>>> The parsers in commons-imaging expose some #dump... methods
>>>>>> (
>>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>>>> ).
>>>>>>
>>>>>> While I can see that parsers may need to dump the data they are
>>>>>> holding in some structured way for inspecting, reporting, serializing,
>>>>>> etc, it looks like some other classes were affected by it too. For
>>>>>> example...
>>>>>>
>>>>>>
>>>>>> A JPEG Segment has a #dump() method
>>>>>>
>>>>>>
>>>>>>
>>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>>>>>
>>>>>>
>>>>>> which gets defined in each subclass of Segment. It can be confusing
>>>>>> to have a method such as #dump() in a Segment, from the point of view
>>>>>> of someone writing a photo editor for example. The user could use that
>>>>>> to pass his/her own logger's PrintWriter, which would make removing or
>>>>>> changing logging in the future in commons-imaging.
>>>>>>
>>>>>>
>>>>>> If we keep the Debug class, and make it internal, there would still
>>>>>> be these methods to take care. And there are some methods where users
>>>>>> can provide a PrintWriter, while others instead use System.out
>>>>>> (e.g.
>>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>>>> ).
>>>>>>
>>>>>> Cheers
>>>>>> Bruno
>>>>>>
>>>>>> ________________________________
>>>>>> From: sebb <se...@gmail.com>
>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>>>>>> Kinoshita <br...@yahoo.com.br>
>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>>>>>> <br...@yahoo.com.br.invalid> wrote:
>>>>>>> Hi Jorg,
>>>>>>>
>>>>>>> I'd be fine with that solution too. I think this one would cause the
>>>> smaller change to the code as is.
>>>>>>>
>>>>>>> I believe my preference is still to remove the Debug class. But
>>>> between logging and making Debug internal only, I'd choose making it
>>>> internal.
>>>>>>
>>>>>> +1
>>>>>>
>>>>>> I think making it internal means it can still be dropped later.
>>>>>>
>>>>>>> Looking forward to hearing what others think about these options.
>>>>>>>
>>>>>>
>>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>>> easily tested independently.
>>>>>> However this is difficult to do, and care must be taken to ensure that
>>>>>> the public API is not unnecessarily extended..
>>>>>>
>>>>>>> Thanks
>>>>>>> Bruno
>>>>>>>
>>>>>>>
>>>>>>> ________________________________
>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>>>>>> To: dev@commons.apache.org
>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Hi Bruno,
>>>>>>>
>>>>>>>
>>>>>>> if it might also be helpful to our users, why not keep and provide
>>> it.
>>>> As
>>>>>>>
>>>>>>> I understand it, the Debug class is a tool helping in development to
>>>>>>>
>>>>>>> analyze some behavior.
>>>>>>>
>>>>>>>
>>>>>>> Nothing stops us from declaring this class internal (we might even
>>> put
>>>> it
>>>>>>>
>>>>>>> into a package "internal" or "debug") that might be changed without
>>>>>>>
>>>>>>> further comment. Nobody may rely on it in production code, but during
>>>>>>>
>>>>>>> development it might be helpful. With such an approach we might not
>>>> have
>>>>>>>
>>>>>>> a need to find a better interface to provide this functionality.
>>>>>>>
>>>>>>>
>>>>>>> Just my 2¢,
>>>>>>>
>>>>>>> Jörg
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>>>>>
>>>>>>>
>>>>>>>> Hello,
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> If memory serves me well, some time ago we had a discussion around
>>>>>>>
>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>>> commons-imaging
>>>>>>>
>>>>>>>> 1.0 was the Debug class.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> I finished the pull request, but Gilles raised an important point,
>>>> about
>>>>>>>
>>>>>>>> discussing other alternatives first.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> Initially I am against logging in low level libraries, especially
>>>>>>>
>>>>>>>> commons components. But some time ago I had to debug TIFF issues in
>>>>>>>
>>>>>>>> commons-imaging, and having the dump methods was a tremendous help.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> The issue is that some imaging algorithms/processing have a lot of
>>>>>>>
>>>>>>>> variables that can be altered. And keeping an eye on all of them in
>>>> the
>>>>>>>
>>>>>>>> debugger can be quite hard - though not impossible.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> So all in all, now I am more confident to proceed without the Debug
>>>>>>>
>>>>>>>> class. But some users could have a hard time investigating possible
>>>>>>>
>>>>>>>> issues in the library without seeing what's going on within the
>>>> library.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> IMO, that could be solved with the logging/dump features... or
>>>> through a
>>>>>>>
>>>>>>>> better design, especially around exception handling/throwing. The
>>>> latter
>>>>>>>
>>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>>>>>>
>>>>>>>> possible - that low level libraries throw exceptions and let me
>>> handle
>>>>>>>
>>>>>>>> the logging.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>>>>>>
>>>>>>>> logging added to commons-imaging.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> Bruno
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>>
>>>>
>>>
>>
>>
>> --
>> Matt Sicker <bo...@gmail.com>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Remko Popma <re...@gmail.com>.
For new projects I would really avoid using Commons Logging. Ceki had a point when he created SLF4J.
The projects you mentioned that have a dependency on Commons Logging were started before SLF4J (and perhaps JUL) were created, I believe.
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 13, 2018, at 18:22, Bruno P. Kinoshita <br...@yahoo.com.br.INVALID> wrote:
>
> Right now that's where I am standing too. If adding a dependency to log4j is a no-no, then I'd probably check if jul would be OK, or otherwise maybe import just Log4J's LowLevelLogUtil into the project would work?
>
>
> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL, and Commons Validator. All of these have a compile dependency to Commons Logging. So it wouldn't be creating a new precedent.
>
>
> Commons Pool and Commons Compress have some optional dependencies, but none for logging... maybe an optional dependency, with disabling the logging by default **could** work?
>
>
> Cheers
> Bruno
>
>
> ________________________________
> From: Remko Popma <re...@gmail.com>
> To: Commons Developers List <de...@commons.apache.org>
> Sent: Monday, 13 August 2018 9:50 AM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> If you want to avoid a dependency I would not create a custom logging abstraction but just use JUL. Most logging libraries have JUL adapters so clients can do the bridging on their side.
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>>
>> What I've seen done when trying to avoid a logging API dependency is to
>> create a minimal logging API purely for framework use. This can have a
>> default System.err style implementation, but the idea is to make it easy
>> (and performant hopefully) to bridge into the end user's choice of
>> framework and configuration without actually requiring a real logging
>> framework (at least until you want to use it in production). While it seems
>> overkill, the problem is that neither JUL nor System.err are sufficient for
>> logging. Even a simple API like Android's logging API can be good enough to
>> abstract it in a small library.
>>
>> For a look at the very simplest route, you can see how Log4j2 handles
>> logging before any logging classes have been initialized. It's basically a
>> configurable wrapper around System.err:
>> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>>
>>
>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
>>>
>>> You could also log to a pluggable print stream which could be sys err by
>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>>>
>>> Gary
>>>
>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>>>>
>>>> There’s a couple of considerations about doing logging in a library, but
>>>> I’ll just mention a few:
>>>>
>>>> * dependencies
>>>> * performance
>>>> * ease of use
>>>>
>>>> * Dependencies*
>>>> Will the library be less attractive to users if it requires an external
>>>> dependency? Then don’t introduce one (so: use system err or JUL). On the
>>>> other hand, if the vast majority of usages is in a context with many
>>> other
>>>> external libraries (like in a web container) you have more freedom.
>>>>
>>>> *Performance*
>>>> Please take a look at the log4j 2 performance page (
>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>>> Console
>>>> logging is 50x (yes fifty times) slower than file logging.
>>>> That’s a strong argument against system err logging. I’m not a fan of
>>> JUL,
>>>> but if you need to avoid dependencies you’re better off using JUL, that’s
>>>> only 5x slower than log4j. Also depends on how much logging you expect to
>>>> do in the worst case.
>>>>
>>>> *Ease of use*
>>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
>>>> Console logging (System.err.printf) probably has the poorest API. Other
>>>> libraries sit in the middle.
>>>>
>>>> *Final note*
>>>> I would never log to System out, always use system err instead. This
>>>> allows programs using your library to pipe output to other programs
>>> without
>>>> their output getting mixed with your library’s diagnostic output.
>>>>
>>>> Hope this helps,
>>>>
>>>> Remko
>>>>
>>>> (Shameless plug) Every java main() method deserves http://picocli.info
>>>>
>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>>> wrote:
>>>>>
>>>>> Hello Bruno.
>>>>>
>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>>>>>> Hi all,
>>>>>>
>>>>>>
>>>>>> I commented on IMAGING-154, but copying the last comment here as it
>>>>>> contains the approach I would like to follow to fix the last change in
>>>>>> the project blocking
>>>>>> a 1.0 release:
>>>>>>
>>>>>>
>>>>>> ---
>>>>>>
>>>>>> So went ahead to re-design the Debug class, in a way users could
>>>>>> still enable/disable debugging, and also use a PrintStream so that
>>>>>> other thing rather than System.out could be used.
>>>>>>
>>>>>>
>>>>>>
>>>>>> Then, realized removing System.out was the natural next step. But
>>>>>> alas, the library uses System.out for debugging, but sometimes it uses
>>>>>> it for writing to System.out in a "verbose mode". What is more
>>>>>> complicated, is that sometimes classes methods like `toString()` are
>>>>>> calling debug methods that receive a PrintStream already.
>>>>>>
>>>>>>
>>>>>>
>>>>>> So I spent some more time quickly comparing what other libraries I've
>>>>>> seen being used / or used for image processing:
>>>>>>
>>>>
>>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>>>> .
>>>>>> Turns out only very low level libraries, such as the JNI bridge for
>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>>>>>> Exception's.
>>>>>>
>>>>>>
>>>>>>
>>>>>> All other libraries have one way or another of logging. Be it with
>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>>>>>
>>>>>>
>>>>>>
>>>>>> My preferred compromise for this ticket was to keep Debug, making
>>>>>> System.out possible but optional, and mark the class internal only.
>>>>>> Now my preferred solution is to keep the Debug internal, but add a
>>>>>> logger to it. And then also add logging to replace where System.out is
>>>>>> used for the "verbose" mode.
>>>>>> ---
>>>>>>
>>>>>>
>>>>>>
>>>>>> Any thoughts? Objections? If none, I will try to work on this issue
>>>>>> next weekend, making the Debug class internal only, and replacing
>>>>>> System.out by a logging utility. After that, we should be good to
>>>>>> start preparing the vote for 1.0.
>>>>>>
>>>>>>
>>>>>>
>>>>>> * I know it's hard to get a consensus on having logging in Commons
>>>>>> components, as we have normally low level libraries, where using
>>>>>> logging is not always practical.
>>>>>
>>>>> There are Log4j2 experts reading here. It would be interesting
>>>>> to hear them about what is practical or not. There are several
>>>>> aspects to "practical": simplicity, flexibility, compatibility,
>>>>> performance, ...
>>>>> How does Log4j2 fare in these areas?
>>>>> Is there a known (through experience) limit in where it should
>>>>> be used?
>>>>>
>>>>>> But I would now argue that Java own
>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>>>>>> Imaging are located at a higher level, some times even using it for
>>>>>> basic image handling/parsing/reading.
>>>>>
>>>>> As with many discussions on this list, conflicting arguments occur
>>>>> because people lack common (!) definitions.
>>>>> So one goes: "You cannot do <something> in a low-level component"
>>>>> but does not define "low-level"...
>>>>>
>>>>>> * Feel free to cast a counter-argument for it, but please think
>>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>>>>>> a while, so if you have a strong opinion on not adding a logger,
>>>>>> please provide an alternative for IMAGING-154.
>>>>>
>>>>>> Otherwise we may fail
>>>>>> to prepare a 1.0 release yet again, and then somebody else may have to
>>>>>> work on it in a few months/years...
>>>>>
>>>>> We are there because the project is too rigid about itself as
>>>>> a whole (cf. for example the [RNG] thread about BC).
>>>>> IMHO, it's not the always least common denominator that is the
>>>>> best decision...
>>>>> As you noticed, components most easily stall in their development
>>>>> for lack of proper review, or risk acceptance (i.e. assume that
>>>>> those who are closer to the code (at a given time) probably know
>>>>> best... :-/
>>>>>
>>>>> My opinion is that we can take the risk to introduce logging, and
>>>>> if people complain somehow, take it back later.
>>>>>
>>>>>> one possible compromise for this,
>>>>>> might be i) make Debug internal,
>>>>>
>>>>> +1
>>>>>
>>>>> [Hmm... Does "internal" mean that minor release can break BC
>>>>> on such a class?]
>>>>>
>>>>>> ii) remove all System.out calls,
>>>>>
>>>>> +1 or
>>>>> -1
>>>>>
>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>>>>> indeed used in low-level utilities but is the intent the same
>>>>> here?]
>>>>>
>>>>>> which means removing the verbose flags, the checks, and calls to
>>>>>> System.out in there.
>>>>>
>>>>> It would be a loss of potentially useful information (e.g. for
>>>>> debugging).
>>>>>
>>>>> Regards,
>>>>> Gilles
>>>>>
>>>>>>
>>>>>> Thanks!
>>>>>> Bruno
>>>>>>
>>>>>> ________________________________
>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>>>>>> To: Commons Developers List <de...@commons.apache.org>
>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> Hi sebb,
>>>>>>
>>>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>>>
>>>>>>> easily tested independently.
>>>>>>> However this is difficult to do, and care must be taken to ensure
>>> that
>>>>>>> the public API is not unnecessarily extended..
>>>>>>
>>>>>> A very good point.
>>>>>>
>>>>>> The parsers in commons-imaging expose some #dump... methods
>>>>>> (
>>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>>>> ).
>>>>>>
>>>>>> While I can see that parsers may need to dump the data they are
>>>>>> holding in some structured way for inspecting, reporting, serializing,
>>>>>> etc, it looks like some other classes were affected by it too. For
>>>>>> example...
>>>>>>
>>>>>>
>>>>>> A JPEG Segment has a #dump() method
>>>>>>
>>>>>>
>>>>>>
>>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>>>>>
>>>>>>
>>>>>> which gets defined in each subclass of Segment. It can be confusing
>>>>>> to have a method such as #dump() in a Segment, from the point of view
>>>>>> of someone writing a photo editor for example. The user could use that
>>>>>> to pass his/her own logger's PrintWriter, which would make removing or
>>>>>> changing logging in the future in commons-imaging.
>>>>>>
>>>>>>
>>>>>> If we keep the Debug class, and make it internal, there would still
>>>>>> be these methods to take care. And there are some methods where users
>>>>>> can provide a PrintWriter, while others instead use System.out
>>>>>> (e.g.
>>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>>>> ).
>>>>>>
>>>>>> Cheers
>>>>>> Bruno
>>>>>>
>>>>>> ________________________________
>>>>>> From: sebb <se...@gmail.com>
>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>>>>>> Kinoshita <br...@yahoo.com.br>
>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>>>>>> <br...@yahoo.com.br.invalid> wrote:
>>>>>>> Hi Jorg,
>>>>>>>
>>>>>>> I'd be fine with that solution too. I think this one would cause the
>>>> smaller change to the code as is.
>>>>>>>
>>>>>>> I believe my preference is still to remove the Debug class. But
>>>> between logging and making Debug internal only, I'd choose making it
>>>> internal.
>>>>>>
>>>>>> +1
>>>>>>
>>>>>> I think making it internal means it can still be dropped later.
>>>>>>
>>>>>>> Looking forward to hearing what others think about these options.
>>>>>>>
>>>>>>
>>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>>> easily tested independently.
>>>>>> However this is difficult to do, and care must be taken to ensure that
>>>>>> the public API is not unnecessarily extended..
>>>>>>
>>>>>>> Thanks
>>>>>>> Bruno
>>>>>>>
>>>>>>>
>>>>>>> ________________________________
>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>>>>>> To: dev@commons.apache.org
>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Hi Bruno,
>>>>>>>
>>>>>>>
>>>>>>> if it might also be helpful to our users, why not keep and provide
>>> it.
>>>> As
>>>>>>>
>>>>>>> I understand it, the Debug class is a tool helping in development to
>>>>>>>
>>>>>>> analyze some behavior.
>>>>>>>
>>>>>>>
>>>>>>> Nothing stops us from declaring this class internal (we might even
>>> put
>>>> it
>>>>>>>
>>>>>>> into a package "internal" or "debug") that might be changed without
>>>>>>>
>>>>>>> further comment. Nobody may rely on it in production code, but during
>>>>>>>
>>>>>>> development it might be helpful. With such an approach we might not
>>>> have
>>>>>>>
>>>>>>> a need to find a better interface to provide this functionality.
>>>>>>>
>>>>>>>
>>>>>>> Just my 2¢,
>>>>>>>
>>>>>>> Jörg
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>>>>>
>>>>>>>
>>>>>>>> Hello,
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> If memory serves me well, some time ago we had a discussion around
>>>>>>>
>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>>> commons-imaging
>>>>>>>
>>>>>>>> 1.0 was the Debug class.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> I finished the pull request, but Gilles raised an important point,
>>>> about
>>>>>>>
>>>>>>>> discussing other alternatives first.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> Initially I am against logging in low level libraries, especially
>>>>>>>
>>>>>>>> commons components. But some time ago I had to debug TIFF issues in
>>>>>>>
>>>>>>>> commons-imaging, and having the dump methods was a tremendous help.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> The issue is that some imaging algorithms/processing have a lot of
>>>>>>>
>>>>>>>> variables that can be altered. And keeping an eye on all of them in
>>>> the
>>>>>>>
>>>>>>>> debugger can be quite hard - though not impossible.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> So all in all, now I am more confident to proceed without the Debug
>>>>>>>
>>>>>>>> class. But some users could have a hard time investigating possible
>>>>>>>
>>>>>>>> issues in the library without seeing what's going on within the
>>>> library.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> IMO, that could be solved with the logging/dump features... or
>>>> through a
>>>>>>>
>>>>>>>> better design, especially around exception handling/throwing. The
>>>> latter
>>>>>>>
>>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>>>>>>
>>>>>>>> possible - that low level libraries throw exceptions and let me
>>> handle
>>>>>>>
>>>>>>>> the logging.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>>>>>>
>>>>>>>> logging added to commons-imaging.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> Bruno
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>>
>>>>
>>>
>>
>>
>> --
>> Matt Sicker <bo...@gmail.com>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Gilles <gi...@harfang.homelinux.org>.
Hi Bruno.
On Mon, 13 Aug 2018 09:22:27 +0000 (UTC), Bruno P. Kinoshita wrote:
> Right now that's where I am standing too. If adding a dependency to
> log4j is a no-no, then I'd probably check if jul would be OK, or
> otherwise maybe import just Log4J's LowLevelLogUtil into the project
> would work?
>
>
> Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL,
> and Commons Validator. All of these have a compile dependency to
> Commons Logging. So it wouldn't be creating a new precedent.
>
>
> Commons Pool and Commons Compress have some optional dependencies,
> but none for logging... maybe an optional dependency, with disabling
> the logging by default **could** work?
Logging configuration is an application property: it's up to the
user to enable or disable actual logging.
If logging statements are introduced, it may be useful to provide
minimal configuration file examples for the most popular logging
frameworks showing how to disable output.
Regards,
Gilles
>
>
> Cheers
> Bruno
>
>
> ________________________________
> From: Remko Popma <re...@gmail.com>
> To: Commons Developers List <de...@commons.apache.org>
> Sent: Monday, 13 August 2018 9:50 AM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> If you want to avoid a dependency I would not create a custom logging
> abstraction but just use JUL. Most logging libraries have JUL
> adapters
> so clients can do the bridging on their side.
>
> (Shameless plug) Every java main() method deserves
> http://picocli.info
>
>> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>>
>> What I've seen done when trying to avoid a logging API dependency is
>> to
>> create a minimal logging API purely for framework use. This can have
>> a
>> default System.err style implementation, but the idea is to make it
>> easy
>> (and performant hopefully) to bridge into the end user's choice of
>> framework and configuration without actually requiring a real
>> logging
>> framework (at least until you want to use it in production). While
>> it seems
>> overkill, the problem is that neither JUL nor System.err are
>> sufficient for
>> logging. Even a simple API like Android's logging API can be good
>> enough to
>> abstract it in a small library.
>>
>> For a look at the very simplest route, you can see how Log4j2
>> handles
>> logging before any logging classes have been initialized. It's
>> basically a
>> configurable wrapper around System.err:
>>
>> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>>
>>
>>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com>
>>> wrote:
>>>
>>> You could also log to a pluggable print stream which could be sys
>>> err by
>>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as
>>> well :-)
>>>
>>> Gary
>>>
>>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com>
>>>> wrote:
>>>>
>>>> There’s a couple of considerations about doing logging in a
>>>> library, but
>>>> I’ll just mention a few:
>>>>
>>>> * dependencies
>>>> * performance
>>>> * ease of use
>>>>
>>>> * Dependencies*
>>>> Will the library be less attractive to users if it requires an
>>>> external
>>>> dependency? Then don’t introduce one (so: use system err or JUL).
>>>> On the
>>>> other hand, if the vast majority of usages is in a context with
>>>> many
>>> other
>>>> external libraries (like in a web container) you have more
>>>> freedom.
>>>>
>>>> *Performance*
>>>> Please take a look at the log4j 2 performance page (
>>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>>> Console
>>>> logging is 50x (yes fifty times) slower than file logging.
>>>> That’s a strong argument against system err logging. I’m not a fan
>>>> of
>>> JUL,
>>>> but if you need to avoid dependencies you’re better off using JUL,
>>>> that’s
>>>> only 5x slower than log4j. Also depends on how much logging you
>>>> expect to
>>>> do in the worst case.
>>>>
>>>> *Ease of use*
>>>> I’m biased and would say that Log4j 2 has the nicest and richest
>>>> API.
>>>> Console logging (System.err.printf) probably has the poorest API.
>>>> Other
>>>> libraries sit in the middle.
>>>>
>>>> *Final note*
>>>> I would never log to System out, always use system err instead.
>>>> This
>>>> allows programs using your library to pipe output to other
>>>> programs
>>> without
>>>> their output getting mixed with your library’s diagnostic output.
>>>>
>>>> Hope this helps,
>>>>
>>>> Remko
>>>>
>>>> (Shameless plug) Every java main() method deserves
>>>> http://picocli.info
>>>>
>>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>>> wrote:
>>>>>
>>>>> Hello Bruno.
>>>>>
>>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita
>>>>>> wrote:
>>>>>> Hi all,
>>>>>>
>>>>>>
>>>>>> I commented on IMAGING-154, but copying the last comment here as
>>>>>> it
>>>>>> contains the approach I would like to follow to fix the last
>>>>>> change in
>>>>>> the project blocking
>>>>>> a 1.0 release:
>>>>>>
>>>>>>
>>>>>> ---
>>>>>>
>>>>>> So went ahead to re-design the Debug class, in a way users could
>>>>>> still enable/disable debugging, and also use a PrintStream so
>>>>>> that
>>>>>> other thing rather than System.out could be used.
>>>>>>
>>>>>>
>>>>>>
>>>>>> Then, realized removing System.out was the natural next step.
>>>>>> But
>>>>>> alas, the library uses System.out for debugging, but sometimes
>>>>>> it uses
>>>>>> it for writing to System.out in a "verbose mode". What is more
>>>>>> complicated, is that sometimes classes methods like `toString()`
>>>>>> are
>>>>>> calling debug methods that receive a PrintStream already.
>>>>>>
>>>>>>
>>>>>>
>>>>>> So I spent some more time quickly comparing what other libraries
>>>>>> I've
>>>>>> seen being used / or used for image processing:
>>>>>>
>>>>
>>>
>>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>>>> .
>>>>>> Turns out only very low level libraries, such as the JNI bridge
>>>>>> for
>>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>>>>>> Exception's.
>>>>>>
>>>>>>
>>>>>>
>>>>>> All other libraries have one way or another of logging. Be it
>>>>>> with
>>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>>>>>
>>>>>>
>>>>>>
>>>>>> My preferred compromise for this ticket was to keep Debug,
>>>>>> making
>>>>>> System.out possible but optional, and mark the class internal
>>>>>> only.
>>>>>> Now my preferred solution is to keep the Debug internal, but add
>>>>>> a
>>>>>> logger to it. And then also add logging to replace where
>>>>>> System.out is
>>>>>> used for the "verbose" mode.
>>>>>> ---
>>>>>>
>>>>>>
>>>>>>
>>>>>> Any thoughts? Objections? If none, I will try to work on this
>>>>>> issue
>>>>>> next weekend, making the Debug class internal only, and
>>>>>> replacing
>>>>>> System.out by a logging utility. After that, we should be good
>>>>>> to
>>>>>> start preparing the vote for 1.0.
>>>>>>
>>>>>>
>>>>>>
>>>>>> * I know it's hard to get a consensus on having logging in
>>>>>> Commons
>>>>>> components, as we have normally low level libraries, where
>>>>>> using
>>>>>> logging is not always practical.
>>>>>
>>>>> There are Log4j2 experts reading here. It would be interesting
>>>>> to hear them about what is practical or not. There are several
>>>>> aspects to "practical": simplicity, flexibility, compatibility,
>>>>> performance, ...
>>>>> How does Log4j2 fare in these areas?
>>>>> Is there a known (through experience) limit in where it should
>>>>> be used?
>>>>>
>>>>>> But I would now argue that Java own
>>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and
>>>>>> Commons
>>>>>> Imaging are located at a higher level, some times even using it
>>>>>> for
>>>>>> basic image handling/parsing/reading.
>>>>>
>>>>> As with many discussions on this list, conflicting arguments
>>>>> occur
>>>>> because people lack common (!) definitions.
>>>>> So one goes: "You cannot do <something> in a low-level component"
>>>>> but does not define "low-level"...
>>>>>
>>>>>> * Feel free to cast a counter-argument for it, but please think
>>>>>> whether you'd still be -0, +0 for this change. We have delayed
>>>>>> 1.0 for
>>>>>> a while, so if you have a strong opinion on not adding a logger,
>>>>>> please provide an alternative for IMAGING-154.
>>>>>
>>>>>> Otherwise we may fail
>>>>>> to prepare a 1.0 release yet again, and then somebody else may
>>>>>> have to
>>>>>> work on it in a few months/years...
>>>>>
>>>>> We are there because the project is too rigid about itself as
>>>>> a whole (cf. for example the [RNG] thread about BC).
>>>>> IMHO, it's not the always least common denominator that is the
>>>>> best decision...
>>>>> As you noticed, components most easily stall in their development
>>>>> for lack of proper review, or risk acceptance (i.e. assume that
>>>>> those who are closer to the code (at a given time) probably know
>>>>> best... :-/
>>>>>
>>>>> My opinion is that we can take the risk to introduce logging, and
>>>>> if people complain somehow, take it back later.
>>>>>
>>>>>> one possible compromise for this,
>>>>>> might be i) make Debug internal,
>>>>>
>>>>> +1
>>>>>
>>>>> [Hmm... Does "internal" mean that minor release can break BC
>>>>> on such a class?]
>>>>>
>>>>>> ii) remove all System.out calls,
>>>>>
>>>>> +1 or
>>>>> -1
>>>>>
>>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>>>>> indeed used in low-level utilities but is the intent the same
>>>>> here?]
>>>>>
>>>>>> which means removing the verbose flags, the checks, and calls to
>>>>>> System.out in there.
>>>>>
>>>>> It would be a loss of potentially useful information (e.g. for
>>>>> debugging).
>>>>>
>>>>> Regards,
>>>>> Gilles
>>>>>
>>>>>>
>>>>>> Thanks!
>>>>>> Bruno
>>>>>>
>>>>>> ________________________________
>>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>>>>>> To: Commons Developers List <de...@commons.apache.org>
>>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> Hi sebb,
>>>>>>
>>>>>>> Another aspect of debugging is ensuring that methods are small
>>>>>>> and
>>>>>>
>>>>>>> easily tested independently.
>>>>>>> However this is difficult to do, and care must be taken to
>>>>>>> ensure
>>> that
>>>>>>> the public API is not unnecessarily extended..
>>>>>>
>>>>>> A very good point.
>>>>>>
>>>>>> The parsers in commons-imaging expose some #dump... methods
>>>>>> (
>>>>
>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>>>> ).
>>>>>>
>>>>>> While I can see that parsers may need to dump the data they are
>>>>>> holding in some structured way for inspecting, reporting,
>>>>>> serializing,
>>>>>> etc, it looks like some other classes were affected by it too.
>>>>>> For
>>>>>> example...
>>>>>>
>>>>>>
>>>>>> A JPEG Segment has a #dump() method
>>>>>>
>>>>>>
>>>>>>
>>>>
>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>>>>>
>>>>>>
>>>>>> which gets defined in each subclass of Segment. It can be
>>>>>> confusing
>>>>>> to have a method such as #dump() in a Segment, from the point of
>>>>>> view
>>>>>> of someone writing a photo editor for example. The user could
>>>>>> use that
>>>>>> to pass his/her own logger's PrintWriter, which would make
>>>>>> removing or
>>>>>> changing logging in the future in commons-imaging.
>>>>>>
>>>>>>
>>>>>> If we keep the Debug class, and make it internal, there would
>>>>>> still
>>>>>> be these methods to take care. And there are some methods where
>>>>>> users
>>>>>> can provide a PrintWriter, while others instead use System.out
>>>>>> (e.g.
>>>>
>>>
>>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>>>> ).
>>>>>>
>>>>>> Cheers
>>>>>> Bruno
>>>>>>
>>>>>> ________________________________
>>>>>> From: sebb <se...@gmail.com>
>>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>>>>>> Kinoshita <br...@yahoo.com.br>
>>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>>>>>> <br...@yahoo.com.br.invalid> wrote:
>>>>>>> Hi Jorg,
>>>>>>>
>>>>>>> I'd be fine with that solution too. I think this one would
>>>>>>> cause the
>>>> smaller change to the code as is.
>>>>>>>
>>>>>>> I believe my preference is still to remove the Debug class. But
>>>> between logging and making Debug internal only, I'd choose making
>>>> it
>>>> internal.
>>>>>>
>>>>>> +1
>>>>>>
>>>>>> I think making it internal means it can still be dropped later.
>>>>>>
>>>>>>> Looking forward to hearing what others think about these
>>>>>>> options.
>>>>>>>
>>>>>>
>>>>>> Another aspect of debugging is ensuring that methods are small
>>>>>> and
>>>>>> easily tested independently.
>>>>>> However this is difficult to do, and care must be taken to
>>>>>> ensure that
>>>>>> the public API is not unnecessarily extended..
>>>>>>
>>>>>>> Thanks
>>>>>>> Bruno
>>>>>>>
>>>>>>>
>>>>>>> ________________________________
>>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>>>>>> To: dev@commons.apache.org
>>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Hi Bruno,
>>>>>>>
>>>>>>>
>>>>>>> if it might also be helpful to our users, why not keep and
>>>>>>> provide
>>> it.
>>>> As
>>>>>>>
>>>>>>> I understand it, the Debug class is a tool helping in
>>>>>>> development to
>>>>>>>
>>>>>>> analyze some behavior.
>>>>>>>
>>>>>>>
>>>>>>> Nothing stops us from declaring this class internal (we might
>>>>>>> even
>>> put
>>>> it
>>>>>>>
>>>>>>> into a package "internal" or "debug") that might be changed
>>>>>>> without
>>>>>>>
>>>>>>> further comment. Nobody may rely on it in production code, but
>>>>>>> during
>>>>>>>
>>>>>>> development it might be helpful. With such an approach we might
>>>>>>> not
>>>> have
>>>>>>>
>>>>>>> a need to find a better interface to provide this
>>>>>>> functionality.
>>>>>>>
>>>>>>>
>>>>>>> Just my 2¢,
>>>>>>>
>>>>>>> Jörg
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>>>>>
>>>>>>>
>>>>>>>> Hello,
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> If memory serves me well, some time ago we had a discussion
>>>>>>>> around
>>>>>>>
>>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>>> commons-imaging
>>>>>>>
>>>>>>>> 1.0 was the Debug class.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> I finished the pull request, but Gilles raised an important
>>>>>>>> point,
>>>> about
>>>>>>>
>>>>>>>> discussing other alternatives first.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> Initially I am against logging in low level libraries,
>>>>>>>> especially
>>>>>>>
>>>>>>>> commons components. But some time ago I had to debug TIFF
>>>>>>>> issues in
>>>>>>>
>>>>>>>> commons-imaging, and having the dump methods was a tremendous
>>>>>>>> help.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> The issue is that some imaging algorithms/processing have a
>>>>>>>> lot of
>>>>>>>
>>>>>>>> variables that can be altered. And keeping an eye on all of
>>>>>>>> them in
>>>> the
>>>>>>>
>>>>>>>> debugger can be quite hard - though not impossible.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> So all in all, now I am more confident to proceed without the
>>>>>>>> Debug
>>>>>>>
>>>>>>>> class. But some users could have a hard time investigating
>>>>>>>> possible
>>>>>>>
>>>>>>>> issues in the library without seeing what's going on within
>>>>>>>> the
>>>> library.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> IMO, that could be solved with the logging/dump features... or
>>>> through a
>>>>>>>
>>>>>>>> better design, especially around exception handling/throwing.
>>>>>>>> The
>>>> latter
>>>>>>>
>>>>>>>> is my preferred approach. Instead of logging, I prefer -
>>>>>>>> whenever
>>>>>>>
>>>>>>>> possible - that low level libraries throw exceptions and let
>>>>>>>> me
>>> handle
>>>>>>>
>>>>>>>> the logging.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0
>>>>>>>> to a
>>>>>>>
>>>>>>>> logging added to commons-imaging.
>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>> Bruno
>>>>>
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>>
>>>>
>>>
>>
>>
>> --
>> Matt Sicker <bo...@gmail.com>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Right now that's where I am standing too. If adding a dependency to log4j is a no-no, then I'd probably check if jul would be OK, or otherwise maybe import just Log4J's LowLevelLogUtil into the project would work?
Commons DBCP, Commons Configuration, Commons Beanutils, Commons JEXL, and Commons Validator. All of these have a compile dependency to Commons Logging. So it wouldn't be creating a new precedent.
Commons Pool and Commons Compress have some optional dependencies, but none for logging... maybe an optional dependency, with disabling the logging by default **could** work?
Cheers
Bruno
________________________________
From: Remko Popma <re...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Monday, 13 August 2018 9:50 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
If you want to avoid a dependency I would not create a custom logging abstraction but just use JUL. Most logging libraries have JUL adapters so clients can do the bridging on their side.
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>
> What I've seen done when trying to avoid a logging API dependency is to
> create a minimal logging API purely for framework use. This can have a
> default System.err style implementation, but the idea is to make it easy
> (and performant hopefully) to bridge into the end user's choice of
> framework and configuration without actually requiring a real logging
> framework (at least until you want to use it in production). While it seems
> overkill, the problem is that neither JUL nor System.err are sufficient for
> logging. Even a simple API like Android's logging API can be good enough to
> abstract it in a small library.
>
> For a look at the very simplest route, you can see how Log4j2 handles
> logging before any logging classes have been initialized. It's basically a
> configurable wrapper around System.err:
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>
>
>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
>>
>> You could also log to a pluggable print stream which could be sys err by
>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>>
>> Gary
>>
>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>>>
>>> There’s a couple of considerations about doing logging in a library, but
>>> I’ll just mention a few:
>>>
>>> * dependencies
>>> * performance
>>> * ease of use
>>>
>>> * Dependencies*
>>> Will the library be less attractive to users if it requires an external
>>> dependency? Then don’t introduce one (so: use system err or JUL). On the
>>> other hand, if the vast majority of usages is in a context with many
>> other
>>> external libraries (like in a web container) you have more freedom.
>>>
>>> *Performance*
>>> Please take a look at the log4j 2 performance page (
>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>> Console
>>> logging is 50x (yes fifty times) slower than file logging.
>>> That’s a strong argument against system err logging. I’m not a fan of
>> JUL,
>>> but if you need to avoid dependencies you’re better off using JUL, that’s
>>> only 5x slower than log4j. Also depends on how much logging you expect to
>>> do in the worst case.
>>>
>>> *Ease of use*
>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
>>> Console logging (System.err.printf) probably has the poorest API. Other
>>> libraries sit in the middle.
>>>
>>> *Final note*
>>> I would never log to System out, always use system err instead. This
>>> allows programs using your library to pipe output to other programs
>> without
>>> their output getting mixed with your library’s diagnostic output.
>>>
>>> Hope this helps,
>>>
>>> Remko
>>>
>>> (Shameless plug) Every java main() method deserves http://picocli.info
>>>
>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>> wrote:
>>>>
>>>> Hello Bruno.
>>>>
>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>>>>> Hi all,
>>>>>
>>>>>
>>>>> I commented on IMAGING-154, but copying the last comment here as it
>>>>> contains the approach I would like to follow to fix the last change in
>>>>> the project blocking
>>>>> a 1.0 release:
>>>>>
>>>>>
>>>>> ---
>>>>>
>>>>> So went ahead to re-design the Debug class, in a way users could
>>>>> still enable/disable debugging, and also use a PrintStream so that
>>>>> other thing rather than System.out could be used.
>>>>>
>>>>>
>>>>>
>>>>> Then, realized removing System.out was the natural next step. But
>>>>> alas, the library uses System.out for debugging, but sometimes it uses
>>>>> it for writing to System.out in a "verbose mode". What is more
>>>>> complicated, is that sometimes classes methods like `toString()` are
>>>>> calling debug methods that receive a PrintStream already.
>>>>>
>>>>>
>>>>>
>>>>> So I spent some more time quickly comparing what other libraries I've
>>>>> seen being used / or used for image processing:
>>>>>
>>>
>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>>> .
>>>>> Turns out only very low level libraries, such as the JNI bridge for
>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>>>>> Exception's.
>>>>>
>>>>>
>>>>>
>>>>> All other libraries have one way or another of logging. Be it with
>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>>>>
>>>>>
>>>>>
>>>>> My preferred compromise for this ticket was to keep Debug, making
>>>>> System.out possible but optional, and mark the class internal only.
>>>>> Now my preferred solution is to keep the Debug internal, but add a
>>>>> logger to it. And then also add logging to replace where System.out is
>>>>> used for the "verbose" mode.
>>>>> ---
>>>>>
>>>>>
>>>>>
>>>>> Any thoughts? Objections? If none, I will try to work on this issue
>>>>> next weekend, making the Debug class internal only, and replacing
>>>>> System.out by a logging utility. After that, we should be good to
>>>>> start preparing the vote for 1.0.
>>>>>
>>>>>
>>>>>
>>>>> * I know it's hard to get a consensus on having logging in Commons
>>>>> components, as we have normally low level libraries, where using
>>>>> logging is not always practical.
>>>>
>>>> There are Log4j2 experts reading here. It would be interesting
>>>> to hear them about what is practical or not. There are several
>>>> aspects to "practical": simplicity, flexibility, compatibility,
>>>> performance, ...
>>>> How does Log4j2 fare in these areas?
>>>> Is there a known (through experience) limit in where it should
>>>> be used?
>>>>
>>>>> But I would now argue that Java own
>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>>>>> Imaging are located at a higher level, some times even using it for
>>>>> basic image handling/parsing/reading.
>>>>
>>>> As with many discussions on this list, conflicting arguments occur
>>>> because people lack common (!) definitions.
>>>> So one goes: "You cannot do <something> in a low-level component"
>>>> but does not define "low-level"...
>>>>
>>>>> * Feel free to cast a counter-argument for it, but please think
>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>>>>> a while, so if you have a strong opinion on not adding a logger,
>>>>> please provide an alternative for IMAGING-154.
>>>>
>>>>> Otherwise we may fail
>>>>> to prepare a 1.0 release yet again, and then somebody else may have to
>>>>> work on it in a few months/years...
>>>>
>>>> We are there because the project is too rigid about itself as
>>>> a whole (cf. for example the [RNG] thread about BC).
>>>> IMHO, it's not the always least common denominator that is the
>>>> best decision...
>>>> As you noticed, components most easily stall in their development
>>>> for lack of proper review, or risk acceptance (i.e. assume that
>>>> those who are closer to the code (at a given time) probably know
>>>> best... :-/
>>>>
>>>> My opinion is that we can take the risk to introduce logging, and
>>>> if people complain somehow, take it back later.
>>>>
>>>>> one possible compromise for this,
>>>>> might be i) make Debug internal,
>>>>
>>>> +1
>>>>
>>>> [Hmm... Does "internal" mean that minor release can break BC
>>>> on such a class?]
>>>>
>>>>> ii) remove all System.out calls,
>>>>
>>>> +1 or
>>>> -1
>>>>
>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>>>> indeed used in low-level utilities but is the intent the same
>>>> here?]
>>>>
>>>>> which means removing the verbose flags, the checks, and calls to
>>>>> System.out in there.
>>>>
>>>> It would be a loss of potentially useful information (e.g. for
>>>> debugging).
>>>>
>>>> Regards,
>>>> Gilles
>>>>
>>>>>
>>>>> Thanks!
>>>>> Bruno
>>>>>
>>>>> ________________________________
>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>>>>> To: Commons Developers List <de...@commons.apache.org>
>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>
>>>>>
>>>>>
>>>>> Hi sebb,
>>>>>
>>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>>
>>>>>> easily tested independently.
>>>>>> However this is difficult to do, and care must be taken to ensure
>> that
>>>>>> the public API is not unnecessarily extended..
>>>>>
>>>>> A very good point.
>>>>>
>>>>> The parsers in commons-imaging expose some #dump... methods
>>>>> (
>>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>>> ).
>>>>>
>>>>> While I can see that parsers may need to dump the data they are
>>>>> holding in some structured way for inspecting, reporting, serializing,
>>>>> etc, it looks like some other classes were affected by it too. For
>>>>> example...
>>>>>
>>>>>
>>>>> A JPEG Segment has a #dump() method
>>>>>
>>>>>
>>>>>
>>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>>>>
>>>>>
>>>>> which gets defined in each subclass of Segment. It can be confusing
>>>>> to have a method such as #dump() in a Segment, from the point of view
>>>>> of someone writing a photo editor for example. The user could use that
>>>>> to pass his/her own logger's PrintWriter, which would make removing or
>>>>> changing logging in the future in commons-imaging.
>>>>>
>>>>>
>>>>> If we keep the Debug class, and make it internal, there would still
>>>>> be these methods to take care. And there are some methods where users
>>>>> can provide a PrintWriter, while others instead use System.out
>>>>> (e.g.
>>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>>> ).
>>>>>
>>>>> Cheers
>>>>> Bruno
>>>>>
>>>>> ________________________________
>>>>> From: sebb <se...@gmail.com>
>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>>>>> Kinoshita <br...@yahoo.com.br>
>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>
>>>>>
>>>>>
>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>>>>> <br...@yahoo.com.br.invalid> wrote:
>>>>>> Hi Jorg,
>>>>>>
>>>>>> I'd be fine with that solution too. I think this one would cause the
>>> smaller change to the code as is.
>>>>>>
>>>>>> I believe my preference is still to remove the Debug class. But
>>> between logging and making Debug internal only, I'd choose making it
>>> internal.
>>>>>
>>>>> +1
>>>>>
>>>>> I think making it internal means it can still be dropped later.
>>>>>
>>>>>> Looking forward to hearing what others think about these options.
>>>>>>
>>>>>
>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>> easily tested independently.
>>>>> However this is difficult to do, and care must be taken to ensure that
>>>>> the public API is not unnecessarily extended..
>>>>>
>>>>>> Thanks
>>>>>> Bruno
>>>>>>
>>>>>>
>>>>>> ________________________________
>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>>>>> To: dev@commons.apache.org
>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> Hi Bruno,
>>>>>>
>>>>>>
>>>>>> if it might also be helpful to our users, why not keep and provide
>> it.
>>> As
>>>>>>
>>>>>> I understand it, the Debug class is a tool helping in development to
>>>>>>
>>>>>> analyze some behavior.
>>>>>>
>>>>>>
>>>>>> Nothing stops us from declaring this class internal (we might even
>> put
>>> it
>>>>>>
>>>>>> into a package "internal" or "debug") that might be changed without
>>>>>>
>>>>>> further comment. Nobody may rely on it in production code, but during
>>>>>>
>>>>>> development it might be helpful. With such an approach we might not
>>> have
>>>>>>
>>>>>> a need to find a better interface to provide this functionality.
>>>>>>
>>>>>>
>>>>>> Just my 2¢,
>>>>>>
>>>>>> Jörg
>>>>>>
>>>>>>
>>>>>>
>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>>>>
>>>>>>
>>>>>>> Hello,
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> If memory serves me well, some time ago we had a discussion around
>>>>>>
>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>> commons-imaging
>>>>>>
>>>>>>> 1.0 was the Debug class.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> I finished the pull request, but Gilles raised an important point,
>>> about
>>>>>>
>>>>>>> discussing other alternatives first.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> Initially I am against logging in low level libraries, especially
>>>>>>
>>>>>>> commons components. But some time ago I had to debug TIFF issues in
>>>>>>
>>>>>>> commons-imaging, and having the dump methods was a tremendous help.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> The issue is that some imaging algorithms/processing have a lot of
>>>>>>
>>>>>>> variables that can be altered. And keeping an eye on all of them in
>>> the
>>>>>>
>>>>>>> debugger can be quite hard - though not impossible.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> So all in all, now I am more confident to proceed without the Debug
>>>>>>
>>>>>>> class. But some users could have a hard time investigating possible
>>>>>>
>>>>>>> issues in the library without seeing what's going on within the
>>> library.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> IMO, that could be solved with the logging/dump features... or
>>> through a
>>>>>>
>>>>>>> better design, especially around exception handling/throwing. The
>>> latter
>>>>>>
>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>>>>>
>>>>>>> possible - that low level libraries throw exceptions and let me
>> handle
>>>>>>
>>>>>>> the logging.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>>>>>
>>>>>>> logging added to commons-imaging.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> Bruno
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>
>>>
>>
>
>
> --
> Matt Sicker <bo...@gmail.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Remko Popma <re...@gmail.com>.
If you want to avoid a dependency I would not create a custom logging abstraction but just use JUL. Most logging libraries have JUL adapters so clients can do the bridging on their side.
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 13, 2018, at 0:17, Matt Sicker <bo...@gmail.com> wrote:
>
> What I've seen done when trying to avoid a logging API dependency is to
> create a minimal logging API purely for framework use. This can have a
> default System.err style implementation, but the idea is to make it easy
> (and performant hopefully) to bridge into the end user's choice of
> framework and configuration without actually requiring a real logging
> framework (at least until you want to use it in production). While it seems
> overkill, the problem is that neither JUL nor System.err are sufficient for
> logging. Even a simple API like Android's logging API can be good enough to
> abstract it in a small library.
>
> For a look at the very simplest route, you can see how Log4j2 handles
> logging before any logging classes have been initialized. It's basically a
> configurable wrapper around System.err:
> https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
>
>
>> On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
>>
>> You could also log to a pluggable print stream which could be sys err by
>> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>>
>> Gary
>>
>>> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>>>
>>> There’s a couple of considerations about doing logging in a library, but
>>> I’ll just mention a few:
>>>
>>> * dependencies
>>> * performance
>>> * ease of use
>>>
>>> * Dependencies*
>>> Will the library be less attractive to users if it requires an external
>>> dependency? Then don’t introduce one (so: use system err or JUL). On the
>>> other hand, if the vast majority of usages is in a context with many
>> other
>>> external libraries (like in a web container) you have more freedom.
>>>
>>> *Performance*
>>> Please take a look at the log4j 2 performance page (
>>> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
>> Console
>>> logging is 50x (yes fifty times) slower than file logging.
>>> That’s a strong argument against system err logging. I’m not a fan of
>> JUL,
>>> but if you need to avoid dependencies you’re better off using JUL, that’s
>>> only 5x slower than log4j. Also depends on how much logging you expect to
>>> do in the worst case.
>>>
>>> *Ease of use*
>>> I’m biased and would say that Log4j 2 has the nicest and richest API.
>>> Console logging (System.err.printf) probably has the poorest API. Other
>>> libraries sit in the middle.
>>>
>>> *Final note*
>>> I would never log to System out, always use system err instead. This
>>> allows programs using your library to pipe output to other programs
>> without
>>> their output getting mixed with your library’s diagnostic output.
>>>
>>> Hope this helps,
>>>
>>> Remko
>>>
>>> (Shameless plug) Every java main() method deserves http://picocli.info
>>>
>>>> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
>> wrote:
>>>>
>>>> Hello Bruno.
>>>>
>>>>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>>>>> Hi all,
>>>>>
>>>>>
>>>>> I commented on IMAGING-154, but copying the last comment here as it
>>>>> contains the approach I would like to follow to fix the last change in
>>>>> the project blocking
>>>>> a 1.0 release:
>>>>>
>>>>>
>>>>> ---
>>>>>
>>>>> So went ahead to re-design the Debug class, in a way users could
>>>>> still enable/disable debugging, and also use a PrintStream so that
>>>>> other thing rather than System.out could be used.
>>>>>
>>>>>
>>>>>
>>>>> Then, realized removing System.out was the natural next step. But
>>>>> alas, the library uses System.out for debugging, but sometimes it uses
>>>>> it for writing to System.out in a "verbose mode". What is more
>>>>> complicated, is that sometimes classes methods like `toString()` are
>>>>> calling debug methods that receive a PrintStream already.
>>>>>
>>>>>
>>>>>
>>>>> So I spent some more time quickly comparing what other libraries I've
>>>>> seen being used / or used for image processing:
>>>>>
>>>
>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
>>> .
>>>>> Turns out only very low level libraries, such as the JNI bridge for
>>>>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>>>>> Exception's.
>>>>>
>>>>>
>>>>>
>>>>> All other libraries have one way or another of logging. Be it with
>>>>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>>>>
>>>>>
>>>>>
>>>>> My preferred compromise for this ticket was to keep Debug, making
>>>>> System.out possible but optional, and mark the class internal only.
>>>>> Now my preferred solution is to keep the Debug internal, but add a
>>>>> logger to it. And then also add logging to replace where System.out is
>>>>> used for the "verbose" mode.
>>>>> ---
>>>>>
>>>>>
>>>>>
>>>>> Any thoughts? Objections? If none, I will try to work on this issue
>>>>> next weekend, making the Debug class internal only, and replacing
>>>>> System.out by a logging utility. After that, we should be good to
>>>>> start preparing the vote for 1.0.
>>>>>
>>>>>
>>>>>
>>>>> * I know it's hard to get a consensus on having logging in Commons
>>>>> components, as we have normally low level libraries, where using
>>>>> logging is not always practical.
>>>>
>>>> There are Log4j2 experts reading here. It would be interesting
>>>> to hear them about what is practical or not. There are several
>>>> aspects to "practical": simplicity, flexibility, compatibility,
>>>> performance, ...
>>>> How does Log4j2 fare in these areas?
>>>> Is there a known (through experience) limit in where it should
>>>> be used?
>>>>
>>>>> But I would now argue that Java own
>>>>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>>>>> Imaging are located at a higher level, some times even using it for
>>>>> basic image handling/parsing/reading.
>>>>
>>>> As with many discussions on this list, conflicting arguments occur
>>>> because people lack common (!) definitions.
>>>> So one goes: "You cannot do <something> in a low-level component"
>>>> but does not define "low-level"...
>>>>
>>>>> * Feel free to cast a counter-argument for it, but please think
>>>>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>>>>> a while, so if you have a strong opinion on not adding a logger,
>>>>> please provide an alternative for IMAGING-154.
>>>>
>>>>> Otherwise we may fail
>>>>> to prepare a 1.0 release yet again, and then somebody else may have to
>>>>> work on it in a few months/years...
>>>>
>>>> We are there because the project is too rigid about itself as
>>>> a whole (cf. for example the [RNG] thread about BC).
>>>> IMHO, it's not the always least common denominator that is the
>>>> best decision...
>>>> As you noticed, components most easily stall in their development
>>>> for lack of proper review, or risk acceptance (i.e. assume that
>>>> those who are closer to the code (at a given time) probably know
>>>> best... :-/
>>>>
>>>> My opinion is that we can take the risk to introduce logging, and
>>>> if people complain somehow, take it back later.
>>>>
>>>>> one possible compromise for this,
>>>>> might be i) make Debug internal,
>>>>
>>>> +1
>>>>
>>>> [Hmm... Does "internal" mean that minor release can break BC
>>>> on such a class?]
>>>>
>>>>> ii) remove all System.out calls,
>>>>
>>>> +1 or
>>>> -1
>>>>
>>>> [Depends on what "low-level" means here. "stdout"/"stderr" is
>>>> indeed used in low-level utilities but is the intent the same
>>>> here?]
>>>>
>>>>> which means removing the verbose flags, the checks, and calls to
>>>>> System.out in there.
>>>>
>>>> It would be a loss of potentially useful information (e.g. for
>>>> debugging).
>>>>
>>>> Regards,
>>>> Gilles
>>>>
>>>>>
>>>>> Thanks!
>>>>> Bruno
>>>>>
>>>>> ________________________________
>>>>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>>>>> To: Commons Developers List <de...@commons.apache.org>
>>>>> Sent: Tuesday, 6 February 2018 11:30 PM
>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>
>>>>>
>>>>>
>>>>> Hi sebb,
>>>>>
>>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>>
>>>>>> easily tested independently.
>>>>>> However this is difficult to do, and care must be taken to ensure
>> that
>>>>>> the public API is not unnecessarily extended..
>>>>>
>>>>> A very good point.
>>>>>
>>>>> The parsers in commons-imaging expose some #dump... methods
>>>>> (
>>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
>>> ).
>>>>>
>>>>> While I can see that parsers may need to dump the data they are
>>>>> holding in some structured way for inspecting, reporting, serializing,
>>>>> etc, it looks like some other classes were affected by it too. For
>>>>> example...
>>>>>
>>>>>
>>>>> A JPEG Segment has a #dump() method
>>>>>
>>>>>
>>>>>
>>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>>>>
>>>>>
>>>>> which gets defined in each subclass of Segment. It can be confusing
>>>>> to have a method such as #dump() in a Segment, from the point of view
>>>>> of someone writing a photo editor for example. The user could use that
>>>>> to pass his/her own logger's PrintWriter, which would make removing or
>>>>> changing logging in the future in commons-imaging.
>>>>>
>>>>>
>>>>> If we keep the Debug class, and make it internal, there would still
>>>>> be these methods to take care. And there are some methods where users
>>>>> can provide a PrintWriter, while others instead use System.out
>>>>> (e.g.
>>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
>>> ).
>>>>>
>>>>> Cheers
>>>>> Bruno
>>>>>
>>>>> ________________________________
>>>>> From: sebb <se...@gmail.com>
>>>>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>>>>> Kinoshita <br...@yahoo.com.br>
>>>>> Sent: Tuesday, 6 February 2018 11:06 PM
>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>
>>>>>
>>>>>
>>>>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>>>>> <br...@yahoo.com.br.invalid> wrote:
>>>>>> Hi Jorg,
>>>>>>
>>>>>> I'd be fine with that solution too. I think this one would cause the
>>> smaller change to the code as is.
>>>>>>
>>>>>> I believe my preference is still to remove the Debug class. But
>>> between logging and making Debug internal only, I'd choose making it
>>> internal.
>>>>>
>>>>> +1
>>>>>
>>>>> I think making it internal means it can still be dropped later.
>>>>>
>>>>>> Looking forward to hearing what others think about these options.
>>>>>>
>>>>>
>>>>> Another aspect of debugging is ensuring that methods are small and
>>>>> easily tested independently.
>>>>> However this is difficult to do, and care must be taken to ensure that
>>>>> the public API is not unnecessarily extended..
>>>>>
>>>>>> Thanks
>>>>>> Bruno
>>>>>>
>>>>>>
>>>>>> ________________________________
>>>>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>>>>> To: dev@commons.apache.org
>>>>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>>>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>>>>
>>>>>>
>>>>>>
>>>>>> Hi Bruno,
>>>>>>
>>>>>>
>>>>>> if it might also be helpful to our users, why not keep and provide
>> it.
>>> As
>>>>>>
>>>>>> I understand it, the Debug class is a tool helping in development to
>>>>>>
>>>>>> analyze some behavior.
>>>>>>
>>>>>>
>>>>>> Nothing stops us from declaring this class internal (we might even
>> put
>>> it
>>>>>>
>>>>>> into a package "internal" or "debug") that might be changed without
>>>>>>
>>>>>> further comment. Nobody may rely on it in production code, but during
>>>>>>
>>>>>> development it might be helpful. With such an approach we might not
>>> have
>>>>>>
>>>>>> a need to find a better interface to provide this functionality.
>>>>>>
>>>>>>
>>>>>> Just my 2¢,
>>>>>>
>>>>>> Jörg
>>>>>>
>>>>>>
>>>>>>
>>>>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>>>>
>>>>>>
>>>>>>> Hello,
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> If memory serves me well, some time ago we had a discussion around
>>>>>>
>>>>>>> sanselan & commons-imaging 1.0. One of the issues with
>> commons-imaging
>>>>>>
>>>>>>> 1.0 was the Debug class.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> I finished the pull request, but Gilles raised an important point,
>>> about
>>>>>>
>>>>>>> discussing other alternatives first.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> Initially I am against logging in low level libraries, especially
>>>>>>
>>>>>>> commons components. But some time ago I had to debug TIFF issues in
>>>>>>
>>>>>>> commons-imaging, and having the dump methods was a tremendous help.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> The issue is that some imaging algorithms/processing have a lot of
>>>>>>
>>>>>>> variables that can be altered. And keeping an eye on all of them in
>>> the
>>>>>>
>>>>>>> debugger can be quite hard - though not impossible.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> So all in all, now I am more confident to proceed without the Debug
>>>>>>
>>>>>>> class. But some users could have a hard time investigating possible
>>>>>>
>>>>>>> issues in the library without seeing what's going on within the
>>> library.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> IMO, that could be solved with the logging/dump features... or
>>> through a
>>>>>>
>>>>>>> better design, especially around exception handling/throwing. The
>>> latter
>>>>>>
>>>>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>>>>>
>>>>>>> possible - that low level libraries throw exceptions and let me
>> handle
>>>>>>
>>>>>>> the logging.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>>>>>
>>>>>>> logging added to commons-imaging.
>>>>>>
>>>>>>>
>>>>>>
>>>>>>> Bruno
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>
>>>
>>
>
>
> --
> Matt Sicker <bo...@gmail.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi Matt!
>What I've seen done when trying to avoid a logging API dependency is to
>create a minimal logging API purely for framework use.
I've seen that happening in some projects, and not only in Java. I'd prefer to use a logging library to simply the code maintenance for now, if possible.
>While it seems
>overkill, the problem is that neither JUL nor System.err are sufficient for
>logging.
Indeed, +1.
>Even a simple API like Android's logging API can be good enough to
>abstract it in a small library.
That's exactly what opencv's android library did.
>For a look at the very simplest route, you can see how Log4j2 handles
>logging before any logging classes have been initialized. It's basically a
>configurable wrapper around System.err:
>https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
Thanks for the link! Log4J is probably one of the dependencies in my projects that I have used the longer (I remember using it in 2004), but thinking now... I believe I never looked at its source code.
Well, LowLevelLogUtil would probably do the trick. Perhaps we could copy just this class in the project... good food for thought Matt, thanks!
Cheers
Bruno
________________________________
From: Matt Sicker <bo...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Monday, 13 August 2018 3:17 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
What I've seen done when trying to avoid a logging API dependency is to
create a minimal logging API purely for framework use. This can have a
default System.err style implementation, but the idea is to make it easy
(and performant hopefully) to bridge into the end user's choice of
framework and configuration without actually requiring a real logging
framework (at least until you want to use it in production). While it seems
overkill, the problem is that neither JUL nor System.err are sufficient for
logging. Even a simple API like Android's logging API can be good enough to
abstract it in a small library.
For a look at the very simplest route, you can see how Log4j2 handles
logging before any logging classes have been initialized. It's basically a
configurable wrapper around System.err:
https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
> You could also log to a pluggable print stream which could be sys err by
> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>
> Gary
>
> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>
> > There’s a couple of considerations about doing logging in a library, but
> > I’ll just mention a few:
> >
> > * dependencies
> > * performance
> > * ease of use
> >
> > * Dependencies*
> > Will the library be less attractive to users if it requires an external
> > dependency? Then don’t introduce one (so: use system err or JUL). On the
> > other hand, if the vast majority of usages is in a context with many
> other
> > external libraries (like in a web container) you have more freedom.
> >
> > *Performance*
> > Please take a look at the log4j 2 performance page (
> > https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
> Console
> > logging is 50x (yes fifty times) slower than file logging.
> > That’s a strong argument against system err logging. I’m not a fan of
> JUL,
> > but if you need to avoid dependencies you’re better off using JUL, that’s
> > only 5x slower than log4j. Also depends on how much logging you expect to
> > do in the worst case.
> >
> > *Ease of use*
> > I’m biased and would say that Log4j 2 has the nicest and richest API.
> > Console logging (System.err.printf) probably has the poorest API. Other
> > libraries sit in the middle.
> >
> > *Final note*
> > I would never log to System out, always use system err instead. This
> > allows programs using your library to pipe output to other programs
> without
> > their output getting mixed with your library’s diagnostic output.
> >
> > Hope this helps,
> >
> > Remko
> >
> > (Shameless plug) Every java main() method deserves http://picocli.info
> >
> > > On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
> wrote:
> > >
> > > Hello Bruno.
> > >
> > >> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> > >> Hi all,
> > >>
> > >>
> > >> I commented on IMAGING-154, but copying the last comment here as it
> > >> contains the approach I would like to follow to fix the last change in
> > >> the project blocking
> > >> a 1.0 release:
> > >>
> > >>
> > >> ---
> > >>
> > >> So went ahead to re-design the Debug class, in a way users could
> > >> still enable/disable debugging, and also use a PrintStream so that
> > >> other thing rather than System.out could be used.
> > >>
> > >>
> > >>
> > >> Then, realized removing System.out was the natural next step. But
> > >> alas, the library uses System.out for debugging, but sometimes it uses
> > >> it for writing to System.out in a "verbose mode". What is more
> > >> complicated, is that sometimes classes methods like `toString()` are
> > >> calling debug methods that receive a PrintStream already.
> > >>
> > >>
> > >>
> > >> So I spent some more time quickly comparing what other libraries I've
> > >> seen being used / or used for image processing:
> > >>
> >
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> > .
> > >> Turns out only very low level libraries, such as the JNI bridge for
> > >> OpenCV, im4java, and Java's ImageIO can do with just throwing
> > >> Exception's.
> > >>
> > >>
> > >>
> > >> All other libraries have one way or another of logging. Be it with
> > >> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> > >>
> > >>
> > >>
> > >> My preferred compromise for this ticket was to keep Debug, making
> > >> System.out possible but optional, and mark the class internal only.
> > >> Now my preferred solution is to keep the Debug internal, but add a
> > >> logger to it. And then also add logging to replace where System.out is
> > >> used for the "verbose" mode.
> > >> ---
> > >>
> > >>
> > >>
> > >> Any thoughts? Objections? If none, I will try to work on this issue
> > >> next weekend, making the Debug class internal only, and replacing
> > >> System.out by a logging utility. After that, we should be good to
> > >> start preparing the vote for 1.0.
> > >>
> > >>
> > >>
> > >> * I know it's hard to get a consensus on having logging in Commons
> > >> components, as we have normally low level libraries, where using
> > >> logging is not always practical.
> > >
> > > There are Log4j2 experts reading here. It would be interesting
> > > to hear them about what is practical or not. There are several
> > > aspects to "practical": simplicity, flexibility, compatibility,
> > > performance, ...
> > > How does Log4j2 fare in these areas?
> > > Is there a known (through experience) limit in where it should
> > > be used?
> > >
> > >> But I would now argue that Java own
> > >> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
> > >> Imaging are located at a higher level, some times even using it for
> > >> basic image handling/parsing/reading.
> > >
> > > As with many discussions on this list, conflicting arguments occur
> > > because people lack common (!) definitions.
> > > So one goes: "You cannot do <something> in a low-level component"
> > > but does not define "low-level"...
> > >
> > >> * Feel free to cast a counter-argument for it, but please think
> > >> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
> > >> a while, so if you have a strong opinion on not adding a logger,
> > >> please provide an alternative for IMAGING-154.
> > >
> > >> Otherwise we may fail
> > >> to prepare a 1.0 release yet again, and then somebody else may have to
> > >> work on it in a few months/years...
> > >
> > > We are there because the project is too rigid about itself as
> > > a whole (cf. for example the [RNG] thread about BC).
> > > IMHO, it's not the always least common denominator that is the
> > > best decision...
> > > As you noticed, components most easily stall in their development
> > > for lack of proper review, or risk acceptance (i.e. assume that
> > > those who are closer to the code (at a given time) probably know
> > > best... :-/
> > >
> > > My opinion is that we can take the risk to introduce logging, and
> > > if people complain somehow, take it back later.
> > >
> > >> one possible compromise for this,
> > >> might be i) make Debug internal,
> > >
> > > +1
> > >
> > > [Hmm... Does "internal" mean that minor release can break BC
> > > on such a class?]
> > >
> > >> ii) remove all System.out calls,
> > >
> > > +1 or
> > > -1
> > >
> > > [Depends on what "low-level" means here. "stdout"/"stderr" is
> > > indeed used in low-level utilities but is the intent the same
> > > here?]
> > >
> > >> which means removing the verbose flags, the checks, and calls to
> > >> System.out in there.
> > >
> > > It would be a loss of potentially useful information (e.g. for
> > > debugging).
> > >
> > > Regards,
> > > Gilles
> > >
> > >>
> > >> Thanks!
> > >> Bruno
> > >>
> > >> ________________________________
> > >> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> > >> To: Commons Developers List <de...@commons.apache.org>
> > >> Sent: Tuesday, 6 February 2018 11:30 PM
> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >>
> > >>
> > >>
> > >> Hi sebb,
> > >>
> > >>> Another aspect of debugging is ensuring that methods are small and
> > >>
> > >>> easily tested independently.
> > >>> However this is difficult to do, and care must be taken to ensure
> that
> > >>> the public API is not unnecessarily extended..
> > >>
> > >> A very good point.
> > >>
> > >> The parsers in commons-imaging expose some #dump... methods
> > >> (
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> > ).
> > >>
> > >> While I can see that parsers may need to dump the data they are
> > >> holding in some structured way for inspecting, reporting, serializing,
> > >> etc, it looks like some other classes were affected by it too. For
> > >> example...
> > >>
> > >>
> > >> A JPEG Segment has a #dump() method
> > >>
> > >>
> > >>
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> > >>
> > >>
> > >> which gets defined in each subclass of Segment. It can be confusing
> > >> to have a method such as #dump() in a Segment, from the point of view
> > >> of someone writing a photo editor for example. The user could use that
> > >> to pass his/her own logger's PrintWriter, which would make removing or
> > >> changing logging in the future in commons-imaging.
> > >>
> > >>
> > >> If we keep the Debug class, and make it internal, there would still
> > >> be these methods to take care. And there are some methods where users
> > >> can provide a PrintWriter, while others instead use System.out
> > >> (e.g.
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> > ).
> > >>
> > >> Cheers
> > >> Bruno
> > >>
> > >> ________________________________
> > >> From: sebb <se...@gmail.com>
> > >> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> > >> Kinoshita <br...@yahoo.com.br>
> > >> Sent: Tuesday, 6 February 2018 11:06 PM
> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >>
> > >>
> > >>
> > >> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> > >> <br...@yahoo.com.br.invalid> wrote:
> > >>> Hi Jorg,
> > >>>
> > >>> I'd be fine with that solution too. I think this one would cause the
> > smaller change to the code as is.
> > >>>
> > >>> I believe my preference is still to remove the Debug class. But
> > between logging and making Debug internal only, I'd choose making it
> > internal.
> > >>
> > >> +1
> > >>
> > >> I think making it internal means it can still be dropped later.
> > >>
> > >>> Looking forward to hearing what others think about these options.
> > >>>
> > >>
> > >> Another aspect of debugging is ensuring that methods are small and
> > >> easily tested independently.
> > >> However this is difficult to do, and care must be taken to ensure that
> > >> the public API is not unnecessarily extended..
> > >>
> > >>> Thanks
> > >>> Bruno
> > >>>
> > >>>
> > >>> ________________________________
> > >>> From: Jörg Schaible <jo...@bpm-inspire.com>
> > >>> To: dev@commons.apache.org
> > >>> Sent: Tuesday, 6 February 2018 9:24 PM
> > >>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >>>
> > >>>
> > >>>
> > >>> Hi Bruno,
> > >>>
> > >>>
> > >>> if it might also be helpful to our users, why not keep and provide
> it.
> > As
> > >>>
> > >>> I understand it, the Debug class is a tool helping in development to
> > >>>
> > >>> analyze some behavior.
> > >>>
> > >>>
> > >>> Nothing stops us from declaring this class internal (we might even
> put
> > it
> > >>>
> > >>> into a package "internal" or "debug") that might be changed without
> > >>>
> > >>> further comment. Nobody may rely on it in production code, but during
> > >>>
> > >>> development it might be helpful. With such an approach we might not
> > have
> > >>>
> > >>> a need to find a better interface to provide this functionality.
> > >>>
> > >>>
> > >>> Just my 2¢,
> > >>>
> > >>> Jörg
> > >>>
> > >>>
> > >>>
> > >>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> > >>>
> > >>>
> > >>>> Hello,
> > >>>
> > >>>>
> > >>>
> > >>>> If memory serves me well, some time ago we had a discussion around
> > >>>
> > >>>> sanselan & commons-imaging 1.0. One of the issues with
> commons-imaging
> > >>>
> > >>>> 1.0 was the Debug class.
> > >>>
> > >>>>
> > >>>
> > >>>> https://issues.apache.org/jira/browse/IMAGING-154
> > >>>
> > >>>>
> > >>>
> > >>>> I finished the pull request, but Gilles raised an important point,
> > about
> > >>>
> > >>>> discussing other alternatives first.
> > >>>
> > >>>>
> > >>>
> > >>>> Initially I am against logging in low level libraries, especially
> > >>>
> > >>>> commons components. But some time ago I had to debug TIFF issues in
> > >>>
> > >>>> commons-imaging, and having the dump methods was a tremendous help.
> > >>>
> > >>>>
> > >>>
> > >>>>
> > >>>
> > >>>> The issue is that some imaging algorithms/processing have a lot of
> > >>>
> > >>>> variables that can be altered. And keeping an eye on all of them in
> > the
> > >>>
> > >>>> debugger can be quite hard - though not impossible.
> > >>>
> > >>>>
> > >>>
> > >>>> So all in all, now I am more confident to proceed without the Debug
> > >>>
> > >>>> class. But some users could have a hard time investigating possible
> > >>>
> > >>>> issues in the library without seeing what's going on within the
> > library.
> > >>>
> > >>>>
> > >>>
> > >>>> IMO, that could be solved with the logging/dump features... or
> > through a
> > >>>
> > >>>> better design, especially around exception handling/throwing. The
> > latter
> > >>>
> > >>>> is my preferred approach. Instead of logging, I prefer - whenever
> > >>>
> > >>>> possible - that low level libraries throw exceptions and let me
> handle
> > >>>
> > >>>> the logging.
> > >>>
> > >>>>
> > >>>
> > >>>>
> > >>>
> > >>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> > >>>
> > >>>> logging added to commons-imaging.
> > >>>
> > >>>>
> > >>>
> > >>>> Bruno
> > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> >
>
--
Matt Sicker <boards@gmail.com
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Matt Sicker <bo...@gmail.com>.
What I've seen done when trying to avoid a logging API dependency is to
create a minimal logging API purely for framework use. This can have a
default System.err style implementation, but the idea is to make it easy
(and performant hopefully) to bridge into the end user's choice of
framework and configuration without actually requiring a real logging
framework (at least until you want to use it in production). While it seems
overkill, the problem is that neither JUL nor System.err are sufficient for
logging. Even a simple API like Android's logging API can be good enough to
abstract it in a small library.
For a look at the very simplest route, you can see how Log4j2 handles
logging before any logging classes have been initialized. It's basically a
configurable wrapper around System.err:
https://github.com/apache/logging-log4j2/blob/master/log4j-api/src/main/java/org/apache/logging/log4j/util/LowLevelLogUtil.java
On Sun, 12 Aug 2018 at 09:12, Gary Gregory <ga...@gmail.com> wrote:
> You could also log to a pluggable print stream which could be sys err by
> default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
>
> Gary
>
> On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
>
> > There’s a couple of considerations about doing logging in a library, but
> > I’ll just mention a few:
> >
> > * dependencies
> > * performance
> > * ease of use
> >
> > * Dependencies*
> > Will the library be less attractive to users if it requires an external
> > dependency? Then don’t introduce one (so: use system err or JUL). On the
> > other hand, if the vast majority of usages is in a context with many
> other
> > external libraries (like in a web container) you have more freedom.
> >
> > *Performance*
> > Please take a look at the log4j 2 performance page (
> > https://logging.apache.org/log4j/2.x/performance.html#tradeoffs).
> Console
> > logging is 50x (yes fifty times) slower than file logging.
> > That’s a strong argument against system err logging. I’m not a fan of
> JUL,
> > but if you need to avoid dependencies you’re better off using JUL, that’s
> > only 5x slower than log4j. Also depends on how much logging you expect to
> > do in the worst case.
> >
> > *Ease of use*
> > I’m biased and would say that Log4j 2 has the nicest and richest API.
> > Console logging (System.err.printf) probably has the poorest API. Other
> > libraries sit in the middle.
> >
> > *Final note*
> > I would never log to System out, always use system err instead. This
> > allows programs using your library to pipe output to other programs
> without
> > their output getting mixed with your library’s diagnostic output.
> >
> > Hope this helps,
> >
> > Remko
> >
> > (Shameless plug) Every java main() method deserves http://picocli.info
> >
> > > On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org>
> wrote:
> > >
> > > Hello Bruno.
> > >
> > >> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> > >> Hi all,
> > >>
> > >>
> > >> I commented on IMAGING-154, but copying the last comment here as it
> > >> contains the approach I would like to follow to fix the last change in
> > >> the project blocking
> > >> a 1.0 release:
> > >>
> > >>
> > >> ---
> > >>
> > >> So went ahead to re-design the Debug class, in a way users could
> > >> still enable/disable debugging, and also use a PrintStream so that
> > >> other thing rather than System.out could be used.
> > >>
> > >>
> > >>
> > >> Then, realized removing System.out was the natural next step. But
> > >> alas, the library uses System.out for debugging, but sometimes it uses
> > >> it for writing to System.out in a "verbose mode". What is more
> > >> complicated, is that sometimes classes methods like `toString()` are
> > >> calling debug methods that receive a PrintStream already.
> > >>
> > >>
> > >>
> > >> So I spent some more time quickly comparing what other libraries I've
> > >> seen being used / or used for image processing:
> > >>
> >
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> > .
> > >> Turns out only very low level libraries, such as the JNI bridge for
> > >> OpenCV, im4java, and Java's ImageIO can do with just throwing
> > >> Exception's.
> > >>
> > >>
> > >>
> > >> All other libraries have one way or another of logging. Be it with
> > >> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> > >>
> > >>
> > >>
> > >> My preferred compromise for this ticket was to keep Debug, making
> > >> System.out possible but optional, and mark the class internal only.
> > >> Now my preferred solution is to keep the Debug internal, but add a
> > >> logger to it. And then also add logging to replace where System.out is
> > >> used for the "verbose" mode.
> > >> ---
> > >>
> > >>
> > >>
> > >> Any thoughts? Objections? If none, I will try to work on this issue
> > >> next weekend, making the Debug class internal only, and replacing
> > >> System.out by a logging utility. After that, we should be good to
> > >> start preparing the vote for 1.0.
> > >>
> > >>
> > >>
> > >> * I know it's hard to get a consensus on having logging in Commons
> > >> components, as we have normally low level libraries, where using
> > >> logging is not always practical.
> > >
> > > There are Log4j2 experts reading here. It would be interesting
> > > to hear them about what is practical or not. There are several
> > > aspects to "practical": simplicity, flexibility, compatibility,
> > > performance, ...
> > > How does Log4j2 fare in these areas?
> > > Is there a known (through experience) limit in where it should
> > > be used?
> > >
> > >> But I would now argue that Java own
> > >> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
> > >> Imaging are located at a higher level, some times even using it for
> > >> basic image handling/parsing/reading.
> > >
> > > As with many discussions on this list, conflicting arguments occur
> > > because people lack common (!) definitions.
> > > So one goes: "You cannot do <something> in a low-level component"
> > > but does not define "low-level"...
> > >
> > >> * Feel free to cast a counter-argument for it, but please think
> > >> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
> > >> a while, so if you have a strong opinion on not adding a logger,
> > >> please provide an alternative for IMAGING-154.
> > >
> > >> Otherwise we may fail
> > >> to prepare a 1.0 release yet again, and then somebody else may have to
> > >> work on it in a few months/years...
> > >
> > > We are there because the project is too rigid about itself as
> > > a whole (cf. for example the [RNG] thread about BC).
> > > IMHO, it's not the always least common denominator that is the
> > > best decision...
> > > As you noticed, components most easily stall in their development
> > > for lack of proper review, or risk acceptance (i.e. assume that
> > > those who are closer to the code (at a given time) probably know
> > > best... :-/
> > >
> > > My opinion is that we can take the risk to introduce logging, and
> > > if people complain somehow, take it back later.
> > >
> > >> one possible compromise for this,
> > >> might be i) make Debug internal,
> > >
> > > +1
> > >
> > > [Hmm... Does "internal" mean that minor release can break BC
> > > on such a class?]
> > >
> > >> ii) remove all System.out calls,
> > >
> > > +1 or
> > > -1
> > >
> > > [Depends on what "low-level" means here. "stdout"/"stderr" is
> > > indeed used in low-level utilities but is the intent the same
> > > here?]
> > >
> > >> which means removing the verbose flags, the checks, and calls to
> > >> System.out in there.
> > >
> > > It would be a loss of potentially useful information (e.g. for
> > > debugging).
> > >
> > > Regards,
> > > Gilles
> > >
> > >>
> > >> Thanks!
> > >> Bruno
> > >>
> > >> ________________________________
> > >> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> > >> To: Commons Developers List <de...@commons.apache.org>
> > >> Sent: Tuesday, 6 February 2018 11:30 PM
> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >>
> > >>
> > >>
> > >> Hi sebb,
> > >>
> > >>> Another aspect of debugging is ensuring that methods are small and
> > >>
> > >>> easily tested independently.
> > >>> However this is difficult to do, and care must be taken to ensure
> that
> > >>> the public API is not unnecessarily extended..
> > >>
> > >> A very good point.
> > >>
> > >> The parsers in commons-imaging expose some #dump... methods
> > >> (
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> > ).
> > >>
> > >> While I can see that parsers may need to dump the data they are
> > >> holding in some structured way for inspecting, reporting, serializing,
> > >> etc, it looks like some other classes were affected by it too. For
> > >> example...
> > >>
> > >>
> > >> A JPEG Segment has a #dump() method
> > >>
> > >>
> > >>
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> > >>
> > >>
> > >> which gets defined in each subclass of Segment. It can be confusing
> > >> to have a method such as #dump() in a Segment, from the point of view
> > >> of someone writing a photo editor for example. The user could use that
> > >> to pass his/her own logger's PrintWriter, which would make removing or
> > >> changing logging in the future in commons-imaging.
> > >>
> > >>
> > >> If we keep the Debug class, and make it internal, there would still
> > >> be these methods to take care. And there are some methods where users
> > >> can provide a PrintWriter, while others instead use System.out
> > >> (e.g.
> >
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> > ).
> > >>
> > >> Cheers
> > >> Bruno
> > >>
> > >> ________________________________
> > >> From: sebb <se...@gmail.com>
> > >> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> > >> Kinoshita <br...@yahoo.com.br>
> > >> Sent: Tuesday, 6 February 2018 11:06 PM
> > >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >>
> > >>
> > >>
> > >> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> > >> <br...@yahoo.com.br.invalid> wrote:
> > >>> Hi Jorg,
> > >>>
> > >>> I'd be fine with that solution too. I think this one would cause the
> > smaller change to the code as is.
> > >>>
> > >>> I believe my preference is still to remove the Debug class. But
> > between logging and making Debug internal only, I'd choose making it
> > internal.
> > >>
> > >> +1
> > >>
> > >> I think making it internal means it can still be dropped later.
> > >>
> > >>> Looking forward to hearing what others think about these options.
> > >>>
> > >>
> > >> Another aspect of debugging is ensuring that methods are small and
> > >> easily tested independently.
> > >> However this is difficult to do, and care must be taken to ensure that
> > >> the public API is not unnecessarily extended..
> > >>
> > >>> Thanks
> > >>> Bruno
> > >>>
> > >>>
> > >>> ________________________________
> > >>> From: Jörg Schaible <jo...@bpm-inspire.com>
> > >>> To: dev@commons.apache.org
> > >>> Sent: Tuesday, 6 February 2018 9:24 PM
> > >>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> > >>>
> > >>>
> > >>>
> > >>> Hi Bruno,
> > >>>
> > >>>
> > >>> if it might also be helpful to our users, why not keep and provide
> it.
> > As
> > >>>
> > >>> I understand it, the Debug class is a tool helping in development to
> > >>>
> > >>> analyze some behavior.
> > >>>
> > >>>
> > >>> Nothing stops us from declaring this class internal (we might even
> put
> > it
> > >>>
> > >>> into a package "internal" or "debug") that might be changed without
> > >>>
> > >>> further comment. Nobody may rely on it in production code, but during
> > >>>
> > >>> development it might be helpful. With such an approach we might not
> > have
> > >>>
> > >>> a need to find a better interface to provide this functionality.
> > >>>
> > >>>
> > >>> Just my 2¢,
> > >>>
> > >>> Jörg
> > >>>
> > >>>
> > >>>
> > >>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> > >>>
> > >>>
> > >>>> Hello,
> > >>>
> > >>>>
> > >>>
> > >>>> If memory serves me well, some time ago we had a discussion around
> > >>>
> > >>>> sanselan & commons-imaging 1.0. One of the issues with
> commons-imaging
> > >>>
> > >>>> 1.0 was the Debug class.
> > >>>
> > >>>>
> > >>>
> > >>>> https://issues.apache.org/jira/browse/IMAGING-154
> > >>>
> > >>>>
> > >>>
> > >>>> I finished the pull request, but Gilles raised an important point,
> > about
> > >>>
> > >>>> discussing other alternatives first.
> > >>>
> > >>>>
> > >>>
> > >>>> Initially I am against logging in low level libraries, especially
> > >>>
> > >>>> commons components. But some time ago I had to debug TIFF issues in
> > >>>
> > >>>> commons-imaging, and having the dump methods was a tremendous help.
> > >>>
> > >>>>
> > >>>
> > >>>>
> > >>>
> > >>>> The issue is that some imaging algorithms/processing have a lot of
> > >>>
> > >>>> variables that can be altered. And keeping an eye on all of them in
> > the
> > >>>
> > >>>> debugger can be quite hard - though not impossible.
> > >>>
> > >>>>
> > >>>
> > >>>> So all in all, now I am more confident to proceed without the Debug
> > >>>
> > >>>> class. But some users could have a hard time investigating possible
> > >>>
> > >>>> issues in the library without seeing what's going on within the
> > library.
> > >>>
> > >>>>
> > >>>
> > >>>> IMO, that could be solved with the logging/dump features... or
> > through a
> > >>>
> > >>>> better design, especially around exception handling/throwing. The
> > latter
> > >>>
> > >>>> is my preferred approach. Instead of logging, I prefer - whenever
> > >>>
> > >>>> possible - that low level libraries throw exceptions and let me
> handle
> > >>>
> > >>>> the logging.
> > >>>
> > >>>>
> > >>>
> > >>>>
> > >>>
> > >>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> > >>>
> > >>>> logging added to commons-imaging.
> > >>>
> > >>>>
> > >>>
> > >>>> Bruno
> > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> >
>
--
Matt Sicker <bo...@gmail.com>
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi Gary,
that was my intention. But the API of Commons Imaging contains certain methods like #dump, which call utility private methods (e.g. printbytes) that may print to System.out, if a flag "verbose" is enabled.
I started changing the signatures of these methods, to allow for a `PrintStream` argument, but that just got silly, and I was using it everywhere. I just threw in the towel and accepted a logging was necessary.
I think if we decide for a logging framework, we can assume log4j is leading for now (:
Bruno
________________________________
From: Gary Gregory <ga...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>
Sent: Monday, 13 August 2018 2:12 AM
Subject: Re: [imaging] IMAGING-154 remove Debug class
You could also log to a pluggable print stream which could be sys err by
default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
Gary
On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
> There’s a couple of considerations about doing logging in a library, but
> I’ll just mention a few:
>
> * dependencies
> * performance
> * ease of use
>
> * Dependencies*
> Will the library be less attractive to users if it requires an external
> dependency? Then don’t introduce one (so: use system err or JUL). On the
> other hand, if the vast majority of usages is in a context with many other
> external libraries (like in a web container) you have more freedom.
>
> *Performance*
> Please take a look at the log4j 2 performance page (
> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs). Console
> logging is 50x (yes fifty times) slower than file logging.
> That’s a strong argument against system err logging. I’m not a fan of JUL,
> but if you need to avoid dependencies you’re better off using JUL, that’s
> only 5x slower than log4j. Also depends on how much logging you expect to
> do in the worst case.
>
> *Ease of use*
> I’m biased and would say that Log4j 2 has the nicest and richest API.
> Console logging (System.err.printf) probably has the poorest API. Other
> libraries sit in the middle.
>
> *Final note*
> I would never log to System out, always use system err instead. This
> allows programs using your library to pipe output to other programs without
> their output getting mixed with your library’s diagnostic output.
>
> Hope this helps,
>
> Remko
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
> > On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org> wrote:
> >
> > Hello Bruno.
> >
> >> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> >> Hi all,
> >>
> >>
> >> I commented on IMAGING-154, but copying the last comment here as it
> >> contains the approach I would like to follow to fix the last change in
> >> the project blocking
> >> a 1.0 release:
> >>
> >>
> >> ---
> >>
> >> So went ahead to re-design the Debug class, in a way users could
> >> still enable/disable debugging, and also use a PrintStream so that
> >> other thing rather than System.out could be used.
> >>
> >>
> >>
> >> Then, realized removing System.out was the natural next step. But
> >> alas, the library uses System.out for debugging, but sometimes it uses
> >> it for writing to System.out in a "verbose mode". What is more
> >> complicated, is that sometimes classes methods like `toString()` are
> >> calling debug methods that receive a PrintStream already.
> >>
> >>
> >>
> >> So I spent some more time quickly comparing what other libraries I've
> >> seen being used / or used for image processing:
> >>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> .
> >> Turns out only very low level libraries, such as the JNI bridge for
> >> OpenCV, im4java, and Java's ImageIO can do with just throwing
> >> Exception's.
> >>
> >>
> >>
> >> All other libraries have one way or another of logging. Be it with
> >> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> >>
> >>
> >>
> >> My preferred compromise for this ticket was to keep Debug, making
> >> System.out possible but optional, and mark the class internal only.
> >> Now my preferred solution is to keep the Debug internal, but add a
> >> logger to it. And then also add logging to replace where System.out is
> >> used for the "verbose" mode.
> >> ---
> >>
> >>
> >>
> >> Any thoughts? Objections? If none, I will try to work on this issue
> >> next weekend, making the Debug class internal only, and replacing
> >> System.out by a logging utility. After that, we should be good to
> >> start preparing the vote for 1.0.
> >>
> >>
> >>
> >> * I know it's hard to get a consensus on having logging in Commons
> >> components, as we have normally low level libraries, where using
> >> logging is not always practical.
> >
> > There are Log4j2 experts reading here. It would be interesting
> > to hear them about what is practical or not. There are several
> > aspects to "practical": simplicity, flexibility, compatibility,
> > performance, ...
> > How does Log4j2 fare in these areas?
> > Is there a known (through experience) limit in where it should
> > be used?
> >
> >> But I would now argue that Java own
> >> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
> >> Imaging are located at a higher level, some times even using it for
> >> basic image handling/parsing/reading.
> >
> > As with many discussions on this list, conflicting arguments occur
> > because people lack common (!) definitions.
> > So one goes: "You cannot do <something> in a low-level component"
> > but does not define "low-level"...
> >
> >> * Feel free to cast a counter-argument for it, but please think
> >> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
> >> a while, so if you have a strong opinion on not adding a logger,
> >> please provide an alternative for IMAGING-154.
> >
> >> Otherwise we may fail
> >> to prepare a 1.0 release yet again, and then somebody else may have to
> >> work on it in a few months/years...
> >
> > We are there because the project is too rigid about itself as
> > a whole (cf. for example the [RNG] thread about BC).
> > IMHO, it's not the always least common denominator that is the
> > best decision...
> > As you noticed, components most easily stall in their development
> > for lack of proper review, or risk acceptance (i.e. assume that
> > those who are closer to the code (at a given time) probably know
> > best... :-/
> >
> > My opinion is that we can take the risk to introduce logging, and
> > if people complain somehow, take it back later.
> >
> >> one possible compromise for this,
> >> might be i) make Debug internal,
> >
> > +1
> >
> > [Hmm... Does "internal" mean that minor release can break BC
> > on such a class?]
> >
> >> ii) remove all System.out calls,
> >
> > +1 or
> > -1
> >
> > [Depends on what "low-level" means here. "stdout"/"stderr" is
> > indeed used in low-level utilities but is the intent the same
> > here?]
> >
> >> which means removing the verbose flags, the checks, and calls to
> >> System.out in there.
> >
> > It would be a loss of potentially useful information (e.g. for
> > debugging).
> >
> > Regards,
> > Gilles
> >
> >>
> >> Thanks!
> >> Bruno
> >>
> >> ________________________________
> >> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> >> To: Commons Developers List <de...@commons.apache.org>
> >> Sent: Tuesday, 6 February 2018 11:30 PM
> >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >>
> >>
> >>
> >> Hi sebb,
> >>
> >>> Another aspect of debugging is ensuring that methods are small and
> >>
> >>> easily tested independently.
> >>> However this is difficult to do, and care must be taken to ensure that
> >>> the public API is not unnecessarily extended..
> >>
> >> A very good point.
> >>
> >> The parsers in commons-imaging expose some #dump... methods
> >> (
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> ).
> >>
> >> While I can see that parsers may need to dump the data they are
> >> holding in some structured way for inspecting, reporting, serializing,
> >> etc, it looks like some other classes were affected by it too. For
> >> example...
> >>
> >>
> >> A JPEG Segment has a #dump() method
> >>
> >>
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> >>
> >>
> >> which gets defined in each subclass of Segment. It can be confusing
> >> to have a method such as #dump() in a Segment, from the point of view
> >> of someone writing a photo editor for example. The user could use that
> >> to pass his/her own logger's PrintWriter, which would make removing or
> >> changing logging in the future in commons-imaging.
> >>
> >>
> >> If we keep the Debug class, and make it internal, there would still
> >> be these methods to take care. And there are some methods where users
> >> can provide a PrintWriter, while others instead use System.out
> >> (e.g.
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> ).
> >>
> >> Cheers
> >> Bruno
> >>
> >> ________________________________
> >> From: sebb <se...@gmail.com>
> >> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> >> Kinoshita <br...@yahoo.com.br>
> >> Sent: Tuesday, 6 February 2018 11:06 PM
> >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >>
> >>
> >>
> >> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> >> <br...@yahoo.com.br.invalid> wrote:
> >>> Hi Jorg,
> >>>
> >>> I'd be fine with that solution too. I think this one would cause the
> smaller change to the code as is.
> >>>
> >>> I believe my preference is still to remove the Debug class. But
> between logging and making Debug internal only, I'd choose making it
> internal.
> >>
> >> +1
> >>
> >> I think making it internal means it can still be dropped later.
> >>
> >>> Looking forward to hearing what others think about these options.
> >>>
> >>
> >> Another aspect of debugging is ensuring that methods are small and
> >> easily tested independently.
> >> However this is difficult to do, and care must be taken to ensure that
> >> the public API is not unnecessarily extended..
> >>
> >>> Thanks
> >>> Bruno
> >>>
> >>>
> >>> ________________________________
> >>> From: Jörg Schaible <jo...@bpm-inspire.com>
> >>> To: dev@commons.apache.org
> >>> Sent: Tuesday, 6 February 2018 9:24 PM
> >>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >>>
> >>>
> >>>
> >>> Hi Bruno,
> >>>
> >>>
> >>> if it might also be helpful to our users, why not keep and provide it.
> As
> >>>
> >>> I understand it, the Debug class is a tool helping in development to
> >>>
> >>> analyze some behavior.
> >>>
> >>>
> >>> Nothing stops us from declaring this class internal (we might even put
> it
> >>>
> >>> into a package "internal" or "debug") that might be changed without
> >>>
> >>> further comment. Nobody may rely on it in production code, but during
> >>>
> >>> development it might be helpful. With such an approach we might not
> have
> >>>
> >>> a need to find a better interface to provide this functionality.
> >>>
> >>>
> >>> Just my 2¢,
> >>>
> >>> Jörg
> >>>
> >>>
> >>>
> >>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> >>>
> >>>
> >>>> Hello,
> >>>
> >>>>
> >>>
> >>>> If memory serves me well, some time ago we had a discussion around
> >>>
> >>>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
> >>>
> >>>> 1.0 was the Debug class.
> >>>
> >>>>
> >>>
> >>>> https://issues.apache.org/jira/browse/IMAGING-154
> >>>
> >>>>
> >>>
> >>>> I finished the pull request, but Gilles raised an important point,
> about
> >>>
> >>>> discussing other alternatives first.
> >>>
> >>>>
> >>>
> >>>> Initially I am against logging in low level libraries, especially
> >>>
> >>>> commons components. But some time ago I had to debug TIFF issues in
> >>>
> >>>> commons-imaging, and having the dump methods was a tremendous help.
> >>>
> >>>>
> >>>
> >>>>
> >>>
> >>>> The issue is that some imaging algorithms/processing have a lot of
> >>>
> >>>> variables that can be altered. And keeping an eye on all of them in
> the
> >>>
> >>>> debugger can be quite hard - though not impossible.
> >>>
> >>>>
> >>>
> >>>> So all in all, now I am more confident to proceed without the Debug
> >>>
> >>>> class. But some users could have a hard time investigating possible
> >>>
> >>>> issues in the library without seeing what's going on within the
> library.
> >>>
> >>>>
> >>>
> >>>> IMO, that could be solved with the logging/dump features... or
> through a
> >>>
> >>>> better design, especially around exception handling/throwing. The
> latter
> >>>
> >>>> is my preferred approach. Instead of logging, I prefer - whenever
> >>>
> >>>> possible - that low level libraries throw exceptions and let me handle
> >>>
> >>>> the logging.
> >>>
> >>>>
> >>>
> >>>>
> >>>
> >>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> >>>
> >>>> logging added to commons-imaging.
> >>>
> >>>>
> >>>
> >>>> Bruno
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Gary Gregory <ga...@gmail.com>.
You could also log to a pluggable print stream which could be sys err by
default. Kind of like what JDBC allows. My bias is to Log4j 2 as well :-)
Gary
On Sun, Aug 12, 2018, 08:00 Remko Popma <re...@gmail.com> wrote:
> There’s a couple of considerations about doing logging in a library, but
> I’ll just mention a few:
>
> * dependencies
> * performance
> * ease of use
>
> * Dependencies*
> Will the library be less attractive to users if it requires an external
> dependency? Then don’t introduce one (so: use system err or JUL). On the
> other hand, if the vast majority of usages is in a context with many other
> external libraries (like in a web container) you have more freedom.
>
> *Performance*
> Please take a look at the log4j 2 performance page (
> https://logging.apache.org/log4j/2.x/performance.html#tradeoffs). Console
> logging is 50x (yes fifty times) slower than file logging.
> That’s a strong argument against system err logging. I’m not a fan of JUL,
> but if you need to avoid dependencies you’re better off using JUL, that’s
> only 5x slower than log4j. Also depends on how much logging you expect to
> do in the worst case.
>
> *Ease of use*
> I’m biased and would say that Log4j 2 has the nicest and richest API.
> Console logging (System.err.printf) probably has the poorest API. Other
> libraries sit in the middle.
>
> *Final note*
> I would never log to System out, always use system err instead. This
> allows programs using your library to pipe output to other programs without
> their output getting mixed with your library’s diagnostic output.
>
> Hope this helps,
>
> Remko
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
> > On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org> wrote:
> >
> > Hello Bruno.
> >
> >> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> >> Hi all,
> >>
> >>
> >> I commented on IMAGING-154, but copying the last comment here as it
> >> contains the approach I would like to follow to fix the last change in
> >> the project blocking
> >> a 1.0 release:
> >>
> >>
> >> ---
> >>
> >> So went ahead to re-design the Debug class, in a way users could
> >> still enable/disable debugging, and also use a PrintStream so that
> >> other thing rather than System.out could be used.
> >>
> >>
> >>
> >> Then, realized removing System.out was the natural next step. But
> >> alas, the library uses System.out for debugging, but sometimes it uses
> >> it for writing to System.out in a "verbose mode". What is more
> >> complicated, is that sometimes classes methods like `toString()` are
> >> calling debug methods that receive a PrintStream already.
> >>
> >>
> >>
> >> So I spent some more time quickly comparing what other libraries I've
> >> seen being used / or used for image processing:
> >>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/
> .
> >> Turns out only very low level libraries, such as the JNI bridge for
> >> OpenCV, im4java, and Java's ImageIO can do with just throwing
> >> Exception's.
> >>
> >>
> >>
> >> All other libraries have one way or another of logging. Be it with
> >> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
> >>
> >>
> >>
> >> My preferred compromise for this ticket was to keep Debug, making
> >> System.out possible but optional, and mark the class internal only.
> >> Now my preferred solution is to keep the Debug internal, but add a
> >> logger to it. And then also add logging to replace where System.out is
> >> used for the "verbose" mode.
> >> ---
> >>
> >>
> >>
> >> Any thoughts? Objections? If none, I will try to work on this issue
> >> next weekend, making the Debug class internal only, and replacing
> >> System.out by a logging utility. After that, we should be good to
> >> start preparing the vote for 1.0.
> >>
> >>
> >>
> >> * I know it's hard to get a consensus on having logging in Commons
> >> components, as we have normally low level libraries, where using
> >> logging is not always practical.
> >
> > There are Log4j2 experts reading here. It would be interesting
> > to hear them about what is practical or not. There are several
> > aspects to "practical": simplicity, flexibility, compatibility,
> > performance, ...
> > How does Log4j2 fare in these areas?
> > Is there a known (through experience) limit in where it should
> > be used?
> >
> >> But I would now argue that Java own
> >> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
> >> Imaging are located at a higher level, some times even using it for
> >> basic image handling/parsing/reading.
> >
> > As with many discussions on this list, conflicting arguments occur
> > because people lack common (!) definitions.
> > So one goes: "You cannot do <something> in a low-level component"
> > but does not define "low-level"...
> >
> >> * Feel free to cast a counter-argument for it, but please think
> >> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
> >> a while, so if you have a strong opinion on not adding a logger,
> >> please provide an alternative for IMAGING-154.
> >
> >> Otherwise we may fail
> >> to prepare a 1.0 release yet again, and then somebody else may have to
> >> work on it in a few months/years...
> >
> > We are there because the project is too rigid about itself as
> > a whole (cf. for example the [RNG] thread about BC).
> > IMHO, it's not the always least common denominator that is the
> > best decision...
> > As you noticed, components most easily stall in their development
> > for lack of proper review, or risk acceptance (i.e. assume that
> > those who are closer to the code (at a given time) probably know
> > best... :-/
> >
> > My opinion is that we can take the risk to introduce logging, and
> > if people complain somehow, take it back later.
> >
> >> one possible compromise for this,
> >> might be i) make Debug internal,
> >
> > +1
> >
> > [Hmm... Does "internal" mean that minor release can break BC
> > on such a class?]
> >
> >> ii) remove all System.out calls,
> >
> > +1 or
> > -1
> >
> > [Depends on what "low-level" means here. "stdout"/"stderr" is
> > indeed used in low-level utilities but is the intent the same
> > here?]
> >
> >> which means removing the verbose flags, the checks, and calls to
> >> System.out in there.
> >
> > It would be a loss of potentially useful information (e.g. for
> > debugging).
> >
> > Regards,
> > Gilles
> >
> >>
> >> Thanks!
> >> Bruno
> >>
> >> ________________________________
> >> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> >> To: Commons Developers List <de...@commons.apache.org>
> >> Sent: Tuesday, 6 February 2018 11:30 PM
> >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >>
> >>
> >>
> >> Hi sebb,
> >>
> >>> Another aspect of debugging is ensuring that methods are small and
> >>
> >>> easily tested independently.
> >>> However this is difficult to do, and care must be taken to ensure that
> >>> the public API is not unnecessarily extended..
> >>
> >> A very good point.
> >>
> >> The parsers in commons-imaging expose some #dump... methods
> >> (
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794
> ).
> >>
> >> While I can see that parsers may need to dump the data they are
> >> holding in some structured way for inspecting, reporting, serializing,
> >> etc, it looks like some other classes were affected by it too. For
> >> example...
> >>
> >>
> >> A JPEG Segment has a #dump() method
> >>
> >>
> >>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
> >>
> >>
> >> which gets defined in each subclass of Segment. It can be confusing
> >> to have a method such as #dump() in a Segment, from the point of view
> >> of someone writing a photo editor for example. The user could use that
> >> to pass his/her own logger's PrintWriter, which would make removing or
> >> changing logging in the future in commons-imaging.
> >>
> >>
> >> If we keep the Debug class, and make it internal, there would still
> >> be these methods to take care. And there are some methods where users
> >> can provide a PrintWriter, while others instead use System.out
> >> (e.g.
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70
> ).
> >>
> >> Cheers
> >> Bruno
> >>
> >> ________________________________
> >> From: sebb <se...@gmail.com>
> >> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> >> Kinoshita <br...@yahoo.com.br>
> >> Sent: Tuesday, 6 February 2018 11:06 PM
> >> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >>
> >>
> >>
> >> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> >> <br...@yahoo.com.br.invalid> wrote:
> >>> Hi Jorg,
> >>>
> >>> I'd be fine with that solution too. I think this one would cause the
> smaller change to the code as is.
> >>>
> >>> I believe my preference is still to remove the Debug class. But
> between logging and making Debug internal only, I'd choose making it
> internal.
> >>
> >> +1
> >>
> >> I think making it internal means it can still be dropped later.
> >>
> >>> Looking forward to hearing what others think about these options.
> >>>
> >>
> >> Another aspect of debugging is ensuring that methods are small and
> >> easily tested independently.
> >> However this is difficult to do, and care must be taken to ensure that
> >> the public API is not unnecessarily extended..
> >>
> >>> Thanks
> >>> Bruno
> >>>
> >>>
> >>> ________________________________
> >>> From: Jörg Schaible <jo...@bpm-inspire.com>
> >>> To: dev@commons.apache.org
> >>> Sent: Tuesday, 6 February 2018 9:24 PM
> >>> Subject: Re: [imaging] IMAGING-154 remove Debug class
> >>>
> >>>
> >>>
> >>> Hi Bruno,
> >>>
> >>>
> >>> if it might also be helpful to our users, why not keep and provide it.
> As
> >>>
> >>> I understand it, the Debug class is a tool helping in development to
> >>>
> >>> analyze some behavior.
> >>>
> >>>
> >>> Nothing stops us from declaring this class internal (we might even put
> it
> >>>
> >>> into a package "internal" or "debug") that might be changed without
> >>>
> >>> further comment. Nobody may rely on it in production code, but during
> >>>
> >>> development it might be helpful. With such an approach we might not
> have
> >>>
> >>> a need to find a better interface to provide this functionality.
> >>>
> >>>
> >>> Just my 2¢,
> >>>
> >>> Jörg
> >>>
> >>>
> >>>
> >>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> >>>
> >>>
> >>>> Hello,
> >>>
> >>>>
> >>>
> >>>> If memory serves me well, some time ago we had a discussion around
> >>>
> >>>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
> >>>
> >>>> 1.0 was the Debug class.
> >>>
> >>>>
> >>>
> >>>> https://issues.apache.org/jira/browse/IMAGING-154
> >>>
> >>>>
> >>>
> >>>> I finished the pull request, but Gilles raised an important point,
> about
> >>>
> >>>> discussing other alternatives first.
> >>>
> >>>>
> >>>
> >>>> Initially I am against logging in low level libraries, especially
> >>>
> >>>> commons components. But some time ago I had to debug TIFF issues in
> >>>
> >>>> commons-imaging, and having the dump methods was a tremendous help.
> >>>
> >>>>
> >>>
> >>>>
> >>>
> >>>> The issue is that some imaging algorithms/processing have a lot of
> >>>
> >>>> variables that can be altered. And keeping an eye on all of them in
> the
> >>>
> >>>> debugger can be quite hard - though not impossible.
> >>>
> >>>>
> >>>
> >>>> So all in all, now I am more confident to proceed without the Debug
> >>>
> >>>> class. But some users could have a hard time investigating possible
> >>>
> >>>> issues in the library without seeing what's going on within the
> library.
> >>>
> >>>>
> >>>
> >>>> IMO, that could be solved with the logging/dump features... or
> through a
> >>>
> >>>> better design, especially around exception handling/throwing. The
> latter
> >>>
> >>>> is my preferred approach. Instead of logging, I prefer - whenever
> >>>
> >>>> possible - that low level libraries throw exceptions and let me handle
> >>>
> >>>> the logging.
> >>>
> >>>>
> >>>
> >>>>
> >>>
> >>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> >>>
> >>>> logging added to commons-imaging.
> >>>
> >>>>
> >>>
> >>>> Bruno
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
Re: [imaging] IMAGING-154 remove Debug class
Posted by Remko Popma <re...@gmail.com>.
There’s a couple of considerations about doing logging in a library, but I’ll just mention a few:
* dependencies
* performance
* ease of use
* Dependencies*
Will the library be less attractive to users if it requires an external dependency? Then don’t introduce one (so: use system err or JUL). On the other hand, if the vast majority of usages is in a context with many other external libraries (like in a web container) you have more freedom.
*Performance*
Please take a look at the log4j 2 performance page (https://logging.apache.org/log4j/2.x/performance.html#tradeoffs). Console logging is 50x (yes fifty times) slower than file logging.
That’s a strong argument against system err logging. I’m not a fan of JUL, but if you need to avoid dependencies you’re better off using JUL, that’s only 5x slower than log4j. Also depends on how much logging you expect to do in the worst case.
*Ease of use*
I’m biased and would say that Log4j 2 has the nicest and richest API. Console logging (System.err.printf) probably has the poorest API. Other libraries sit in the middle.
*Final note*
I would never log to System out, always use system err instead. This allows programs using your library to pipe output to other programs without their output getting mixed with your library’s diagnostic output.
Hope this helps,
Remko
(Shameless plug) Every java main() method deserves http://picocli.info
> On Aug 12, 2018, at 21:21, Gilles <gi...@harfang.homelinux.org> wrote:
>
> Hello Bruno.
>
>> On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
>> Hi all,
>>
>>
>> I commented on IMAGING-154, but copying the last comment here as it
>> contains the approach I would like to follow to fix the last change in
>> the project blocking
>> a 1.0 release:
>>
>>
>> ---
>>
>> So went ahead to re-design the Debug class, in a way users could
>> still enable/disable debugging, and also use a PrintStream so that
>> other thing rather than System.out could be used.
>>
>>
>>
>> Then, realized removing System.out was the natural next step. But
>> alas, the library uses System.out for debugging, but sometimes it uses
>> it for writing to System.out in a "verbose mode". What is more
>> complicated, is that sometimes classes methods like `toString()` are
>> calling debug methods that receive a PrintStream already.
>>
>>
>>
>> So I spent some more time quickly comparing what other libraries I've
>> seen being used / or used for image processing:
>> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/.
>> Turns out only very low level libraries, such as the JNI bridge for
>> OpenCV, im4java, and Java's ImageIO can do with just throwing
>> Exception's.
>>
>>
>>
>> All other libraries have one way or another of logging. Be it with
>> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>>
>>
>>
>> My preferred compromise for this ticket was to keep Debug, making
>> System.out possible but optional, and mark the class internal only.
>> Now my preferred solution is to keep the Debug internal, but add a
>> logger to it. And then also add logging to replace where System.out is
>> used for the "verbose" mode.
>> ---
>>
>>
>>
>> Any thoughts? Objections? If none, I will try to work on this issue
>> next weekend, making the Debug class internal only, and replacing
>> System.out by a logging utility. After that, we should be good to
>> start preparing the vote for 1.0.
>>
>>
>>
>> * I know it's hard to get a consensus on having logging in Commons
>> components, as we have normally low level libraries, where using
>> logging is not always practical.
>
> There are Log4j2 experts reading here. It would be interesting
> to hear them about what is practical or not. There are several
> aspects to "practical": simplicity, flexibility, compatibility,
> performance, ...
> How does Log4j2 fare in these areas?
> Is there a known (through experience) limit in where it should
> be used?
>
>> But I would now argue that Java own
>> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
>> Imaging are located at a higher level, some times even using it for
>> basic image handling/parsing/reading.
>
> As with many discussions on this list, conflicting arguments occur
> because people lack common (!) definitions.
> So one goes: "You cannot do <something> in a low-level component"
> but does not define "low-level"...
>
>> * Feel free to cast a counter-argument for it, but please think
>> whether you'd still be -0, +0 for this change. We have delayed 1.0 for
>> a while, so if you have a strong opinion on not adding a logger,
>> please provide an alternative for IMAGING-154.
>
>> Otherwise we may fail
>> to prepare a 1.0 release yet again, and then somebody else may have to
>> work on it in a few months/years...
>
> We are there because the project is too rigid about itself as
> a whole (cf. for example the [RNG] thread about BC).
> IMHO, it's not the always least common denominator that is the
> best decision...
> As you noticed, components most easily stall in their development
> for lack of proper review, or risk acceptance (i.e. assume that
> those who are closer to the code (at a given time) probably know
> best... :-/
>
> My opinion is that we can take the risk to introduce logging, and
> if people complain somehow, take it back later.
>
>> one possible compromise for this,
>> might be i) make Debug internal,
>
> +1
>
> [Hmm... Does "internal" mean that minor release can break BC
> on such a class?]
>
>> ii) remove all System.out calls,
>
> +1 or
> -1
>
> [Depends on what "low-level" means here. "stdout"/"stderr" is
> indeed used in low-level utilities but is the intent the same
> here?]
>
>> which means removing the verbose flags, the checks, and calls to
>> System.out in there.
>
> It would be a loss of potentially useful information (e.g. for
> debugging).
>
> Regards,
> Gilles
>
>>
>> Thanks!
>> Bruno
>>
>> ________________________________
>> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
>> To: Commons Developers List <de...@commons.apache.org>
>> Sent: Tuesday, 6 February 2018 11:30 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> Hi sebb,
>>
>>> Another aspect of debugging is ensuring that methods are small and
>>
>>> easily tested independently.
>>> However this is difficult to do, and care must be taken to ensure that
>>> the public API is not unnecessarily extended..
>>
>> A very good point.
>>
>> The parsers in commons-imaging expose some #dump... methods
>> (https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794).
>>
>> While I can see that parsers may need to dump the data they are
>> holding in some structured way for inspecting, reporting, serializing,
>> etc, it looks like some other classes were affected by it too. For
>> example...
>>
>>
>> A JPEG Segment has a #dump() method
>>
>>
>> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>>
>>
>> which gets defined in each subclass of Segment. It can be confusing
>> to have a method such as #dump() in a Segment, from the point of view
>> of someone writing a photo editor for example. The user could use that
>> to pass his/her own logger's PrintWriter, which would make removing or
>> changing logging in the future in commons-imaging.
>>
>>
>> If we keep the Debug class, and make it internal, there would still
>> be these methods to take care. And there are some methods where users
>> can provide a PrintWriter, while others instead use System.out
>> (e.g.https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70).
>>
>> Cheers
>> Bruno
>>
>> ________________________________
>> From: sebb <se...@gmail.com>
>> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
>> Kinoshita <br...@yahoo.com.br>
>> Sent: Tuesday, 6 February 2018 11:06 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> On 6 February 2018 at 09:52, Bruno P. Kinoshita
>> <br...@yahoo.com.br.invalid> wrote:
>>> Hi Jorg,
>>>
>>> I'd be fine with that solution too. I think this one would cause the smaller change to the code as is.
>>>
>>> I believe my preference is still to remove the Debug class. But between logging and making Debug internal only, I'd choose making it internal.
>>
>> +1
>>
>> I think making it internal means it can still be dropped later.
>>
>>> Looking forward to hearing what others think about these options.
>>>
>>
>> Another aspect of debugging is ensuring that methods are small and
>> easily tested independently.
>> However this is difficult to do, and care must be taken to ensure that
>> the public API is not unnecessarily extended..
>>
>>> Thanks
>>> Bruno
>>>
>>>
>>> ________________________________
>>> From: Jörg Schaible <jo...@bpm-inspire.com>
>>> To: dev@commons.apache.org
>>> Sent: Tuesday, 6 February 2018 9:24 PM
>>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>>
>>>
>>>
>>> Hi Bruno,
>>>
>>>
>>> if it might also be helpful to our users, why not keep and provide it. As
>>>
>>> I understand it, the Debug class is a tool helping in development to
>>>
>>> analyze some behavior.
>>>
>>>
>>> Nothing stops us from declaring this class internal (we might even put it
>>>
>>> into a package "internal" or "debug") that might be changed without
>>>
>>> further comment. Nobody may rely on it in production code, but during
>>>
>>> development it might be helpful. With such an approach we might not have
>>>
>>> a need to find a better interface to provide this functionality.
>>>
>>>
>>> Just my 2¢,
>>>
>>> Jörg
>>>
>>>
>>>
>>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>>
>>>
>>>> Hello,
>>>
>>>>
>>>
>>>> If memory serves me well, some time ago we had a discussion around
>>>
>>>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
>>>
>>>> 1.0 was the Debug class.
>>>
>>>>
>>>
>>>> https://issues.apache.org/jira/browse/IMAGING-154
>>>
>>>>
>>>
>>>> I finished the pull request, but Gilles raised an important point, about
>>>
>>>> discussing other alternatives first.
>>>
>>>>
>>>
>>>> Initially I am against logging in low level libraries, especially
>>>
>>>> commons components. But some time ago I had to debug TIFF issues in
>>>
>>>> commons-imaging, and having the dump methods was a tremendous help.
>>>
>>>>
>>>
>>>>
>>>
>>>> The issue is that some imaging algorithms/processing have a lot of
>>>
>>>> variables that can be altered. And keeping an eye on all of them in the
>>>
>>>> debugger can be quite hard - though not impossible.
>>>
>>>>
>>>
>>>> So all in all, now I am more confident to proceed without the Debug
>>>
>>>> class. But some users could have a hard time investigating possible
>>>
>>>> issues in the library without seeing what's going on within the library.
>>>
>>>>
>>>
>>>> IMO, that could be solved with the logging/dump features... or through a
>>>
>>>> better design, especially around exception handling/throwing. The latter
>>>
>>>> is my preferred approach. Instead of logging, I prefer - whenever
>>>
>>>> possible - that low level libraries throw exceptions and let me handle
>>>
>>>> the logging.
>>>
>>>>
>>>
>>>>
>>>
>>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>>
>>>> logging added to commons-imaging.
>>>
>>>>
>>>
>>>> Bruno
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
Re: [imaging] IMAGING-154 remove Debug class
Posted by Gilles <gi...@harfang.homelinux.org>.
Hello Bruno.
On Sun, 12 Aug 2018 08:56:37 +0000 (UTC), Bruno P. Kinoshita wrote:
> Hi all,
>
>
> I commented on IMAGING-154, but copying the last comment here as it
> contains the approach I would like to follow to fix the last change
> in
> the project blocking
> a 1.0 release:
>
>
> ---
>
> So went ahead to re-design the Debug class, in a way users could
> still enable/disable debugging, and also use a PrintStream so that
> other thing rather than System.out could be used.
>
>
>
> Then, realized removing System.out was the natural next step. But
> alas, the library uses System.out for debugging, but sometimes it
> uses
> it for writing to System.out in a "verbose mode". What is more
> complicated, is that sometimes classes methods like `toString()` are
> calling debug methods that receive a PrintStream already.
>
>
>
> So I spent some more time quickly comparing what other libraries I've
> seen being used / or used for image processing:
>
> https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/.
> Turns out only very low level libraries, such as the JNI bridge for
> OpenCV, im4java, and Java's ImageIO can do with just throwing
> Exception's.
>
>
>
> All other libraries have one way or another of logging. Be it with
> JUL, SLF4J, custom loggers, or with the ol' System.out/err.
>
>
>
> My preferred compromise for this ticket was to keep Debug, making
> System.out possible but optional, and mark the class internal only.
> Now my preferred solution is to keep the Debug internal, but add a
> logger to it. And then also add logging to replace where System.out
> is
> used for the "verbose" mode.
> ---
>
>
>
> Any thoughts? Objections? If none, I will try to work on this issue
> next weekend, making the Debug class internal only, and replacing
> System.out by a logging utility. After that, we should be good to
> start preparing the vote for 1.0.
>
>
>
> * I know it's hard to get a consensus on having logging in Commons
> components, as we have normally low level libraries, where using
> logging is not always practical.
There are Log4j2 experts reading here. It would be interesting
to hear them about what is practical or not. There are several
aspects to "practical": simplicity, flexibility, compatibility,
performance, ...
How does Log4j2 fare in these areas?
Is there a known (through experience) limit in where it should
be used?
> But I would now argue that Java own
> ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons
> Imaging are located at a higher level, some times even using it for
> basic image handling/parsing/reading.
As with many discussions on this list, conflicting arguments occur
because people lack common (!) definitions.
So one goes: "You cannot do <something> in a low-level component"
but does not define "low-level"...
> * Feel free to cast a counter-argument for it, but please think
> whether you'd still be -0, +0 for this change. We have delayed 1.0
> for
> a while, so if you have a strong opinion on not adding a logger,
> please provide an alternative for IMAGING-154.
> Otherwise we may fail
> to prepare a 1.0 release yet again, and then somebody else may have
> to
> work on it in a few months/years...
We are there because the project is too rigid about itself as
a whole (cf. for example the [RNG] thread about BC).
IMHO, it's not the always least common denominator that is the
best decision...
As you noticed, components most easily stall in their development
for lack of proper review, or risk acceptance (i.e. assume that
those who are closer to the code (at a given time) probably know
best... :-/
My opinion is that we can take the risk to introduce logging, and
if people complain somehow, take it back later.
> one possible compromise for this,
> might be i) make Debug internal,
+1
[Hmm... Does "internal" mean that minor release can break BC
on such a class?]
> ii) remove all System.out calls,
+1 or
-1
[Depends on what "low-level" means here. "stdout"/"stderr" is
indeed used in low-level utilities but is the intent the same
here?]
> which means removing the verbose flags, the checks, and calls to
> System.out in there.
It would be a loss of potentially useful information (e.g. for
debugging).
Regards,
Gilles
>
> Thanks!
> Bruno
>
> ________________________________
> From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
> To: Commons Developers List <de...@commons.apache.org>
> Sent: Tuesday, 6 February 2018 11:30 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> Hi sebb,
>
>>Another aspect of debugging is ensuring that methods are small and
>
>>easily tested independently.
>>However this is difficult to do, and care must be taken to ensure
>> that
>>the public API is not unnecessarily extended..
>
> A very good point.
>
> The parsers in commons-imaging expose some #dump... methods
>
> (https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794).
>
> While I can see that parsers may need to dump the data they are
> holding in some structured way for inspecting, reporting,
> serializing,
> etc, it looks like some other classes were affected by it too. For
> example...
>
>
> A JPEG Segment has a #dump() method
>
>
>
> https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
>
>
> which gets defined in each subclass of Segment. It can be confusing
> to have a method such as #dump() in a Segment, from the point of view
> of someone writing a photo editor for example. The user could use
> that
> to pass his/her own logger's PrintWriter, which would make removing
> or
> changing logging in the future in commons-imaging.
>
>
> If we keep the Debug class, and make it internal, there would still
> be these methods to take care. And there are some methods where users
> can provide a PrintWriter, while others instead use System.out
>
> (e.g.https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70).
>
> Cheers
> Bruno
>
> ________________________________
> From: sebb <se...@gmail.com>
> To: Commons Developers List <de...@commons.apache.org>; Bruno P.
> Kinoshita <br...@yahoo.com.br>
> Sent: Tuesday, 6 February 2018 11:06 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> On 6 February 2018 at 09:52, Bruno P. Kinoshita
> <br...@yahoo.com.br.invalid> wrote:
>> Hi Jorg,
>>
>> I'd be fine with that solution too. I think this one would cause the
>> smaller change to the code as is.
>>
>> I believe my preference is still to remove the Debug class. But
>> between logging and making Debug internal only, I'd choose making it
>> internal.
>
> +1
>
> I think making it internal means it can still be dropped later.
>
>> Looking forward to hearing what others think about these options.
>>
>
> Another aspect of debugging is ensuring that methods are small and
> easily tested independently.
> However this is difficult to do, and care must be taken to ensure
> that
> the public API is not unnecessarily extended..
>
>> Thanks
>> Bruno
>>
>>
>> ________________________________
>> From: Jörg Schaible <jo...@bpm-inspire.com>
>> To: dev@commons.apache.org
>> Sent: Tuesday, 6 February 2018 9:24 PM
>> Subject: Re: [imaging] IMAGING-154 remove Debug class
>>
>>
>>
>> Hi Bruno,
>>
>>
>> if it might also be helpful to our users, why not keep and provide
>> it. As
>>
>> I understand it, the Debug class is a tool helping in development to
>>
>> analyze some behavior.
>>
>>
>> Nothing stops us from declaring this class internal (we might even
>> put it
>>
>> into a package "internal" or "debug") that might be changed without
>>
>> further comment. Nobody may rely on it in production code, but
>> during
>>
>> development it might be helpful. With such an approach we might not
>> have
>>
>> a need to find a better interface to provide this functionality.
>>
>>
>> Just my 2¢,
>>
>> Jörg
>>
>>
>>
>> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>>
>>
>>> Hello,
>>
>>>
>>
>>> If memory serves me well, some time ago we had a discussion around
>>
>>> sanselan & commons-imaging 1.0. One of the issues with
>>> commons-imaging
>>
>>> 1.0 was the Debug class.
>>
>>>
>>
>>> https://issues.apache.org/jira/browse/IMAGING-154
>>
>>>
>>
>>> I finished the pull request, but Gilles raised an important point,
>>> about
>>
>>> discussing other alternatives first.
>>
>>>
>>
>>> Initially I am against logging in low level libraries, especially
>>
>>> commons components. But some time ago I had to debug TIFF issues in
>>
>>> commons-imaging, and having the dump methods was a tremendous help.
>>
>>>
>>
>>>
>>
>>> The issue is that some imaging algorithms/processing have a lot of
>>
>>> variables that can be altered. And keeping an eye on all of them in
>>> the
>>
>>> debugger can be quite hard - though not impossible.
>>
>>>
>>
>>> So all in all, now I am more confident to proceed without the Debug
>>
>>> class. But some users could have a hard time investigating possible
>>
>>> issues in the library without seeing what's going on within the
>>> library.
>>
>>>
>>
>>> IMO, that could be solved with the logging/dump features... or
>>> through a
>>
>>> better design, especially around exception handling/throwing. The
>>> latter
>>
>>> is my preferred approach. Instead of logging, I prefer - whenever
>>
>>> possible - that low level libraries throw exceptions and let me
>>> handle
>>
>>> the logging.
>>
>>>
>>
>>>
>>
>>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>>
>>> logging added to commons-imaging.
>>
>>>
>>
>>> Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi all,
I commented on IMAGING-154, but copying the last comment here as it contains the approach I would like to follow to fix the last change in the project blocking
a 1.0 release:
---
So went ahead to re-design the Debug class, in a way users could still enable/disable debugging, and also use a PrintStream so that other thing rather than System.out could be used.
Then, realized removing System.out was the natural next step. But alas, the library uses System.out for debugging, but sometimes it uses it for writing to System.out in a "verbose mode". What is more complicated, is that sometimes classes methods like `toString()` are calling debug methods that receive a PrintStream already.
So I spent some more time quickly comparing what other libraries I've seen being used / or used for image processing: https://kinoshita.eti.br/2018/08/12/use-of-logging-in-java-image-processing-libraries/. Turns out only very low level libraries, such as the JNI bridge for OpenCV, im4java, and Java's ImageIO can do with just throwing Exception's.
All other libraries have one way or another of logging. Be it with JUL, SLF4J, custom loggers, or with the ol' System.out/err.
My preferred compromise for this ticket was to keep Debug, making System.out possible but optional, and mark the class internal only. Now my preferred solution is to keep the Debug internal, but add a logger to it. And then also add logging to replace where System.out is used for the "verbose" mode.
---
Any thoughts? Objections? If none, I will try to work on this issue next weekend, making the Debug class internal only, and replacing System.out by a logging utility. After that, we should be good to start preparing the vote for 1.0.
* I know it's hard to get a consensus on having logging in Commons components, as we have normally low level libraries, where using logging is not always practical. But I would now argue that Java own ImageIO is low level. But ImageJ2, Processing, OpenJPEG, and Commons Imaging are located at a higher level, some times even using it for basic image handling/parsing/reading.
* Feel free to cast a counter-argument for it, but please think whether you'd still be -0, +0 for this change. We have delayed 1.0 for a while, so if you have a strong opinion on not adding a logger, please provide an alternative for IMAGING-154. Otherwise we may fail to prepare a 1.0 release yet again, and then somebody else may have to work on it in a few months/years... one possible compromise for this, might be i) make Debug internal, ii) remove all System.out calls, which means removing the verbose flags, the checks, and calls to System.out in there.
Thanks!
Bruno
________________________________
From: Bruno P. Kinoshita <br...@yahoo.com.br.INVALID>
To: Commons Developers List <de...@commons.apache.org>
Sent: Tuesday, 6 February 2018 11:30 PM
Subject: Re: [imaging] IMAGING-154 remove Debug class
Hi sebb,
>Another aspect of debugging is ensuring that methods are small and
>easily tested independently.
>However this is difficult to do, and care must be taken to ensure that
>the public API is not unnecessarily extended..
A very good point.
The parsers in commons-imaging expose some #dump... methods (https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794).
While I can see that parsers may need to dump the data they are holding in some structured way for inspecting, reporting, serializing, etc, it looks like some other classes were affected by it too. For example...
A JPEG Segment has a #dump() method
https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
which gets defined in each subclass of Segment. It can be confusing to have a method such as #dump() in a Segment, from the point of view of someone writing a photo editor for example. The user could use that to pass his/her own logger's PrintWriter, which would make removing or changing logging in the future in commons-imaging.
If we keep the Debug class, and make it internal, there would still be these methods to take care. And there are some methods where users can provide a PrintWriter, while others instead use System.out (e.g.https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70).
Cheers
Bruno
________________________________
From: sebb <se...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>; Bruno P. Kinoshita <br...@yahoo.com.br>
Sent: Tuesday, 6 February 2018 11:06 PM
Subject: Re: [imaging] IMAGING-154 remove Debug class
On 6 February 2018 at 09:52, Bruno P. Kinoshita
<br...@yahoo.com.br.invalid> wrote:
> Hi Jorg,
>
> I'd be fine with that solution too. I think this one would cause the smaller change to the code as is.
>
> I believe my preference is still to remove the Debug class. But between logging and making Debug internal only, I'd choose making it internal.
+1
I think making it internal means it can still be dropped later.
> Looking forward to hearing what others think about these options.
>
Another aspect of debugging is ensuring that methods are small and
easily tested independently.
However this is difficult to do, and care must be taken to ensure that
the public API is not unnecessarily extended..
> Thanks
> Bruno
>
>
> ________________________________
> From: Jörg Schaible <jo...@bpm-inspire.com>
> To: dev@commons.apache.org
> Sent: Tuesday, 6 February 2018 9:24 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> Hi Bruno,
>
>
> if it might also be helpful to our users, why not keep and provide it. As
>
> I understand it, the Debug class is a tool helping in development to
>
> analyze some behavior.
>
>
> Nothing stops us from declaring this class internal (we might even put it
>
> into a package "internal" or "debug") that might be changed without
>
> further comment. Nobody may rely on it in production code, but during
>
> development it might be helpful. With such an approach we might not have
>
> a need to find a better interface to provide this functionality.
>
>
> Just my 2¢,
>
> Jörg
>
>
>
> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>
>
>> Hello,
>
>>
>
>> If memory serves me well, some time ago we had a discussion around
>
>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
>
>> 1.0 was the Debug class.
>
>>
>
>> https://issues.apache.org/jira/browse/IMAGING-154
>
>>
>
>> I finished the pull request, but Gilles raised an important point, about
>
>> discussing other alternatives first.
>
>>
>
>> Initially I am against logging in low level libraries, especially
>
>> commons components. But some time ago I had to debug TIFF issues in
>
>> commons-imaging, and having the dump methods was a tremendous help.
>
>>
>
>>
>
>> The issue is that some imaging algorithms/processing have a lot of
>
>> variables that can be altered. And keeping an eye on all of them in the
>
>> debugger can be quite hard - though not impossible.
>
>>
>
>> So all in all, now I am more confident to proceed without the Debug
>
>> class. But some users could have a hard time investigating possible
>
>> issues in the library without seeing what's going on within the library.
>
>>
>
>> IMO, that could be solved with the logging/dump features... or through a
>
>> better design, especially around exception handling/throwing. The latter
>
>> is my preferred approach. Instead of logging, I prefer - whenever
>
>> possible - that low level libraries throw exceptions and let me handle
>
>> the logging.
>
>>
>
>>
>
>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>
>> logging added to commons-imaging.
>
>>
>
>> Bruno
>
>
>
>
> ---------------------------------------------------------------------
>
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi sebb,
>Another aspect of debugging is ensuring that methods are small and
>easily tested independently.
>However this is difficult to do, and care must be taken to ensure that
>the public API is not unnecessarily extended..
A very good point.
The parsers in commons-imaging expose some #dump... methods (https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/ImageParser.java#L794).
While I can see that parsers may need to dump the data they are holding in some structured way for inspecting, reporting, serializing, etc, it looks like some other classes were affected by it too. For example...
A JPEG Segment has a #dump() method
https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/Segment.java#L34
which gets defined in each subclass of Segment. It can be confusing to have a method such as #dump() in a Segment, from the point of view of someone writing a photo editor for example. The user could use that to pass his/her own logger's PrintWriter, which would make removing or changing logging in the future in commons-imaging.
If we keep the Debug class, and make it internal, there would still be these methods to take care. And there are some methods where users can provide a PrintWriter, while others instead use System.out (e.g.https://github.com/apache/commons-imaging/blob/7e7f96857df999175bb614732e13272a82f7962a/src/main/java/org/apache/commons/imaging/FormatCompliance.java#L70).
Cheers
Bruno
________________________________
From: sebb <se...@gmail.com>
To: Commons Developers List <de...@commons.apache.org>; Bruno P. Kinoshita <br...@yahoo.com.br>
Sent: Tuesday, 6 February 2018 11:06 PM
Subject: Re: [imaging] IMAGING-154 remove Debug class
On 6 February 2018 at 09:52, Bruno P. Kinoshita
<br...@yahoo.com.br.invalid> wrote:
> Hi Jorg,
>
> I'd be fine with that solution too. I think this one would cause the smaller change to the code as is.
>
> I believe my preference is still to remove the Debug class. But between logging and making Debug internal only, I'd choose making it internal.
+1
I think making it internal means it can still be dropped later.
> Looking forward to hearing what others think about these options.
>
Another aspect of debugging is ensuring that methods are small and
easily tested independently.
However this is difficult to do, and care must be taken to ensure that
the public API is not unnecessarily extended..
> Thanks
> Bruno
>
>
> ________________________________
> From: Jörg Schaible <jo...@bpm-inspire.com>
> To: dev@commons.apache.org
> Sent: Tuesday, 6 February 2018 9:24 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> Hi Bruno,
>
>
> if it might also be helpful to our users, why not keep and provide it. As
>
> I understand it, the Debug class is a tool helping in development to
>
> analyze some behavior.
>
>
> Nothing stops us from declaring this class internal (we might even put it
>
> into a package "internal" or "debug") that might be changed without
>
> further comment. Nobody may rely on it in production code, but during
>
> development it might be helpful. With such an approach we might not have
>
> a need to find a better interface to provide this functionality.
>
>
> Just my 2¢,
>
> Jörg
>
>
>
> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>
>
>> Hello,
>
>>
>
>> If memory serves me well, some time ago we had a discussion around
>
>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
>
>> 1.0 was the Debug class.
>
>>
>
>> https://issues.apache.org/jira/browse/IMAGING-154
>
>>
>
>> I finished the pull request, but Gilles raised an important point, about
>
>> discussing other alternatives first.
>
>>
>
>> Initially I am against logging in low level libraries, especially
>
>> commons components. But some time ago I had to debug TIFF issues in
>
>> commons-imaging, and having the dump methods was a tremendous help.
>
>>
>
>>
>
>> The issue is that some imaging algorithms/processing have a lot of
>
>> variables that can be altered. And keeping an eye on all of them in the
>
>> debugger can be quite hard - though not impossible.
>
>>
>
>> So all in all, now I am more confident to proceed without the Debug
>
>> class. But some users could have a hard time investigating possible
>
>> issues in the library without seeing what's going on within the library.
>
>>
>
>> IMO, that could be solved with the logging/dump features... or through a
>
>> better design, especially around exception handling/throwing. The latter
>
>> is my preferred approach. Instead of logging, I prefer - whenever
>
>> possible - that low level libraries throw exceptions and let me handle
>
>> the logging.
>
>>
>
>>
>
>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>
>> logging added to commons-imaging.
>
>>
>
>> Bruno
>
>
>
>
> ---------------------------------------------------------------------
>
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by sebb <se...@gmail.com>.
On 6 February 2018 at 09:52, Bruno P. Kinoshita
<br...@yahoo.com.br.invalid> wrote:
> Hi Jorg,
>
> I'd be fine with that solution too. I think this one would cause the smaller change to the code as is.
>
> I believe my preference is still to remove the Debug class. But between logging and making Debug internal only, I'd choose making it internal.
+1
I think making it internal means it can still be dropped later.
> Looking forward to hearing what others think about these options.
>
Another aspect of debugging is ensuring that methods are small and
easily tested independently.
However this is difficult to do, and care must be taken to ensure that
the public API is not unnecessarily extended..
> Thanks
> Bruno
>
>
> ________________________________
> From: Jörg Schaible <jo...@bpm-inspire.com>
> To: dev@commons.apache.org
> Sent: Tuesday, 6 February 2018 9:24 PM
> Subject: Re: [imaging] IMAGING-154 remove Debug class
>
>
>
> Hi Bruno,
>
>
> if it might also be helpful to our users, why not keep and provide it. As
>
> I understand it, the Debug class is a tool helping in development to
>
> analyze some behavior.
>
>
> Nothing stops us from declaring this class internal (we might even put it
>
> into a package "internal" or "debug") that might be changed without
>
> further comment. Nobody may rely on it in production code, but during
>
> development it might be helpful. With such an approach we might not have
>
> a need to find a better interface to provide this functionality.
>
>
> Just my 2¢,
>
> Jörg
>
>
>
> Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
>
>
>> Hello,
>
>>
>
>> If memory serves me well, some time ago we had a discussion around
>
>> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
>
>> 1.0 was the Debug class.
>
>>
>
>> https://issues.apache.org/jira/browse/IMAGING-154
>
>>
>
>> I finished the pull request, but Gilles raised an important point, about
>
>> discussing other alternatives first.
>
>>
>
>> Initially I am against logging in low level libraries, especially
>
>> commons components. But some time ago I had to debug TIFF issues in
>
>> commons-imaging, and having the dump methods was a tremendous help.
>
>>
>
>>
>
>> The issue is that some imaging algorithms/processing have a lot of
>
>> variables that can be altered. And keeping an eye on all of them in the
>
>> debugger can be quite hard - though not impossible.
>
>>
>
>> So all in all, now I am more confident to proceed without the Debug
>
>> class. But some users could have a hard time investigating possible
>
>> issues in the library without seeing what's going on within the library.
>
>>
>
>> IMO, that could be solved with the logging/dump features... or through a
>
>> better design, especially around exception handling/throwing. The latter
>
>> is my preferred approach. Instead of logging, I prefer - whenever
>
>> possible - that low level libraries throw exceptions and let me handle
>
>> the logging.
>
>>
>
>>
>
>> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
>
>> logging added to commons-imaging.
>
>>
>
>> Bruno
>
>
>
>
> ---------------------------------------------------------------------
>
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>
> For additional commands, e-mail: dev-help@commons.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by "Bruno P. Kinoshita" <br...@yahoo.com.br.INVALID>.
Hi Jorg,
I'd be fine with that solution too. I think this one would cause the smaller change to the code as is.
I believe my preference is still to remove the Debug class. But between logging and making Debug internal only, I'd choose making it internal.
Looking forward to hearing what others think about these options.
Thanks
Bruno
________________________________
From: Jörg Schaible <jo...@bpm-inspire.com>
To: dev@commons.apache.org
Sent: Tuesday, 6 February 2018 9:24 PM
Subject: Re: [imaging] IMAGING-154 remove Debug class
Hi Bruno,
if it might also be helpful to our users, why not keep and provide it. As
I understand it, the Debug class is a tool helping in development to
analyze some behavior.
Nothing stops us from declaring this class internal (we might even put it
into a package "internal" or "debug") that might be changed without
further comment. Nobody may rely on it in production code, but during
development it might be helpful. With such an approach we might not have
a need to find a better interface to provide this functionality.
Just my 2¢,
Jörg
Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> Hello,
>
> If memory serves me well, some time ago we had a discussion around
> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
> 1.0 was the Debug class.
>
> https://issues.apache.org/jira/browse/IMAGING-154
>
> I finished the pull request, but Gilles raised an important point, about
> discussing other alternatives first.
>
> Initially I am against logging in low level libraries, especially
> commons components. But some time ago I had to debug TIFF issues in
> commons-imaging, and having the dump methods was a tremendous help.
>
>
> The issue is that some imaging algorithms/processing have a lot of
> variables that can be altered. And keeping an eye on all of them in the
> debugger can be quite hard - though not impossible.
>
> So all in all, now I am more confident to proceed without the Debug
> class. But some users could have a hard time investigating possible
> issues in the library without seeing what's going on within the library.
>
> IMO, that could be solved with the logging/dump features... or through a
> better design, especially around exception handling/throwing. The latter
> is my preferred approach. Instead of logging, I prefer - whenever
> possible - that low level libraries throw exceptions and let me handle
> the logging.
>
>
> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> logging added to commons-imaging.
>
> Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [imaging] IMAGING-154 remove Debug class
Posted by Jörg Schaible <jo...@bpm-inspire.com>.
Hi Bruno,
if it might also be helpful to our users, why not keep and provide it. As
I understand it, the Debug class is a tool helping in development to
analyze some behavior.
Nothing stops us from declaring this class internal (we might even put it
into a package "internal" or "debug") that might be changed without
further comment. Nobody may rely on it in production code, but during
development it might be helpful. With such an approach we might not have
a need to find a better interface to provide this functionality.
Just my 2¢,
Jörg
Am Mon, 05 Feb 2018 12:20:58 +0000 schrieb Bruno P. Kinoshita:
> Hello,
>
> If memory serves me well, some time ago we had a discussion around
> sanselan & commons-imaging 1.0. One of the issues with commons-imaging
> 1.0 was the Debug class.
>
> https://issues.apache.org/jira/browse/IMAGING-154
>
> I finished the pull request, but Gilles raised an important point, about
> discussing other alternatives first.
>
> Initially I am against logging in low level libraries, especially
> commons components. But some time ago I had to debug TIFF issues in
> commons-imaging, and having the dump methods was a tremendous help.
>
>
> The issue is that some imaging algorithms/processing have a lot of
> variables that can be altered. And keeping an eye on all of them in the
> debugger can be quite hard - though not impossible.
>
> So all in all, now I am more confident to proceed without the Debug
> class. But some users could have a hard time investigating possible
> issues in the library without seeing what's going on within the library.
>
> IMO, that could be solved with the logging/dump features... or through a
> better design, especially around exception handling/throwing. The latter
> is my preferred approach. Instead of logging, I prefer - whenever
> possible - that low level libraries throw exceptions and let me handle
> the logging.
>
>
> So, any thoughts? :) I'm +1 to remove the Debug class, and +0 to a
> logging added to commons-imaging.
>
> Bruno
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org