Updated FAQ.

1 files changed, 87 insertions, 19 deletions

diff --git a/src/site/fml/technical-faq.fml b/src/site/fml/technical-faq.fml
index efe69d1..4d33328 100644
--- a/src/site/fml/technical-faq.fml
+++ b/src/site/fml/technical-faq.fml
@@ -206,19 +206,11 @@ JDBC DataSource that logs all activity. Provided in the JDBC repository package
 is the LoggingDataSource class, which does this. As a convenience, it can be

 installed simply by calling setDataSourceLogging(true) on the

 JDBCRepositoryBuilder.

-       </p>

-     </answer>

-   </faq>

-

-   <faq id="jdbc-indexes">

-     <question>What happens if JDBC repository cannot get index info?</question>

-     <answer>

-       <p>

-The JDBC repository checks if the Storable alternate keys match those defined

-in the database. To do this, it tries to get the index info. If the user

-account does not have permissions, a message is logged and this check is

-skipped. This should not cause any harm, unless the alternate keys don't

-match. This can cause unexpected errors when using the replicated repository.

+</p>

+<p>

+Alternatively, you can call Query.printNative(), which by default prints the

+native query to standard out. When using the JDBC repository, this will print

+the SQL statement.

        </p>

      </answer>

    </faq>

@@ -227,10 +219,8 @@ match. This can cause unexpected errors when using the replicated repository.
      <question>How do I use MySQL auto-increment columns?</question>

      <answer>

        <p>

-As of 2006-10-23, Carbonado MySQL support is very thin. The @Sequence

-annotation is intended to be used for mapping to auto-increment columns, if the

-database does not support proper sequences. Until support is added,

-auto-increment columns will not work.

+Carbonado version 1.1 has thin support for MySQL. Version 1.2 (in the 1.2-dev branch)

+supports an @Automatic annotation for supporting MySQL auto-increment columns.

        </p>

      </answer>

    </faq>

@@ -246,6 +236,24 @@ is that there can be only one primary, but many alternate keys are allowed.
      </answer>

    </faq>

 

+   <faq id="caching">

+     <question>What kind of caching does Carbonado provide?</question>

+     <answer>

+       <p>

+Carbonado does not require repository implementations to perform any

+caching. If you're using just the JDBC repository, there's no cache. A general

+purpose caching repository was in development, but it was shelved because there

+was no immediate need for it. The replicated repository however, can be

+considered to be a complete cache.

+</p>

+<p>

+The only built in caching is for join properties on Storable instances. It just

+lazily sets the join result to an internal field of the Storable instance. The

+join property value is not shared with other Storable instances.

+        </p>

+     </answer>

+   </faq>

+

    <faq id="join-cache">

      <question>How does one manually flush the Carbonado join cache?</question>

      <answer>

@@ -316,8 +324,68 @@ the repository might hold in advance?
 </p>

 <p>

 Repositories that implement StorableInfoCapability provide this

-functionality. The reason its a capability is that some repos (JDBC) don't have

-a registry of storables. BDB based ones do, and so this capability works.

+functionality. The reason it's a capability is that some repos (JDBC) don't have

+a registry of storables. BDB based ones do, and so this capability works for that.

+</p>

+     </answer>

+   </faq>

+

+   <faq id="index-integrity">

+     <question>Are explicit transactions required to ensure index integrity?</question>

+     <answer>

+       <p>

+The short answer is no -- index integrity is ensured automatically. More details follow:

+</p>

+<p>

+When using the JDBC repository, it is up to the database vendor to ensure that

+insert/update/delete operations include index updates within an implicit

+auto-commit transaction. All the major database vendors do this properly

+already, so nothing special needs to be done here.

+</p>

+<p>

+When using a BDB backed repository, it is up to Carbonado to ensure implicit

+transactions are used. Carbonado sets up BDB to be in transaction mode, and

+there's no Carbonado level config to disable this. So you're always using BDB

+with transactions, and that is good. When you do a lone Carbonado

+insert/update/delete operation, it will pass null to BDB for the transaction

+object, which implies auto-commit. BDB will automatically enter a tiny

+transaction to protect that little change.

+</p>

+<p>

+If the Storable you're updating has any indexes on it, a Carbonado trigger is

+installed that updates the affected indexes when you do an

+insert/update/delete. The presence of the trigger changes how the

+auto-generated Storable behaves. The insert/update/delete operation enters a

+transaction automatically, and it doesn't commit until all triggers have

+run. Index updates are therefore guarded by transactions, even if you don't

+explicitly specify one. In addition, all changes made by your own triggers are

+always guarded by a transaction.

+</p>

+     </answer>

+   </faq>

+

+   <faq id="delete-from-cursor">

+     <question> How do I delete Storables returned by a Cursor without deadlocks?</question>

+     <answer>

+       <p>

+The cursor iteration and delete operations must be enclosed in the same

+transaction. Auto-commit delete while iterating over a cursor fails for some

+databases, BDB and BDB-JE in particular. Although BDB supports a delete

+operation on the cursor itself, the transaction requirement remains.

+</p>

+<p>

+A workaround exists when using BDB-JE, which works only due to its use of

+record-level locks. Calling Cursor.hasNext() forces the cursor to move past the

+current record, releasing the lock on the record to be deleted. BDB native uses

+page locks, so this trick will only work in the occasional case that the next

+record is on another page.

+</p>

+<p>

+The BDB-JE cursor implementation could be changed to automatically move to the

+next record, but this reduces portability. Also, the cursor should not move

+past the current record automatically if in a transaction. It would allow

+another thread to sneak in and modify the record. An isolation level of

+repeatable read would be required to keep the lock.

 </p>

      </answer>

    </faq>