<?xml version="1.0" encoding="UTF-8"?>
<chapter id="metadata">
   <title>Metadata</title>

  <section id="coremetadata">
    <title>Core metadata</title>
    <para>The metadata for the IronJacamar project is split up into the following areas</para>

    <itemizedlist spacing="compact">
      <listitem>
        <para>Java Connector Architecture metadata</para>
      </listitem>
      <listitem>
        <para>IronJacamar metadata</para>
      </listitem>
      <listitem>
        <para>Resource adapter deployment metadata</para>
      </listitem>
      <listitem>
        <para>DataSource deployment metadata</para>
      </listitem>
    </itemizedlist>

    <para>All metadata parsing is done using the StAX model (<code>javax.xml.stream</code>) for
      optimal performance.</para>

    <para>The implementation of these areas is done within the common module of the project.</para>

    <section id="jcametadata">
      <title>Java Connector Architecture metadata</title>
      <para>The Java Connector Architecture (JCA) metadata implement the metadata defined in the JCA specifications.
        We have metadata representing the following standards:</para>
      
      <itemizedlist spacing="compact">
        <listitem>
          <para>Java Connector Architecture 1.0</para>
        </listitem>
        <listitem>
          <para>Java Connector Architecture 1.5</para>
        </listitem>
        <listitem>
          <para>Java Connector Architecture 1.6</para>
        </listitem>
        <listitem>
          <para>Java Connector Architecture 1.7</para>
        </listitem>
      </itemizedlist>

      <para>An instance of the metadata is bundle with the resource adapter archive as</para>
      <programlisting>
META-INF/ra.xml
      </programlisting>

      <para>The implementation is split into two package hierarchies - the API in</para>
      <programlisting>
org.jboss.jca.common.api.metadata.spec
      </programlisting>
      <para>and the implementation in</para>

      <programlisting>
org.jboss.jca.common.metadata.spec
      </programlisting>
      <para>.</para>

      <para>
        The parser will transform the metadata into a Java Connector Architecture 1.7 based model
        which is used internally in IronJacamar.
      </para>

    </section>

    <section id="ironjacamarmetadata">
      <title>IronJacamar metadata</title>
      <para>The IronJacamar metadata can provide overrides for the values specified in the
        standard Java Connector Architecture metdata. It is also possible to specify
        deployment metadata, which will active an instance of the resource adapter without
        any other deployment plans.</para>

      <para>Supported versions of the metadata:</para>
      <itemizedlist spacing="compact">
        <listitem>
          <para>IronJacamar 1.0</para>
        </listitem>
        <listitem>
          <para>IronJacamar 1.1</para>
        </listitem>
        <listitem>
          <para>IronJacamar 1.2</para>
        </listitem>
      </itemizedlist>

      <para>An instance of the metadata is bundle with the resource adapter archive as</para>
      <programlisting>
META-INF/ironjacamar.xml
      </programlisting>

      <para>The implementation is split into two package hierarchies - the API in</para>
      <programlisting>
org.jboss.jca.common.api.metadata.resourceadapter
      </programlisting>
      <para>and the implementation in</para>

      <programlisting>
org.jboss.jca.common.metadata.ironjacamar
org.jboss.jca.common.metadata.resourceadapter
      </programlisting>
      <para>.</para>

      <para>
        The parser will produce one <code>Activation</code> instance, which
        defines the activation model of the resource adapter.
      </para>

    </section>

    <section id="resourceadapterdeploymentmetadata">
      <title>Resource adapter deployment metadata</title>
      <para>The resource adapter deployment metadata provides a deployment plan for
        the specified resource adapter archive. It is possible to override
        metadata specified as part of the Java Connector Architecture metadata or 
        the IronJacamar metadata.</para>

      <para>Supported versions of the metadata:</para>
      <itemizedlist spacing="compact">
        <listitem>
          <para>Resource adapter deployment 1.0</para>
        </listitem>
        <listitem>
          <para>Resource adapter deployment 1.1</para>
        </listitem>
        <listitem>
          <para>Resource adapter deployment 1.2</para>
        </listitem>
      </itemizedlist>

      <para>The implementation is split into two package hierarchies - the API in</para>
      <programlisting>
org.jboss.jca.common.api.metadata.resourceadapter
      </programlisting>
      <para>and the implementation in</para>

      <programlisting>
org.jboss.jca.common.metadata.resourceadapter
      </programlisting>
      <para>.</para>

      <para>
        The parser will produce a list of <code>Activation</code> instances, which
        defines the activation model of the resource adapter.
      </para>

    </section>

    <section id="datasourcedeploymentmetadata">
      <title>Datasource deployment metadata</title>
   
      <para>The datasource deployment metadata provides a deployment plan for
        datasources. The metadata allows the developer to setup connection parameters, pooling
        settings and security.</para>

      <para>Supported versions of the metadata:</para>
      <itemizedlist spacing="compact">
        <listitem>
          <para>Datasource deployment 1.0</para>
        </listitem>
        <listitem>
          <para>Datasource deployment 1.1</para>
        </listitem>
        <listitem>
          <para>Datasource deployment 1.2</para>
        </listitem>
        <listitem>
          <para>Datasource deployment 1.3</para>
        </listitem>
      </itemizedlist>

      <para>The implementation is split into two package hierarchies - the API in</para>
      <programlisting>
org.jboss.jca.common.api.metadata.ds
      </programlisting>
      <para>and the implementation in</para>

      <programlisting>
org.jboss.jca.common.metadata.ds
      </programlisting>
      <para>.</para>

      <section id="datasourcedeploymentmetadatamapping">
        <title>Datasource mapping</title>
        
        <para>The table below specifies how each attribute/element map to the resource adapter
          or the container.</para>

        <table frame="all">
          <title>Datasource mapping</title>
          <tgroup cols="3" align="left" colsep="1" rowsep="1">
            <colspec colname="c1"/>
            <colspec colname="c2"/>
            <colspec colname="c3"/>
            <thead>
              <row>
                <entry align="left">Tag</entry>
                <entry align="left">Resource Adapter</entry>
                <entry align="left">Container</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>min-pool-size</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>max-pool-size</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>prefill</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>user-name</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>password</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>connection-url</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>driver-class</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>transaction-isolation</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>connection-property</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>url-delimiter</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>url-selector-strategy-class-name</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>new-connection-sql</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>xa-datasource-property</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>xa-datasource-class</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>is-same-rm-override</code></entry>
                <entry></entry>
                <entry><code>TxConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>interleaving</code></entry>
                <entry></entry>
                <entry><code>TxConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>prepared-statement-cache-size</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>share-prepared-statements</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>pad-xid</code></entry>
                <entry></entry>
                <entry><code>TxConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>wrap-xa-resource</code></entry>
                <entry></entry>
                <entry><code>TxConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>no-tx-separate-pools</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>jndi-name</code></entry>
                <entry></entry>
                <entry><code>ConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>pool-name</code></entry>
                <entry></entry>
                <entry>X</entry>
              </row>
              <row>
                <entry><code>enabled</code></entry>
                <entry></entry>
                <entry>X</entry>
              </row>
              <row>
                <entry><code>use-java-context</code></entry>
                <entry></entry>
                <entry>X</entry>
              </row>
              <row>
                <entry><code>valid-connection-checker-class-name</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>check-valid-connection-sql</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>validate-on-match</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>background-validation</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>background-validation-minutes</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>use-fast-fail</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>stale-connection-checker-class-name</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>exception-sorter-class-name</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>blocking-timeout-millis</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>idle-timeout-minutes</code></entry>
                <entry></entry>
                <entry><code>Pool</code></entry>
              </row>
              <row>
                <entry><code>set-tx-query-timeout</code></entry>
                <entry></entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>query-timeout</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>use-try-lock</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>allocation-retry</code></entry>
                <entry></entry>
                <entry><code>ConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>allocation-retry-wait-millis</code></entry>
                <entry></entry>
                <entry><code>ConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>xa-resource-timeout</code></entry>
                <entry></entry>
                <entry><code>TxConnectionManager</code></entry>
              </row>
              <row>
                <entry><code>track-statements</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>prepared-statement-cache-size</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>share-prepared-statements</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
              <row>
                <entry><code>validation-query-timeout</code></entry>
                <entry>X</entry>
                <entry></entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </section>

    </section>

  </section>

  <section id="metadatarepository">
    <title>Metadata Repository</title>
    <para>The metadata repository serves as a central point for all the metadata in the systems.</para>

    <section id="mdrinterface">
      <title>Interface</title>
      <para>The interface of the metadata repository is located in:</para>
      <programlisting>
org.jboss.jca.core.spi.MetaDataRepository
      </programlisting>
      <para>providing methods to query and update the repository.</para>
    </section>

    <section id="mdrbean">
      <title>Bean</title>
      <para>The implementation of the metadata repository can be defined as:</para>
      <programlisting language="xml">
&lt;bean name="MetaDataRepository" 
      interface="org.jboss.jca.core.spi.MetaDataRepository" 
      class="org.jboss.jca.core.mdr.SimpleMetaDataRepository"&gt;
&lt;/bean&gt;
      </programlisting>

      <para>which is a simple implementation of the metadata repository service provider interface (SPI).</para>
    </section>


  </section>
</chapter>
