            ------
            Welcome to Mirage
            ------
            Naoki Takezoe
            ------
            2010-04-18

Welcome

* What's Mirage?

 Mirage is an easy and powerful SQL centric database access library.

   * 2WaySQL

   The main feature of Mirage is 2WaySQL. This makes plain old SQL template,
   and it is executable using any SQL client tools because parameters and
   conditions are written as SQL comment.

   * SQL less Update

   Generally, update processing are simpler than search processing.
   However, especially, large INSERT SQL brings us the considerable pain.
   In the Mirage, you can insert / update / delete records using entity class (without SQL).

   []

* Quick Start

 You can get JAR file from the follwing URL:

   * {{http://sourceforge.jp/projects/amateras/releases/?package_id=10941}}

   []

** First example of Mirage

 The basic example of searching using the SQL file. <<SqlManager>> is a main interface of Mirage.
 You can get it from Session and you can control transaction using Session also.

--------
Session session = SessionFactory.getSession();
SqlManager sqlManager = session.getSqlmanager();

try {
  BookParam param = new BookParam();

  List<Book> result = sqlManager.getResultList(
    Book.class, "/META-INF/selectBooks.sql", param);

  ...

  session.commit();

} catch(Exception ex) {
  session.rollback();

} finally {
  session.release();
}
--------

 <<Book>> is a POJO to mapping ResultSet:

--------
public class Book {
  public Long bookId;
  public String bookName;
  public String author;
  public Integer price;
}
--------

 <<BookParam>> is a parameter class:

--------
public class BookParam {
  public String author;
  public Integer minPrice;
  public Integer maxPrice;
}
--------

 <</META-INF/selectProducts.sql>>:

--------
SELECT * FROM BOOK
/*BEGIN*/
  WHERE
  /*IF author != null */
        AUTHOR = /*author*/'Naoki Takezoe'
  /*END*/
  /*IF minPrice != null */
    AND PRICE >= /*minPrice*/20
  /*END*/
  /*IF maxPrice != null */
    AND PRICE <= /*maxPrice*/100
  /*END*/
/*END*/
ORDER BY BOOK_ID ASC
--------

** 2WaySQL

 Mirage supports <<2WaySQL>>. This is based on Japanese O/R mapping framework {{{http://s2container.seasar.org/2.4/ja/s2jdbc.html}S2JDBC}}.
 2WaySQL is the plain old SQL template. You can specify parameters and conditions using SQL comment.
 So these SQLs are executable using SQL client tools.

 For exmaple, the following SQL has a SQL comment(/*author*/), however it is executable as SQL.

--------
SELECT * FROM BOOK
WHERE AUTHOR = /*author*/'Naoki Takezoe'
ORDER BY BOOK_ID ASC
--------

 Mirage replaces <</*author*/>> to a place holder and removes a word (<<'Naoki Takezoe'>>) after replaced SQL comment.
 Actually, Mirage would execute the following SQL.

--------
SELECT * FROM BOOK
WHERE AUTHOR = ?
ORDER BY BOOK_ID ASC
--------

 See {{{2waysql.html}here}} to know details about 2WaySQL.

** SQL less Update

 Mirage can insert / update / delete using entity object (without SQL file).

 Entity Class must have a primary key field with <<@PrimaryKey>> annotation:

--------
public class Book {
  @PrimaryKey
  public Long bookId;
  public String bookName;
  public String author;
  public Integer price;
}
--------

 Example to insert an entity using <<SqlManager#insertEntity()>>:

--------
Book book = new Book();
book.bookName = "Mirage in Action";
book.author = "Naoki Takezoe";
book.price = 20;

sqlManager.insertEntity(entity);
--------

* Using Mirage with Maven

 If you are using Maven, you can get Mirage from the Maven repository which is provided by Project Amateras.
 Add the following fragment into your pom.xml.

----
<repositories>
  <repository>
    <id>amateras</id>
    <name>Project Amateras Maven2 Repository</name>
    <url>http://amateras.sourceforge.jp/mvn/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>jp.sf.amateras.mirage</groupId>
    <artifactId>mirage</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>
----
