From e3c30458c08d402b8baeb1a82e2cea04c428e64f Mon Sep 17 00:00:00 2001 From: "Brian S. O'Neill" Date: Fri, 20 Oct 2006 19:48:50 +0000 Subject: Expand overview. --- src/site/apt/index.apt | 116 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 112 insertions(+), 4 deletions(-) (limited to 'src/site/apt') 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 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: + +*---------------------+-------------------------+ +| <> | <> | +*---------------------+-------------------------+ +| 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 + + [] -- cgit v1.2.3