com.google.code.maven-play-plugin.com.sienaproject.siena:siena

h1. Welcome to Siena project!

Latest tagged version is Siena v1.0.0-b5

bq. You can now find some "manuals":https://github.com/mandubian/siena/wiki/Manuals

Siena is a persitence API for Java inspired by the Google App Engine Python Datastore trying to draw a bridge between SQL and NoSQL worlds. It provides a Java Object-DB mapping designed following the "ActiveRecord pattern":http://en.wikipedia.org/wiki/Active_record_pattern#Java which brings a simple and intuitive approach to manage your Java objects with respect to the database entities.

h2. Where can you find us also?

• The main website is http://www.sienaproject.com but the doc is not up-to-date there as it refers to the old version 0.x of Siena.

• We have a IRC channel on freenode: ** irc server: @irc.freenode.net:6667@ ** channel: @#siena@

• You can contact the main committer of Siena using "mandubian" profile in Github or this email: [e-mail]

h2. Siena is a single API with many implementations

• SQL RDBMS (MySQL, Postgres, H2)
• NoSQL (GAE sync/async for the time being and other implementations are planned such as: MongoDB, SimpleDB, HBase...)

h2. Siena simplifies the transition between NoSQL and SQL

Siena is not meant to mimic a kind of Hibernate for NoSQL+SQL as it would be non-sense. In most cases, a model designed for SQL can be re-used in a NoSQL DB and vis-versa but it might not be optimized for the database. Siena is not meant to modify your model behind your back to optimize it for all the databases because it would be a crazy work. Siena just aims at drawing a bridge between NoSQL/SQL worlds and reduce the effort required when going from one database to the other. It ensures:

• You can use the same API for all DB.
• The model you design for a RDBMS will work with the same code in a NoSQL database and vis versa.
• Naturally, after migrating, you will optimize your model for the new database based on its specificity.
• When you want to use very specific feature of a database, you will naturally use the low-level APIs provided by this DB.

h2. Siena has a development lifecycle driven by practical use-cases and user experience

Siena doesn't try to fit in force and hide all the specific database technical aspects into your Java code. It has certainly been a false and unfulfilled promise of ORM frameworks in general: an object is not really a relational entity and SQL can't be completely hidden behind Java code. Thus, ORM often just moves the problems you had with SQL to problems you have with your ORM framework and unfortunately, you don't control your ORM framework at all as your SQL.

So we try to design siena (at least as a wishful thinking because it's not an easy and exact process :)) through a process going from the user needs to the technical aspects of SQL/NoSQL databases and not the other way. As an example, when building a web application, you often need to paginate among hundreds of entities by pages of 50 for ex. You really don't care how the DB manages its record offsets for SQL or cursors for GAE, you just want a page of 50 entities and then go to the next page and then go back to the previous page etc... So Siena provides a pagination mechanism which allows exactly this without scratching your head and this mechanism has the same behavior in SQL and NoSQL.

As a consequence, Siena is a bit more than just a Object-Mapping API, it's like a toolbox to help you build your application based on a persistence system.

h2. Siena technical design

==
==

h3. A thin layer on top of low-level DB API

Siena is meant to keep the layer between your code and the low-level database APIs as thin as possible in order to make it efficient and not to implement to much technical mechanisms on top of already complex and complete database mechanisms:

• For SQL, it directly uses JDBC
• For GAE, it directly uses GAE low-level Datastore

The biggest part of Siena DB implementations is :

• Mapping from Java types to low level DB types
• Business code to manage high level mechanism such as pagination or stateless/stateful modes

==
==

h3. Siena core is ONE jar and some tools/modules around this core library

Siena tries to be as simple as possible in its dependencies. For the time being, in order to use Siena with all DB implementations, you just need the siena.jar and the DB Jar(s) (JDBC or GAE) but nothing else. There is no hidden or transitive dependencies on other frameworks or Jars. So you can use Siena in a simple Java application or in a simple web app or in a JEE app.

Our purpose is also to provide tools or integrated modules based on this core library to use Siena in given environments.

The first module developed for Siena is "play-siena":http://www.playframework.org/modules/siena-2.0.0/home: the web framework "Play!":http://www.playframework.org is really great, really fits Siena design and provides a very good test platform.

==
==

h3. Siena is stateless by default (but can become stateful if required)

Siena is stateless by default because it really fits the majority of cases and one can use it directly without scratching his head about potential problems of releasing DB resources or committing anything. Moreover, stateless is much easier to use in scalable and distributed infrastructure such as GAE.

Yet, Siena now proposes a new stateful mode to be able to reuse DB resources several times. Thus you can:

• create a query with filters and orders and use the same query several keeping last context alive.
• iterate through the results while keeping in memory the last position.
• etc...

This stateful mode provides some interesting advanced features and we don't know yet all the practices it will bring. Siena is Open Source and is released under the Apache License 2.0.

==
==

h3. Siena provides an asynchronous mode (only for GAE for the time being)

This is a really powerful way of retrieving entities from a database. You create a query, you launch it, you do something else and when the result is ready, you get it. Asynchronism is really useful when you run long duration queries and don't want to stop all the current thread while the queries is treated.

Siena provides an easy way to go to asynchronous mode and back to synchronous.