<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../custom.dtd">
%CustomDTD;
]>
<chapter id="modeshape_connection">
  <title>Connecting to ModeShape Repository</title>

  <para>The ModeShape JDBC API provides Java Database Connectivity (JDBC)
  access to a ModeShape JCR Repository deployed in a JBoss AS Server. Java
  client applications connecting to a ModeShape JCR Respository will need to
  use Java 1.6 JDK. Previous versions of Java are not supported. Additionally,
  the ModeShape JDBC API is not jdbc complient, see <ulink url="???"><link
  linkend="appendix-unsupported-jdbc.xml">Appendix</link></ulink>.</para>

  <para></para>

  <para>Before you can connect using the ModeShape JDBC API, please do
  following tasks first.</para>

  <orderedlist>
    <listitem>
      <para>Install the ModeShape JCR Repository. One option for installation
      is to use the JBoss AS distribution kit.</para>
    </listitem>

    <listitem>
      <para>Start the JBoss AS server, if it is not already running.</para>
    </listitem>
  </orderedlist>

  <para>Now that you have the ModeShape JCR Repository deployed and the server
  running, client applications running in the server can connect to the
  ModeShape JCR Repository and issue SQL queries. If you are new to JDBC, see
  Java's documentation about <ulink
  url="http://java.sun.com/docs/books/tutorial/jdbc/index.html">JDBC</ulink>.</para>

  <para></para>

  <section id="driver_connection">
    <title>Driver Connection</title>

    <para>Using <code>org.modeshape.jdbc.JcrDriver</code> as the driver
    class.</para>

    <para>The driver accepts several URL formats based on how the repository
    is configured:</para>

    <para><itemizedlist>
        <listitem>
          <para>configured for <emphasis>local</emphasis> access using
          JNDI</para>

          <para>jdbc:jcr:jndi:{jndiName}</para>

          <para>or</para>

          <para>jdbc:jcr:jndi:{jndiName}?[prop-name=prop-value&amp;]*</para>

          <para></para>

          <para>where</para>

          <para><emphasis>{jndiName}</emphasis> is the JNDI name where the
          <interfacename>Repository</interfacename> or
          <interfacename>Repositories</interfacename> instance can be
          found</para>

          <para><emphasis>[prop-name=prop-value]</emphasis> - additionally you
          can supply any number of name value pairs separated by ampersand
          [&amp;]. All supported URL properties are defined in the <link
          linkend="connection_properties">connection properties
          section</link>. Any use of URL encoding ('%' followed by a two-digit
          hexadecimal value) will be decoded before being used.</para>

          <para><example>
              <title>Local <interfacename>Repository</interfacename> instance
              located at <code>jcr/local </code></title>

              <para>jdbc:jcr:jndi:jcr/local?repositoryName=repository&amp;user=jsmith&amp;amp;password=secret</para>

              <para></para>
            </example></para>
        </listitem>
      </itemizedlist></para>

    <itemizedlist>
      <listitem>
        <para>configured for <emphasis>remote</emphasis> access using REST
        interface</para>

        <para>jdbc:jcr:http://{host}:{port}/{context
        root}/{workspace}/?[prop-name=prop-value&amp;]*</para>

        <para></para>

        <para>where</para>

        <para><emphasis>{host}</emphasis> is the host name where the
        <interfacename>Repository</interfacename> or
        <interfacename>Repositories</interfacename> instance can be
        found</para>

        <para><emphasis>{port}</emphasis> is the port to access the
        <interfacename>Repository</interfacename> or
        <interfacename>Repositories</interfacename> instance on the specified
        <code>host</code></para>

        <para><emphasis>{context root}</emphasis> is the location where the
        rest service is deployed. The default context, when using the JBoss AS
        distribution kit, is <code>modeshape-rest</code>.</para>

        <para><emphasis>{workspace}</emphasis> is the workspace to use. The
        default workspace in the JBoss AS distribution kit is
        <emphasis>default</emphasis>.</para>

        <para><emphasis>[prop-name=prop-value]</emphasis> - additionally you
        can supply any number of name value pairs separated by ampersand
        [&amp;]. All supported URL properties are defined in the <link
        linkend="connection_properties">connection properties section</link>.
        Any use of URL encoding ('%' followed by a two-digit hexadecimal
        value) will be decoded before being used.</para>

        <para><example>
            <title>Remote Repository instance</title>

            <para>jdbc:jcr:http://localhost:8080/modeshape-rest/default?repositoryName=repository&amp;user=jsmith&amp;amp;password=secret</para>
          </example></para>
      </listitem>
    </itemizedlist>

    <para></para>

    <section id="connection_properties">
      <title>URL Connection Properties</title>

      <para>The following table shows all the supported connection properties
      that can used with ModeShap JDBC Driver URL connection string.</para>

      <table frame="all">
        <title>Connection Properties</title>

        <tgroup align="left" cols="3" colsep="1" rowsep="1">
          <colspec colname="c1" colwidth=".75*" />

          <colspec colname="c2" colwidth=".5*" />

          <colspec colname="c3" colwidth="2*" />

          <thead>
            <row>
              <entry>Property Name</entry>

              <entry>Type</entry>

              <entry>Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry><code>repositoryName</code></entry>

              <entry><code>String</code></entry>

              <entry>Name of the client application; allows the administrator
              to identify the connections</entry>
            </row>

            <row>
              <entry><code>worksspace</code></entry>

              <entry><code>int</code></entry>

              <entry>Size of the resultset; The default size if 500. &lt;=0
              indicates that the default should be used.</entry>
            </row>

            <row>
              <entry><code>user</code></entry>

              <entry><code>String</code></entry>

              <entry>User name</entry>
            </row>

            <row>
              <entry><code>Password</code></entry>

              <entry><code>String</code></entry>

              <entry>Credential for user</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
  </section>

  <section id="ds_in_jbossas">
    <title>JBoss AS Data Source</title>

    <para>ModeShape can be configured as a JDBC data source in the JBoss
    Application Server to be accessed from JNDI or injected into your JEE
    applications. Deploying ModeShape as data source in JBoss AS is exactly
    same as deploying any other RDBMS resources like Oracle or DB2.</para>

    <para>Defining as data source is not limited to JBoss AS, you can also
    deploy as data source in Glassfish, Tomcat, Websphere, Weblogic etc
    servers, however their configuration files are different than JBoss AS.
    Consult the respective documentation of the environment in which you are
    deploying.</para>

    <para>The data source will then be accessable through the JNDI name
    specified in the -ds.xml file.</para>

    <para>The following is the modeshape-jdbc-ds.xml datasource file deployed
    when the JBoss AS distribution kit is deployed.</para>

    <example>
      <title>Sample DataSource in the JBoss AS using the ModeShape Driver
      class <code>org.modeshape.jdbc.JcrDriver</code></title>

      <programlisting>&lt;datasources&gt;
  &lt;local-tx-datasource&gt;
    &lt;jndi-name&gt;ModeShapeDS&lt;/jndi-name&gt;
    &lt;connection-url&gt;jdbc:jcr:jndi:jcr/local?repositoryName=repository&lt;/connection-url&gt;

    &lt;driver-class&gt;org.modeshape.jdbc.JcrDriver&lt;/driver-class&gt;
    &lt;user&gt;admin&lt;/user&gt;
    &lt;password&gt;admin&lt;/password&gt;

      &lt;metadata&gt;
         &lt;type-mapping&gt;jcrrepo&lt;/type-mapping&gt;
      &lt;/metadata&gt;
  &lt;/local-tx-datasource&gt;

&lt;/datasources&gt;</programlisting>
    </example>
  </section>
</chapter>
