<?xml version="1.0" encoding="UTF-8"?>
<book xmlns:ci="http://apache.org/cocoon/include/1.0">
    <bookinfo>
        <graphic fileref="logo.jpg"/>
        <productname>Open Source Native XML Database</productname>
        <title>Cluster Journal description</title>
        <author>
            <firstname>Piranha</firstname>
            <surname>Group</surname>
        </author>
    </bookinfo>
    <ci:include src="sidebar.xml"/>
    <chapter>
        <title>Cluster Journal desription</title>
        <section>
            <title>Overview</title>
            <para>In this chapter is presented the Cluster Journal.</para>
            <para>all the configuration is performed in
                <filename>conf.xml</filename>, for more information see
                <ulink href="cluster.xml">cluster configuration docu</ulink>
            </para>
        </section>
        <section>
            <title>Journal</title>
            <para>
                Every node of the cluster maintains an index file (one row for every propagated event) named jei.jbx
                and n files (0.jbx, 1.jbx etc...) that store serialized events.
            </para>
            <para>
                The format of index file is:

                <programlisting format="linespecific">
                [header]
                [item1 ]
                .........
                [itemN ]

                [header] := [LAST_ID_SAVED|MAX_ID_SAVED|ACTIVE_COUNTER]
                [item-i] := [ID | START_DATA_FILE | END_DATA_FILE | FILE_NAME | CONUTER ]
                </programlisting>
            </para>
            <para>
                All data are integer :
                <itemizedlist>
                    <listitem>ID is the event identifier. This is unique in the cluster and is generated from the coordinator</listitem>
                    <listitem>START_DATA_FILE is the position (in byte) in the store file where starts the event serialization</listitem>
                    <listitem>END_DATA_FILE is the position (in byte) in the store file where ends the event serialization</listitem>
                    <listitem>FILE_NAME integer name of the store file (the file names FILE_NAME.jbx)</listitem>
                    <listitem>COUNTER is the last index file rotation whene the event was written</listitem>
                </itemizedlist>
            </para>
            <para>
                If an event must be retrieved, the id row in index file is read. FILE_NAME.jbx is opened (RandomAccessFile) and chunk from START_DATA_FILE to END_DATA_FILE
                is retrieved. This bytes are the object event serialized.
            </para>
            <para>
                Store file has a max dimension of 10Mb.
                If this dimension is exceeded a new store file is created.
                In this version, old files is not removed.
            </para>
        </section>
        <section>
            <title>Writing of Journal file</title>
            <para>
                Journal is written on file every synchronization. Whene max dimenzion si reached, a rotation is performed (ID becomes 0
                and counter is increased by 1).
                Whene a node start, it's index file is comparad to the one of the coordinator. If header is not equals, the node is declared
                disaligned and a realigment is forced. The coordinator sends all the event (from node:max_id_save - 20 to coordinator:max_id_saved)
                and node reexecute all the event not previously executed.
            </para>
        </section>
        <section>
            <title>ID event generation</title>
            <para>
                Coordinator generates unique ID and every node use this generation to retrieve event ID.
                Whene event is stored on journal , internal node id counter is increased so node is aligned.
            </para>
        </section>
        <section>
            <title>Master crash</title>
            <para>
                Whene master crash, nodes is unable to retrieve event ID. In this case node catch a <filename>SuspectedException</filename>
                and tries again to recover the id from the new coordinator.
            </para>
        </section>
    </chapter>
</book>
