poi/src/ooxml/README.interfaces

            Fun with Interfaces
            -------------------

Let us consider a simple case

  public Interface IFoo {}
  public Interface IBar {
     public IFoo getFoo();
  }

  public class RealFoo implements IFoo {}
  public class RealBar implements IBar {
     public RealFoo getFoo() { return new RealFoo(); }
  }

Looks ok, doesn't it? If you access RealBar directly, you get back a
RealFoo. If you access RealBar via the IBar interface, you get back a
IFoo object instead. All looks good.

Only snag - this doesn't work with any JDK older than 1.5. If you're on
JDK 1.3 or JDK 1.4, you will get a compile time error about incompatible
return signatures.


At the moment, we're still committed to having the core of POI work on
JDK 1.3 / JDK 1.4. If you want the OOXML support, then you need to move
to JDK 1.5. This allows us a sort of work-around for the problems:

JDK 1.3 / JDK 1.4:
 You can't use the OOXML stuff anyway, so you probably don't care about
  the new interfaces
 So, have the existing code (hssf) compile against dummy interfaces, which 
  don't actually provide any methods
 You can't then use the interfaces, but you probably didn't want to anyway
 These live in src/ooxml/interfaces-jdk14

JDK 1.5:
 Compile the existing code (hssf) against full interfaces. Users can still
  use the concrete HSSF classes if they want, or if they use the interfaces,
  their code will work with the ooxml support too
 Need to change any methods that take a concrete object (eg HSSFCell) to
  take the interface (eg Cell), and cast, otherwise they're not compatible
  with the interface contract (which specifies Cell not HSSFCell).
 These live in src/ooxml/interfaces-jdk15