Jeremias Maerki wrote:
I don't think you missed anything important except maybe your
personal opinion how you'd propose to go on. :-)
Ok.
Step 0: Baseline rules.
- No new Errors except possibly some sort of a FOPConfigurationError
(JAXP implementations tend to have an equivalent). Does anybody
think we need more?
- No new RuntimeException descendants, checked exceptions only.
- Keep exception declarations lean.
- Don't wrap RuntimeExceptions thrown by lower layers unless
the wrapper contains essential additional information
- Think before committing code (this is a test :-).
Step 1: Identify subpackages which potentially are of intertest
as libraries for others and therefore should get their own
exceptions. Candidates
- PDF lib
- RTF lib
- shall we have a SVG lib, PS lib, etc? (BTW had anyone a look at
the Cairo API?)
- Font metrics, font management. Oops, already outsorced.
- Hyphenation
- Word parsing for hyphenation
- Data structure underlying the pattern hyphenator (may be reused
for automatic ligatures)
- URL handling
- Unified Image handling API. I hope we aren't reinventing JAI.
- Image cache
- Colorspace handlung (not yet implemented)
- Various Unicode stuff, in particular TR14 and BIDI handling (still
missing too)
- Character shaping (also no code yet)
Step 2: Decide how many independent exception trees per package as
identified in step 1. Proposal
- Hyphenation gets two Exceptions, one for compiling the patterns,
one for the actual hyphenation (if necessary)
- The renderer libraries should probably get one exception tree
- The smaller utility libs should be ok with existing java.lang
exceptions and perhaps IOException
- A FOPException, of course.
Necessary decisions:
- Should the Renderer and perhaps the specific renderers (not the
reusable renderer libs) get their own exceptions? I tend to say
no, but I'm still sorting arguments.
- Do we need a FOPConfigurationException?
- Do we need a FOPConfigurationError?
- How many exceptions shoudl the font subsystem get (if there's
something to decide).
Step 3: How to use exceptions from the JRE
- Renderer libs which actually do stream IO should declare IOException
instead of wrapping it.
- Something similar for the image handling API
- Reusable utility methods taking URLs (as java.net.URL/URI, perhaps
also as String?) should declare URL related exceptions rather than
wrap them.
- Everything else is probably forced to wrap, i.e. no declaration of
exceptions other than the package specific ones. I don't want to have
IOExcpetion et al declared in Java interfaces unless the majority
of the conceivable implementations will throw them.
Step 4: additional exceptions.
- FOPIOException, and possibly descendants, for wrapping IOException
- FOPPrintException, for wrapping PrintException thrown by the
print renderer. Print renderer users are likely to want to catch it.
- Does anybody ever catch a PropertyException? It may still
be useful due to the code. I also think at least some instances
of PropertyException are thrown because of validation problems.
We might want to split it into a subclass of ValidationException, a
PropertyExpressionParseException and a
PropertyExpressionEvaluationException.
- We might want to have other subclasses of FOPException indicating
specific problems with user supplied data, similar to
ValidationException.
- If there is some code repeatedly used in setting up a FOPException,
this may point to another FOPException subclass.
- It may be an idea to have a subclass of FOException which has a
Locator (or another location indication) and others which havn't
(i.e. exceptions thrown by renderers). Is it always possible to
pinpoint the FO which is related to a particular exception? There
are certainly problems where this is difficult due to asynchronity
or buffering, like "sample.foo:13: no space left on device".
- 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
Some additional thoughts: There are basically two reasons for building
an exception tree:
1. Code reuse, standard OO staple.
2. Catching specific exceptions.
An example for the second: Imagine
catch( FOOException e) {
Throwable cause = e.getCause();
if (cause instanceOf IOException) {
notifyUser(cause);
} else if (cause instanceOf BarException)
...
}
vs.
catch(FOOIOEXception e) {
notifyUser((IOException)e.getCause());
}
catch(FOOBarException e) {
...
}
Step 5: Miscellaneous
- The RTF lib exception should derive from Excetion rather than
IOException. Add IOException as necessary. Yes, this hurts.
- Do something about PDFFilterException.
- Should we use IllegalArgumentException for sanity checkings
in the public API classes (not FOTree, layout or anything deeper
down), e.g. for enumerations for renderers which aren't known?
I'm undecided. Some JRE packages do so.
That's all for today
J.Pietschmann
