One thing I'd have liked to see is an indicator of which packages are intended as API packages for public consumption, and which packages are implementation.
The idea being that I'd like to minimise dependencies on 'private' API. There're a few incentives to do that: * making sure you're using a well-trodden code paths - they tend to be well tested; * reducing the likelihood of having to rework code when upgrading to later versions; * ensuring you're not caught out if iBATIS ever gets an OSGI MANIFEST.MF, which prevents importing private packages. For example, right now I have a dependency on BoundSql - and I've no idea whether that's likely to be maintained as part of a stable API. I don't share the cynicism about Javadoc - I can think of plenty of libraries outside the JDK with useful Javadoc. For example, the Apache Commons javadocs tend to be very good, describe corner-cases like null-handling, and have class javadocs that show useful examples. I've been completely baffled by how MetaClass, MetaObject, ObjectFactory and ObjectWrapper and ObjectWrapperFactory are related, and what they're used for. I don't know whether they're all considered public API, but I've had to trace through them tracking down bugs. Martin On 7 April 2010 16:53, cowwoc <cow...@bbs.darktech.org> wrote: > Clinton, > > I'm not looking for a specification in that sense of the word :) I meant > something along the lines of Design by Contract: > http://en.wikipedia.org/wiki/Design_by_contract > > If my code depends on iBatis and upgrading to a newer version breaks my > code then how do we establish whether the problem is: > > 1. The iBatis implementation no longer conforms to its specification (i.e. > an iBatis bug) > 2. My code assumed something about an iBatis method that was not guaranteed > by the specification (i.e. a bug in my application) > > Thanks, > Gili > > On 07/04/2010 9:50 AM, Clinton Begin wrote: > > Then you might be happier with a spec like JPA. Although I'd warn that such > specs are rarely implemented consistently. > > This is what has killed J2EE vs. the alternatives. Look at the history: > > * CMP - Spec. Dead, along with all implementations. > > * EJB - Spec. Dead. Spring killed it -- not a spec. > > * JDO - Spec. Dead, along with all implementations. > > * JSF - DOA. Bad idea to begin with, and has failed to unify client side > Java. Struts, GWT, Wickett, Stripes, ZK, Tapestry, etc. all still exist -- > and are more popular than JSF -- all without a spec. > > Some specs have succeeded, due to their simplicity and natural interface > boundary (usually a network connection requiring a driver of sorts). These > include Servlet, JDBC and JMS. Even though they're not the nicest, they're > simple and necessary. Yet they too differ in many ways, especially JDBC. > JPA has a chance, but only because they essentially took the two most > popular frameworks that weren't specs and made them into a spec... nobody > will be winning any innovation awards for that one. > > The spec doesn't guarantee anything. Kind of like a green light doesn't > guarantee that cars won't be driving through the opposing red light at an > intersection... do you not check? > > The only thing that defines how a framework will work is the framework > itself -- spec or not. The only protection you have is your own unit, > functional and integration tests -- which you need anyway, as it's also the > only way you'll know if YOUR code works. > > We've created a user guide to describe the intended behavior of the iBATIS > framework. If it is somehow incomplete or incorrect, you can contribute to > it via the wiki discussed on page 2. > > Clinton > > > > On Tue, Apr 6, 2010 at 10:37 PM, cowwoc <cow...@bbs.darktech.org> wrote: >>> >>> Yes, iBATIS will rollback the connection if it deems it necessary. The >>> only >>> time you might need to call rollback explicitly is if you have a "select" >>> that actually updates data in the database. Such is sometimes the case >>> with >>> stored procedures. >>> >> >> Clinton, >> >> Coming back to our earlier discussion of Javadoc... where do you document >> the iBatis specification? I hope you understand my reluctance of depending >> on behavior outside of an explicit specification. Today one person will tell >> me the method works one way, tomorrow another person will tell me a >> different story. I'd love to have an official document to refer back to. >> >> Thanks, >> Gili >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: user-java-unsubscr...@ibatis.apache.org >> For additional commands, e-mail: user-java-h...@ibatis.apache.org >> > > > --------------------------------------------------------------------- To unsubscribe, e-mail: user-java-unsubscr...@ibatis.apache.org For additional commands, e-mail: user-java-h...@ibatis.apache.org
