[prev in list] [next in list] [prev in thread] [next in thread] 

List:       fop-dev
Subject:    Re: API discussion (revived)
From:       "J.Pietschmann" <j3322ptm () yahoo ! de>
Date:       2005-08-31 21:54:03
Message-ID: 431626FB.4090702 () yahoo ! de
[Download RAW message or body]

Jeremias Maerki wrote:
> Cairo? no. It's not Java, is it?
It's C. Nevertheless, it might provide ideas. They can render
2D graphics to PDF.

> Depends. I guess ATM we'll need a FOPConfigurationException. I don't buy
> the Error, yet.

Ok.

>>- How many exceptions shoudl the font subsystem get (if there's
>>  something to decide).
> As few as possible. Can't tell, yet.

Hehe!

>>- Renderer libs which actually do stream IO should declare IOException
>>  instead of wrapping it.
> 
> Right. But does that mean we add IOException to the throws list of all
> the render*() methods (Renderer interface and AbstractRenderer base
> class)?

The renderer implementation classes (and other FOP specific classes,
if any), should wrap the IOException.


>>- FOPIOException, and possibly descendants, for wrapping IOException
> Really???

Dunno. Nevertheless many IOExceptions indicate classic ressource
problems (disk full, connection reset by peer). Note that I/O related
java.net exceptions derive from IOException too.


>>- We might want to have other subclasses of FOPException indicating
>>  specific problems with user supplied data, similar to
>>  ValidationException.
> 
> Yes, LayoutException.

I'll check this.

> Did I mention I18N? :-)

Horror! =:-0

:-)

>>- We might want to have separate exceptions indicating real bugs rather
>>  than problems with user supplied data or ressources:
>>  * FOPNotImplementedException indicating known deficiencies
>>  * FOPInternalException thrown in "can't happen" branches
> 
> But aren't those subclasses of RuntimeException which you ruled out
> above????

I had thought of deriving them from the checked FOPException, but of
course this may cause exception declarations on methods which don't
need them for other purposes. Possibly lots of them.

Ok, let's search for reusable Exceptions. Well, not all of the
exceptions provided by the RTL are apparently supposed to be reused.
Some clearly are (IllegalStateException, Illegal ArgumentException),
because other Java packages do so.
There we find java.lang.UnsupportedOperationException. On of the JDK
docs I read suggested it was part of the container framework, which
might hint on not reusing it. But then, Java 1.4 derives a
java.awt.HeadlessException (funny name: imagine beheaded exception!),
so we might use it as well. There are also java.lang.InternalError
(might be applicable to "can't happen" tests) and
java.lang.UnknownError. Well, they are errors and using them might
cause even more programmers to catch Throwable instead of Exception
(with possibly bad consequences).

The more I think of it, the more I'm inclined to derive
FOPNotImplementedException and and FOPInternalException from 
RuntimeException, or possibly using a FOPRuntimeException for
both purposes.


Side note: From the 1.4.1 Java docs
   MissingRessourceException: Signals that a resource is missing.
Wow, talk about a comprehensive documentation.

I also noticed that designing the exception system naturally leads
to thoughts about logging. Logging is used for different purposes:
- Indicate progress
- Log warnings, which indicate the output may differ from the output
  of other FO processors. This may be caused for example by
  implementation choices because of the spec is ambiguous or left
  it explicitely to the implementation.
- Log errors which have been ignored or warnings which are actually
  errors (bad input, ressource problems, ...) which have been recovered
  from. The output may to be different from what the user expected,
  or not (an example being the infamous page-number-format="1", which
  formally *is* a syntax error).
- Log information or warnings that something happened which the user
  likely didn't expect, or tells him he is about to shoot himself into
  the foot (for example using a proprietary extension, a legal but
  commonly misunderstood construct, or a deprecated feature).
- Debugging, mainly for developers.

I'd like to throw some ideas onto the list:
- Have some sort of progress() method on the user agent for indicating
  layout/rendering progress.
- Have a warning() , error() and fatalError() method on the user agent.
  Provide a mechanism so that the user can turn recoverable errors and
  warnings into fatal errors, preferably individually.

J.Pietschmann

[prev in list] [next in list] [prev in thread] [next in thread]