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