===============================================================================
Apache Jackrabbit SPI - FAQ
===============================================================================

Q: why defining a SPI?
A: see README.txt


Q: why doesn't it work?
A: please note the the SPI contribution is still in an early stage and work
   in progress. interfaces and implementations are still matter to change
   and up to now almost no tests have been performed.
   As soon as the SPI is more or less stable the normal JCR test suite can
   be used to assert JSR 170 compliance.


Q: Is there a working plan for the SPI? 
A: No. we work on this as time permits.


Q: Is there any schedule for the SPI project?
A: No. See above.


Q: What is the difference between JCR API and the SPI? They look similar.
A: The SPI is basically a low level API that covers all the functionality 
   provided by the existing JCR API but does not require implementing 
   the transient layer of the JCR stack.


Q: What is the status of the SPI project?
A: The SPI is still in an early draft version. The next step would be to
   complete the prototype (jcr2spi) in order test the feasibility of the SPI.


Q: Can the SPI be addressed directly by clients? And what would this mean for
   the current SPI api?
A: Up to now, we considered, that clients should use the JSR 170 API and should
   not operate on the SPI directly.


Q: why does the core project not use the SPI?
A: The jackrabbit core project represents the reference implementation of
   JSR 170. Introducing an SPI is a recent approach that hopefully allows to
   provide a JCR client covering the transient layer only. See also the
   README.txt for some rationals regarding defining a SPI. 


Q: why does the SPI subproject have a dependency to jackrabbit commons?
A: see next Q.


Q: why do the SPI interfaces used a final QName/Path class instead of defining
   interfaces?
A: this has been matter of long discussions.
   originally no QName/Path classes were present in the SPI. instead they were
   represented by Strings.
   In a second step we introduced QName and QPath interfaces to the SPI
   and added the implementation to our own 'commons' project.
   While preparing the existing efforts for a checkin into jackrabbit, we 
   decided, that there should be only one commons project within Jackrabbit.
   therefore we removed the interfaces again from the SPI project, since it would
   not be possible to have jackrabbit code depend on a contribution.
   -> we will probably address this issue again.


Q: jcr2spi looks like jackrabbit/core code. why are all the classes copied?
A: originally we planned to use jackrabbit/core for the jcr2spi implementation.
   however, we realized that its not feasible to plug different implementations
   of the crucial interfaces in the core. Therefore we decided to copy over
   the code and modify it according to the needs of the SPI.


Some questions arising from issues still being discussed:

Q: Why does the RepositoryService does not provide methods batch reads? 
Q: Is there need for special handling of very large values in SPI?
Q: Should the SPI define a XASessionInfo or should the transaction handling
   be left out from the interfaces?
Q: Should credentials, workspaceName and all kind of tokens be passed to every 
   RepositoryService call instead of having a SessionInfo?
   (currently we don't thinks so. we had that in the beginning).
Q: RepositoryService.executeQuery(): should it take an offset?
Q: QueryInfo: should it take a flag rating the results?
Q: QueryInfo: should it rather return NodeInfos instead of Ids?