You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pdfbox.apache.org by Maruan Sahyoun <sa...@fileaffairs.de> on 2018/01/17 17:41:54 UTC
[DISCUSS] return values for functions
Hi,
many of our methods return null in case an entry can not be found potentially causing NPEs. For 3.0 what about starting to change that so we return the expected object in the PDModel although I understand that this might mean that for some time some methods might return null where others might return the expected object.
E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case that there is no sufficient entry instead of return null we could return an empty float[].
Wouldn't expect that we start looking for such cases but doing it as we touch methods.
WDYT?
BR
Maruan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Tilman Hausherr <TH...@t-online.de>.
I have read about this concept "don't use null, return empty list
instead" often and I like it... I haven't changed anything here because
I'm always wondering whether there could be a case where we want to know
whether the object is missing, or when we write back the object and a
PDF would then have an empty object instead of nothing at all.
Tilman
Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
> Hi,
>
> many of our methods return null in case an entry can not be found potentially causing NPEs. For 3.0 what about starting to change that so we return the expected object in the PDModel although I understand that this might mean that for some time some methods might return null where others might return the expected object.
>
> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case that there is no sufficient entry instead of return null we could return an empty float[].
>
> Wouldn't expect that we start looking for such cases but doing it as we touch methods.
>
> WDYT?
>
> BR
> Maruan
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Maruan Sahyoun <sa...@fileaffairs.de>.
> Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler <an...@lehmi.de>:
>
> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>> Hi,
>> many of our methods return null in case an entry can not be found potentially causing NPEs. For 3.0 what about starting to change that so we return the expected object in the PDModel although I understand that this might mean that for some time some methods might return null where others might return the expected object.
>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case that there is no sufficient entry instead of return null we could return an empty float[].
>> Wouldn't expect that we start looking for such cases but doing it as we touch methods.
>> WDYT?
> I never thought about that. What exactly is the advantage of this strategy? In the end I'm doing "is empty checks" instead of "is not null checks".
# it lessens the risk of NPE in our code and in the users code
# it avoids duplicate checks e.g. if myList != null && myList.contains
# it eases the usage of for each if we ensure that there is an empty collection or array returned
…
Maruan
>
> Andreas
>
>> BR
>> Maruan
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Maruan Sahyoun <sa...@fileaffairs.de>.
> Am 10.02.2018 um 07:30 schrieb Tilman Hausherr <TH...@t-online.de>:
>
> Am 10.02.2018 um 07:25 schrieb Maruan Sahyoun:
>> Hi,
>>
>>> Am 09.02.2018 um 23:06 schrieb Mark Tanner <ma...@pagesuite.com>:
>>>
>>> hey all
>>>
>>> Java has quite strict enforcement of exception handling. I.e. if a method can throw an exception then the calling method must handle it, and you get plenty of compiler warnings telling you such.
>>>
>>> We can avoid NPE's by avoiding returning null from methods completely, and throwing an exception instead.
>> I'd think that throwing an exception if something required is missing is OK. Throwing an exception for retrieving an optional value is not. And that's the case we are talking about. And it's for the high level PD model within PDFbox - the API most of our users are using and should anyway.
>>
>> Now for an optional value which may or may not exist - like an drop down field options - shall we return null or an empty array(collection?
>
> Same as I said last time... I'm always wondering whether there could be a case where we want to know whether the object is missing, or when we write back the object and a PDF would then have an empty object instead of nothing at all.
if we want to know that the object is missing we could either use the COS model, which I'm not proposing to change and/or use a hasXXX method to test upfront.
>
> It also depends whether the behavior is different whether an item is empty vs an item is missing. Adobe behaves differently whether the color of a link annotation is missing (will draw a black line) or is empty (will draw nothing).
Of course we need to look at such cases and make sure that any PDFBox user can deal with that difference if he want's to. OTOH I'd rather draw a black border than throwing an NPE because I've forgootten to test that the color returned might be null. Again one shall be able to test if the key exists or has an empty value.
Many PDFBox users do have a good knowledge of the PDF specification. So they understand the difference between an optional property which is not existing or which is existing but has no value. But users who are not fluent in the PDF specification will not understand that. So they might be surprised why a method sometimes returns null where in most of the cases it doesn't.
Maruan
>
> Tilman
>
>
>>
>> BR
>> Maruan
>>
>>
>>> This will also allow us to customize the message of the exception and let the user know why they aren't getting their expected results.
>>>
>>> Any thoughts?
>>>
>>> Mark Tanner
>>> ________________________________________
>>> From: Tilman Hausherr [THausherr@t-online.de]
>>> Sent: 09 February 2018 18:50
>>> To: dev@pdfbox.apache.org
>>> Subject: Re: [DISCUSS] return values for functions
>>>
>>> Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler:
>>>> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>>>>> Hi,
>>>>>
>>>>> many of our methods return null in case an entry can not be found
>>>>> potentially causing NPEs. For 3.0 what about starting to change that
>>>>> so we return the expected object in the PDModel although I understand
>>>>> that this might mean that for some time some methods might return
>>>>> null where others might return the expected object.
>>>>>
>>>>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case
>>>>> that there is no sufficient entry instead of return null we could
>>>>> return an empty float[].
>>>>>
>>>>> Wouldn't expect that we start looking for such cases but doing it as
>>>>> we touch methods.
>>>>>
>>>>> WDYT?
>>>> I never thought about that. What exactly is the advantage of this
>>>> strategy? In the end I'm doing "is empty checks" instead of "is not
>>>> null checks".
>>>>
>>>> Andreas
>>> It's a programming style that is expected to avoid NPEs, Sonar mentions
>>> it at some places. The advantage is that you could run a loop on the
>>> result without null checking.
>>>
>>> Tilman
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Tilman Hausherr <TH...@t-online.de>.
Am 10.02.2018 um 07:25 schrieb Maruan Sahyoun:
> Hi,
>
>> Am 09.02.2018 um 23:06 schrieb Mark Tanner <ma...@pagesuite.com>:
>>
>> hey all
>>
>> Java has quite strict enforcement of exception handling. I.e. if a method can throw an exception then the calling method must handle it, and you get plenty of compiler warnings telling you such.
>>
>> We can avoid NPE's by avoiding returning null from methods completely, and throwing an exception instead.
> I'd think that throwing an exception if something required is missing is OK. Throwing an exception for retrieving an optional value is not. And that's the case we are talking about. And it's for the high level PD model within PDFbox - the API most of our users are using and should anyway.
>
> Now for an optional value which may or may not exist - like an drop down field options - shall we return null or an empty array(collection?
Same as I said last time... I'm always wondering whether there could be
a case where we want to know whether the object is missing, or when we
write back the object and a PDF would then have an empty object instead
of nothing at all.
It also depends whether the behavior is different whether an item is
empty vs an item is missing. Adobe behaves differently whether the color
of a link annotation is missing (will draw a black line) or is empty
(will draw nothing).
Tilman
>
> BR
> Maruan
>
>
>> This will also allow us to customize the message of the exception and let the user know why they aren't getting their expected results.
>>
>> Any thoughts?
>>
>> Mark Tanner
>> ________________________________________
>> From: Tilman Hausherr [THausherr@t-online.de]
>> Sent: 09 February 2018 18:50
>> To: dev@pdfbox.apache.org
>> Subject: Re: [DISCUSS] return values for functions
>>
>> Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler:
>>> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>>>> Hi,
>>>>
>>>> many of our methods return null in case an entry can not be found
>>>> potentially causing NPEs. For 3.0 what about starting to change that
>>>> so we return the expected object in the PDModel although I understand
>>>> that this might mean that for some time some methods might return
>>>> null where others might return the expected object.
>>>>
>>>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case
>>>> that there is no sufficient entry instead of return null we could
>>>> return an empty float[].
>>>>
>>>> Wouldn't expect that we start looking for such cases but doing it as
>>>> we touch methods.
>>>>
>>>> WDYT?
>>> I never thought about that. What exactly is the advantage of this
>>> strategy? In the end I'm doing "is empty checks" instead of "is not
>>> null checks".
>>>
>>> Andreas
>> It's a programming style that is expected to avoid NPEs, Sonar mentions
>> it at some places. The advantage is that you could run a loop on the
>> result without null checking.
>>
>> Tilman
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
>> For additional commands, e-mail: dev-help@pdfbox.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Maruan Sahyoun <sa...@fileaffairs.de>.
Hi,
> Am 09.02.2018 um 23:06 schrieb Mark Tanner <ma...@pagesuite.com>:
>
> hey all
>
> Java has quite strict enforcement of exception handling. I.e. if a method can throw an exception then the calling method must handle it, and you get plenty of compiler warnings telling you such.
>
> We can avoid NPE's by avoiding returning null from methods completely, and throwing an exception instead.
I'd think that throwing an exception if something required is missing is OK. Throwing an exception for retrieving an optional value is not. And that's the case we are talking about. And it's for the high level PD model within PDFbox - the API most of our users are using and should anyway.
Now for an optional value which may or may not exist - like an drop down field options - shall we return null or an empty array(collection?
BR
Maruan
>
> This will also allow us to customize the message of the exception and let the user know why they aren't getting their expected results.
>
> Any thoughts?
>
> Mark Tanner
> ________________________________________
> From: Tilman Hausherr [THausherr@t-online.de]
> Sent: 09 February 2018 18:50
> To: dev@pdfbox.apache.org
> Subject: Re: [DISCUSS] return values for functions
>
> Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler:
>> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>>> Hi,
>>>
>>> many of our methods return null in case an entry can not be found
>>> potentially causing NPEs. For 3.0 what about starting to change that
>>> so we return the expected object in the PDModel although I understand
>>> that this might mean that for some time some methods might return
>>> null where others might return the expected object.
>>>
>>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case
>>> that there is no sufficient entry instead of return null we could
>>> return an empty float[].
>>>
>>> Wouldn't expect that we start looking for such cases but doing it as
>>> we touch methods.
>>>
>>> WDYT?
>> I never thought about that. What exactly is the advantage of this
>> strategy? In the end I'm doing "is empty checks" instead of "is not
>> null checks".
>>
>> Andreas
>
> It's a programming style that is expected to avoid NPEs, Sonar mentions
> it at some places. The advantage is that you could run a loop on the
> result without null checking.
>
> Tilman
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Tilman Hausherr <TH...@t-online.de>.
Am 09.02.2018 um 23:06 schrieb Mark Tanner:
> hey all
>
> Java has quite strict enforcement of exception handling. I.e. if a method can throw an exception then the calling method must handle it, and you get plenty of compiler warnings telling you such.
>
> We can avoid NPE's by avoiding returning null from methods completely, and throwing an exception instead.
>
> This will also allow us to customize the message of the exception and let the user know why they aren't getting their expected results.
Many nulls are returned by our methods because an optional item doesn't
exist. So it isn't abnormal, so an exception wouldn't make sense.
Tilman
>
> Any thoughts?
>
> Mark Tanner
> ________________________________________
> From: Tilman Hausherr [THausherr@t-online.de]
> Sent: 09 February 2018 18:50
> To: dev@pdfbox.apache.org
> Subject: Re: [DISCUSS] return values for functions
>
> Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler:
>> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>>> Hi,
>>>
>>> many of our methods return null in case an entry can not be found
>>> potentially causing NPEs. For 3.0 what about starting to change that
>>> so we return the expected object in the PDModel although I understand
>>> that this might mean that for some time some methods might return
>>> null where others might return the expected object.
>>>
>>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case
>>> that there is no sufficient entry instead of return null we could
>>> return an empty float[].
>>>
>>> Wouldn't expect that we start looking for such cases but doing it as
>>> we touch methods.
>>>
>>> WDYT?
>> I never thought about that. What exactly is the advantage of this
>> strategy? In the end I'm doing "is empty checks" instead of "is not
>> null checks".
>>
>> Andreas
> It's a programming style that is expected to avoid NPEs, Sonar mentions
> it at some places. The advantage is that you could run a loop on the
> result without null checking.
>
> Tilman
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
RE: [DISCUSS] return values for functions
Posted by Mark Tanner <ma...@pagesuite.com>.
hey all
Java has quite strict enforcement of exception handling. I.e. if a method can throw an exception then the calling method must handle it, and you get plenty of compiler warnings telling you such.
We can avoid NPE's by avoiding returning null from methods completely, and throwing an exception instead.
This will also allow us to customize the message of the exception and let the user know why they aren't getting their expected results.
Any thoughts?
Mark Tanner
________________________________________
From: Tilman Hausherr [THausherr@t-online.de]
Sent: 09 February 2018 18:50
To: dev@pdfbox.apache.org
Subject: Re: [DISCUSS] return values for functions
Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler:
> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>> Hi,
>>
>> many of our methods return null in case an entry can not be found
>> potentially causing NPEs. For 3.0 what about starting to change that
>> so we return the expected object in the PDModel although I understand
>> that this might mean that for some time some methods might return
>> null where others might return the expected object.
>>
>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case
>> that there is no sufficient entry instead of return null we could
>> return an empty float[].
>>
>> Wouldn't expect that we start looking for such cases but doing it as
>> we touch methods.
>>
>> WDYT?
> I never thought about that. What exactly is the advantage of this
> strategy? In the end I'm doing "is empty checks" instead of "is not
> null checks".
>
> Andreas
It's a programming style that is expected to avoid NPEs, Sonar mentions
it at some places. The advantage is that you could run a loop on the
result without null checking.
Tilman
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Tilman Hausherr <TH...@t-online.de>.
Am 09.02.2018 um 19:20 schrieb Andreas Lehmkuehler:
> Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
>> Hi,
>>
>> many of our methods return null in case an entry can not be found
>> potentially causing NPEs. For 3.0 what about starting to change that
>> so we return the expected object in the PDModel although I understand
>> that this might mean that for some time some methods might return
>> null where others might return the expected object.
>>
>> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case
>> that there is no sufficient entry instead of return null we could
>> return an empty float[].
>>
>> Wouldn't expect that we start looking for such cases but doing it as
>> we touch methods.
>>
>> WDYT?
> I never thought about that. What exactly is the advantage of this
> strategy? In the end I'm doing "is empty checks" instead of "is not
> null checks".
>
> Andreas
It's a programming style that is expected to avoid NPEs, Sonar mentions
it at some places. The advantage is that you could run a loop on the
result without null checking.
Tilman
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org
Re: [DISCUSS] return values for functions
Posted by Andreas Lehmkuehler <an...@lehmi.de>.
Am 17.01.2018 um 18:41 schrieb Maruan Sahyoun:
> Hi,
>
> many of our methods return null in case an entry can not be found potentially causing NPEs. For 3.0 what about starting to change that so we return the expected object in the PDModel although I understand that this might mean that for some time some methods might return null where others might return the expected object.
>
> E.g. in PDAnnotationTextMarkup.getQuadPoints() in the unlikely case that there is no sufficient entry instead of return null we could return an empty float[].
>
> Wouldn't expect that we start looking for such cases but doing it as we touch methods.
>
> WDYT?
I never thought about that. What exactly is the advantage of this strategy? In
the end I'm doing "is empty checks" instead of "is not null checks".
Andreas
>
> BR
> Maruan
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
> For additional commands, e-mail: dev-help@pdfbox.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@pdfbox.apache.org
For additional commands, e-mail: dev-help@pdfbox.apache.org