<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="architecture">
  <title>Architecture</title>
  <section>
    <title>Terminology</title>
    <itemizedlist>
      <listitem>
        <para>VM or Process – a JBossAS instance running Teiid.  
        </para>
      </listitem>
      <listitem>
        <para>Host – a machine that is “hosting” one or more VMs.</para>
      </listitem>
      <listitem>
        <para>Service – a subsystem running in a VM (often in
          many VMs) and providing a  related set of functionality</para>
      </listitem>
    </itemizedlist>
    <para>In addition to these main components, the service platform
      provides a core set of services available to applications built on
      top of the service platform.  These services are:</para>
    <itemizedlist>
      <listitem>
        <para>Session – the Session service manages active
          session information.
        </para>
      </listitem>
      <listitem>
        <para>Buffer Manager – the <link linkend="buffer_management">Buffer Manager</link> service
          provides access to data management for intermediate results.</para>
      </listitem>
      <listitem>
        <para>Transaction – the Transaction service
          manages global, local, and request scoped transactions.  See also the documentation on <link linkend="transaction_support">transaction support</link>.</para>
      </listitem>
    </itemizedlist>
  </section>
  <section>
    <title>Data Management</title>
    <section>
      <title>Cursoring and Batching</title>
      <para> Teiid cursors all results, regardless of whether they
        are from one source or many sources, and regardless of what type
        of processing (joins, unions, etc.) have been performed on the
        results.</para>
      <para>Teiid processes results in batches. A batch is
        simply a set of records. The number of rows in a batch is
        determined by the buffer system properties Processor Batch Size
        (within query engine) and Connector Batch Size (created at
        connectors).</para>
      <para>Client applications have no direct knowledge of
        batches or batch sizes, but rather specify fetch size. However
        the first batch, regardless of fetch size is always proactively
        returned to synchronous clients. Subsequent batches are returned
        based on client demand for the data. Pre-fetching is utilized at
        both the client and connector levels.</para>
    </section>
    <section id="buffer_management">
      <title>Buffer Management</title>
      <para> The buffer manager manages memory for all result sets used
        in the query engine. That includes result sets read from a
        connection factory, result sets used temporarily during
        processing, and result sets prepared for a user. Each result set
        is referred to in the buffer manager as a tuple source.</para>
      <para>When retrieving batches from the buffer manager, the
        size of a batch in bytes is estimated and then allocated against
        the max limit.</para>
      <section>
        <title>Memory Management</title>
        <para>The buffer manager has two storage managers - a memory
          manager and a disk manager. The buffer manager maintains the
          state of all the batches, and determines when batches must be
          moved from memory to disk.</para>
      </section>
      <section>
        <title>Disk Management</title>
        <para>Each tuple source has a dedicated file (named by the
          ID) on disk. This file will be created only if at least one
          batch for the tuple source had to be swapped to disk. The file
          is random access. The connector batch size and processor batch
          size properties define how many rows can exist in a batch and
          thus define how granular the batches are when stored into the
          storage manager. Batches are
          always read and written from the storage manager whole.</para>
        <para>The disk storage manager has a cap on the maximum
          number of open files to prevent running out of file handles.
          In cases with heavy buffering, this can cause wait times while
          waiting for a file handle to become available (the default max
          open files is 64).</para>
      </section>
    </section>
    <section>
      <title>Cleanup</title>
      <para>When a tuple source is no longer needed, it is removed
        from the buffer manager. The buffer manager will remove it from
        both the memory storage manager and the disk storage manager.
        The disk storage manager will delete the file. In addition,
        every tuple source is tagged with a "group name" which is
        typically the session ID of the client. When the client's
        session is terminated (by closing the connection, server
        detecting client shutdown, or administrative termination), a
        call is sent to the buffer manager to remove all tuple sources
        for the session.</para>
      <para> In addition, when the query engine is shutdown, the buffer
        manager is shut down, which will remove all state from the disk
        storage manager and cause all files to be closed. When the query engine is stopped, it is safe
        to delete any files in the buffer directory as they are not used
        across query engine restarts and must be due to a system crash
        where buffer files were not cleaned up.</para>
    </section>
  </section>
  <section>
    <title>Query Termination</title>
    <section>
      <title>Canceling Queries</title>
      <para>When a query is canceled, processing will be stopped in
        the query engine and in all connectors involved in the query.
        The semantics of what a connector does in response to a
        cancellation command is dependent on the connector
        implementation. For example, JDBC connectors will asynchronously
        call cancel on the underlying JDBC driver, which may or may not
        actually support this method.</para>
    </section>
    <section>
      <title>User Query Timeouts</title>
      <para>User query timeouts in Teiid can be managed on the client-side or the server-side.
        Timeouts are only relevant for the first record returned.  If the
        first record has not been received by the client within the
        specified timeout period, a 'cancel' command is issued to the
        server for the request and no results are returned to the
        client.  The cancel command is issued asynchronously without the
        client’s intervention.
        </para><para>
        The JDBC API uses the query timeout set by the <code>java.sql.Statement.setQueryTimeout</code> method.
        You may also set a default statement timeout via the connection property "QUERYTIMEOUT".  
        ODBC clients may also utilize QUERYTIMEOUT as an execution property via a set statement to control the default timeout setting.
        See the Client Developers Guide for more on connection/execution properties and set statements.</para>
        <para>Server-side timeouts start when the query is received by the engine.  There may be a skew from the when the
        client issued the query due to network latency or server load that may slow the processing of IO work.
        The timeout will be cancelled if the first result is sent back before the timeout has ended.  
        See the <xref linkend="vdbs"/> section for more on setting the query-timeout VDB property.
        See the Admin Guide for more on modifying the &jboss-beans; file to set default query timeout for all queries.
        </para>
    </section>
  </section>
  <section>
    <title>Processing</title>
    <section>
      <title>Join Algorithms</title>
      <para>Nested loop does the most obvious processing – for
        every row in the outer source, it compares with every row in the
        inner source. Nested loop is only used when the join criteria
        has no equi-join predicates.</para>
      <para>Merge join first sorts the input sources on the joined
        columns.  You can then walk through each side in parallel
        (effectively one pass through each sorted source) and when you
        have a match, emit a row.  In general, merge join is
        on the order of n+m rather than n*m in nested loop.  Merge join is the
        default algorithm.</para>
      <para>Using costing information the engine may also delay the decision
      to perform a full sort merge join.  Based upon the actual row counts involved, the engine 
      can choose to build an index of the smaller side (which will perform similarly to a hash join) 
      or to only partially sort the larger side of the relation.</para>
      <para>Joins involving equi-join predicates are also eligible to be made into <xref linkend="dependent_joins"/>.</para>
    </section>
    <section>
      <title>Sort Based Algorithms</title>
      <para>Sorting is used as the basis of the Sort (ORDER BY),
        Grouping (GROUP BY), and DupRemoval (SELECT DISTINCT)
        operations.  The sort algorithm is a multi-pass merge-sort that
        does not require all of the result set to ever be in memory yet
        uses the maximal amount of memory allowed by the buffer manager.
      </para>
      <para>It consists of two phases.  The first phase ("sort") will
        take an unsorted input stream and produce one or more sorted
        input streams.  Each pass reads as much of the unsorted stream
        as possible, sorts it, and writes it back out as a new stream.
         Since the stream may be more than can fit in memory, this may
        result in many sorted streams.</para>
      <para>The second phase ("merge") consists of a set of phases
        that grab the next batch from as many sorted input streams as
        will fit in memory.  It then repeatedly grabs the next tuple in
        sorted order from each stream and outputs merged sorted batches
        to a new sorted stream.  At completion of the pass, all input
        streams are dropped.  In this way, each pass reduces the number
        of sorted streams.  When only one stream remains, it is the
        final output.</para>
    </section>
  </section>
</chapter>