summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBrian S. O'Neill <bronee@gmail.com>2006-10-20 19:48:50 +0000
committerBrian S. O'Neill <bronee@gmail.com>2006-10-20 19:48:50 +0000
commite3c30458c08d402b8baeb1a82e2cea04c428e64f (patch)
tree9dd9620b17e2eda4140c34d0b333c4821ba4d5f0
parent04f045ec5cb75198e809558a31aac71dbd46f47e (diff)
Expand overview.
-rw-r--r--pom.xml8
-rw-r--r--src/site/apt/index.apt116
2 files changed, 120 insertions, 4 deletions
diff --git a/pom.xml b/pom.xml
index f860e90..a81b131 100644
--- a/pom.xml
+++ b/pom.xml
@@ -168,6 +168,14 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <configuration>
+ <outputEncoding>UTF-8</outputEncoding>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jxr-plugin</artifactId>
<configuration>
<aggregate>true</aggregate>
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 7e70fd8..f9a1ec1 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -4,8 +4,116 @@
Carbonado
- Carbonado is an extensible, high performance persistence abstraction layer for Java
- applications, providing a relational view to the underlying persistence technology.
- The Carbonado project is still in the planning phases, so don't expect to find
- anything interesting here yet.
+ Carbonado is an extensible, high performance persistence abstraction layer
+for Java applications, providing a relational view to the underlying
+persistence technology. The persistence layer can be a JDBC accessible SQL
+relational database, or it can be a BDB. It can also be fully replicated
+between the two.
+ Even if the backing database is not SQL based, Carbonado still supports
+many of the core features found in any kind of relational database. It supports
+queries, joins, indexes, and it performs query optimization. When used in this
+way, Carbonado is not merely a layer to a relational database, it <is> the
+relational database. SQL is not a requirement for implementing relational
+databases.
+
+ Defining new types in Carbonado involves creating an interface or abstract
+class which follows Java bean conventions. Additional information is specified
+by inserting special annotations. At the very least, an annotation is required
+to specify the primary key. Annotations are feature first available in Java 5,
+and as a result, Carbonado depends on Java 5.
+
+ On the surface, it may appear that Carbonado types are defined like POJOs.
+The difference is that in Carbonado, types are object representations of
+relations. It is not an object database nor an object-relational bridge. In
+addition, data type defintions are simply interfaces, and there are no external
+configuration files. All the code to implement types is auto-generated, yet
+there are no extra build time steps.
+
+ Carbonado is able to achieve high performance by imposing very low overhead
+when accessing the storage layer. Low overhead is achieved in part by auto
+generating performance critical code, via the open source Cojen library.
+
+* Terminology
+
+ Loose mapping from Carbonado terminology to SQL terminology:
+
+*---------------------+-------------------------+
+| <<Carbonado>> | <<SQL>> |
+*---------------------+-------------------------+
+| Repository | database |
+*---------------------+-------------------------+
+| Storage | table |
+*---------------------+-------------------------+
+| Storable definition | table definition |
+*---------------------+-------------------------+
+| Storable instance | table row |
+*---------------------+-------------------------+
+| property | column |
+*---------------------+-------------------------+
+| Query | select/delete statement |
+*---------------------+-------------------------+
+| Cursor | result set |
+*---------------------+-------------------------+
+
+* Limitations
+
+ Carbonado queries are not as expressive as SQL selects. Unlike SQL,
+Carbonado queries do not support things like sub-selects or data
+processing. See Carbonado
+{{{http://sourceforge.net/tracker/?group_id=171277&atid=857357}feature
+requests}}.
+
+ Carbonado supports the minimal querying capability that makes automatic
+index selection possible. Other features available in SQL can be emulated in
+code. If the database is local, then this offers no loss of performance.
+
+ Applications that wish to use Carbonado only as a convenient layer over SQL
+will not be able to use full SQL features. Carbonado is by no means a
+replacement for JDBC. These kinds of applications may choose a blend of
+Carbonado and JDBC. To facilitate this, access to the JDBC connection in use by
+the current transaction is supported.
+
+ The Carbonado repositories that are backed by BDB use a simple rule-based
+query optimizer to come up with a query plan. Cost-based optimizers are
+generally much more effective, since they estimate I/O costs. Carbonado has a
+rule-based optimizer mainly because it is easier to write.
+
+* Persistence Layer Requirements
+
+ Carbonado is capable of supporting many different kinds of persistence
+layers. A minimum set of features is required, however, in order to provide
+enough Carbonado features to justify the effort:
+
+ * Arbitrary keys and values
+
+ * Get value by key
+
+ * Put value by key (does not need to distinguish insert vs update)
+
+ * Delete value by key
+
+ * Ordered key iteration
+
+ * Iteration start specified via full or partial key
+
+ []
+
+ Ideally, the persistence layer should support transactions. If it does not,
+then its transactions must be implemented by batching updates in memory. Upon
+commit, the updates are made to the persistence layer. If atomic batch updates
+are supported, then the repository can report supporting an isolation level of
+"read committed". Otherwise, it can only support the lowest level of "read
+uncommitted".
+
+ Additional features which are nice to have, but not strictly required:
+
+ * Reverse iteration
+
+ * ACID transactions
+
+ * Storable type segregation (eliminates need to define key prefixes)
+
+ * Truncation by storable type, if segregated
+
+ []