On Friday 25 May 2001 04:24, Peter Becker wrote:
Hello,
> > I think Thierry will ellaborate on the
> > reason-why of the Transcoder API, but note that
> > we were aware of the trade-offs and that (right or wrong ?), we decided
> > to go with a generic interface that would accomodate for various types
> > of Transcoders. Our goal was to create a simple API that would be
> > easy to learn and understand.
>
> The API is ok, using the classes is even worse than the usual Java ;-)
When I started thinking of the design of the transcoder module, my main goal
was to try to provide a common API for all transcoders. In fact, we
identified two simple solutions.
1. Each transcoder has its own and custom API. The main advantages is strong
typing for the various parameters. Errors will be also detected at the
compile time.
2. Try to design a common API for all transcoders. The main advantage is that
users have to learn one API and then can use all transcoders available in
Batik (switching them, extending them easily...).
What we have done is a mix of both solutions. You can use the generic API as
a first shot then switch to the custom API of a particular transcoder if you
need it (BTW only the generic API is documented - custom API are documented
by their own).
If you think of a generic API, there is no magic solution. Similar to the
RenderingHints class of the 2D API, errors (bad type for parameters...) can
only be detected at runtime.
> That's my point. Not only that compile-time type checking has a number
> of advantages in itself (e.g. errors are found even if the code is not
> executed in your tests), it was mainly the documentation aspect that
> annoyed me. If a parameter has a specific type I expect to be able to
> use this type, not descendants (BTW: this is IMHO the real reason why
> the lack of parametrized classes in Java is a Bad Thing (tm): I can't
> specifiy that I want a list of MyType objects). And although I have to
> admit that my favoured way of finding the right methods and parameters
> is JBuilders CodeInsight feature, ...
I agree that compile-time errors are best. If you need strong typing, I
invite you to use the custom API of the transcoder you need.
I agree that the documentation may be not up-to-date but according to the
example, you should have guess no? :) If you have time to improve the
documentation or contribute some FAQs entries, feel free to contribute...
> "... For example, the image transcoders accept an SVG
> org.w3c.dom.Document, ... as an input ..."
OK the sentence is not good. The implicit thing is that an SVG
org.w3c.dom.Document is a org.w3c.dom.svg.SVGDocument.
Sorry about that.
> I still can't see where the trade-off is. You state in multiple
> locations to support the org.w3c.dom... interfaces but in fact you just
> support your own implementation. If your trade-off is between
> flexibility (the W3C interface) and easy of implementing (just your
> implementation) then you didn't document it and lead me to wring
> assumptions.
The trade-off is that the transcoder API is *not* dedicated to a particular
transcoder (not only for the ImageTranscoder) though it seems that it's the
one people commonly use. You can take a look at the SVGTranscoder (pretty
printer) or the WMF transcoder... - they work fine a generic DOM
implementation.
> > org.apache.batik.util.DOMUtilities.deepCloneDocument).
>
> Ahh -- that seems to be what I tried to find yesterday. Can you tell me
> how I should have found this? Even now that I know where it is I can't
> see this. And again: the return value of this method is the interface,
> not the implementation but if I understand the interface right it means:
> convert a foreign document into our format. The aspect "foreign" is
> somehow covered by the fact that you want a DomImplementation object but
> why don't you state that you return SVGDocument? Keeping parameters
> generic is useful (if you can hold your promise) but I can't see why you
> can't state exactly what you return since you don't override a method here.
We simply do not return an SVGDocument because this method is not dedicated
to transform a Document into an SVGDocument. We clone a Document using
another DOMImplementation. This method can be used to transform a Document
into an SVGDocument if you specify the Batik DOM Implementation - but you can
also use this method to transform an SVGDocument into a xerces Document for
example.
> BTW: while talking about documentation -- check out
> http://doc.trolltech.com on a really good example on how to write source
> docu (just read some class description to know what I mean). This is the
> way I try to do it (but usually I don't really achieve it due to the
> common reasons. ;-) ) For the counterexample check most Java libraries,
> e.g. AWT. Usually I can derive more information from the signature of a
> method (which I can see after pressing the dot) than from the
> description of the method. Since the classes themself are not described
> either I gave up looking into this documentation unless I want to find
> some hierarchical relations. And Literate Programming and AWT is quite
> different, too: I really need some documentation from time to time.
I know trolltech documentation. I agree that the documentation is nice but we
are actually out of time to write tutorials or detailed documentation. We are
trying to do our best both for the Batik code and its documentation. I tend
to agree that much time has been dedicated to the code rather than the
documentation :) We will try to improve that as soon as possible.
> An API is a contract. You tell people what you want and what you give
> back. I gave you what you claimed you wanted and you told me: "go away!
> we don't like THIS". That's how I see it and I think it is a common view
> with software engineers (although not with hackers). In fact I'd love to
> have some way to state more like this -- I guess it is time for me to
> learn Eiffel ;-)
I learned Eiffel btw :) The problem is much more compicated than especially
when you are designing a toolkit. Genericity and strong typing are not good
friends generally (and more specifically in Java).
> - useful feedback on error is a nice thing but a real good design
> doesn't allow errors
I agree with that but in real world, there is no perfect solution. We could
have done a simple thing: no transcoder API :) You will have strong typing
everywhere and only compile-time errors. In this way, users will also have to
learn one API per transcoder. I really believe that learning once and just
quickly check the errors if any is a valuable solution.
> In programming terms this means for me:
> - write your code (and most important: the APIs) to be easy to read in
> itself, good code doesn't need much documentation (although nowadays I
> find that most good code is documented well while badly designed code is
> close to no documentation (see above for examples))
> - try to use as much static type checking as possible. Static (i.e.
> compile time) type checking ensures that you get what you want, that
> other people know what you want and that the compiler ensures that this
> contract is held by both parties. Using RTTI when you could use static
> type safety is a major design flaw IMHO since you allow your clients to
> make more errors
Once, I agree. If you have a proposal for a new Transcoder API - I will be
happy. We can work on that if you have time.
> Sorry if this sounds too academic and is somehow OT but switching from
> C++/Qt to Java/Swing made me think a lot on programming languages and
> now I rant more on Java than I ever did on C++ before ;-) At least I
> _can_ write good code in C++ (if it only would have garbage collection).
> I think when I finished the next release of my program I should recreate
> my private site and put an article "Why Java is Evil" on it to avoid
> writing too much OT stuff on lists like this ;-)
Sorry to hear that. May be you need to learn Java the same time you have
studied C++ :) My feeling is that good programmers are doing good code what
ever the language is.
Thierry.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
