<document>
<header>
<product>resin</product>
<type>tutorial</type>
<title>Connector</title>

<description>
<p>This is an advanced Connector tutorial for those interested in implementing
Connector drivers or who just want to understand the inner workings.
Connectors are a generalization of the JDBC DataSource, supporting
pooling and transactions for any Connector following the interface.</p>
</description>
    <tutorial-startpage>demo</tutorial-startpage>

</header>
<body>

<summary/>

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/web.xml"/>
    <td>Configures the Connector
<tr><td><viewfile-link file="WEB-INF/classes/example/ConnectionImpl.java"/>
    <td>User interface for the connection
<tr><td><viewfile-link file="WEB-INF/classes/example/ConnectionFactoryImpl.java"/>
    <td>User interface for the connection factory
<tr><td><viewfile-link file="WEB-INF/classes/example/ManagedConnectionImpl.java"/>
    <td>Driver (SPI) interface for the connection
<tr><td><viewfile-link file="WEB-INF/classes/example/ManagedConnectionFactoryImpl.java"/>
    <td>Driver (SPI) interface for the connection factory
<tr><td><viewfile-link file="WEB-INF/classes/example/TestServlet.java"/>
    <td>The demo servlet for the tutorial
</deftable>
</section>

<section title="Overview">

<glossary title="Connector">The driver's system of connections and
factories.</glossary>

<p>The connector architecture generalizes the pooling and transaction
capabilities of the JDBC DataSource, allowing other connections and
even user code to take advantage of pooling and transactions.  From a
user's perspective, the system is simple: a factory creates connection
objects.  The driver implementor's view is a bit more complex, of
course, but still only requires two extra classes: the server's view
of the factory and the server's view of the connection.</p>

<p>Understanding the connector system starts from the main class,
the user connection, the user's view of the connection.</p>

<deftable>
<tr><td>user connection</td><td>User's view of the connection</td>
<tr><td>user connection factory</td><td>User's view of the connection factory</td>
<tr><td>managed connection</td><td>Resin's view of the connection</td>
<tr><td>managed connection factory</td><td>Resin's view of the connection factory</td>
</deftable>

<section title="User Connection">

<p>The user connection is the main application interface.  The
connector can use any API for the user connection.
Typically, connections will at least have a <code>close()</code>
method which will return the connection to the pool.</p>

<p>The user's connection, <code>ConnectionImpl</code> in the tutorial,
has a similar function to the JDBC <code>Connection</code> class.
It's the main object that applications will use.  Typically, it will
be used in a single threaded fashion and will be closed in a finally
block to return the connection to the pool.</p>

<p>When the connection is returned to the pool, the user connection,
<code>ConnectionImpl</code> is not reused.</p>

<p>The user connection and the user connection factory are the only
interfaces user code will see.  The user connection factory, like
JDBC's <code>DataSource</code> is responsible for
creating user connections.</p>

</section>

<section title="User Connection Factory">

<p>The user connection factory creates user connections.
Users will generally get the user connection factory from JNDI during
initialization and use it for all requests.  Each request will get a
new user connection from the user connection factory.  In the example,
the user connection factory is <code>ConnectionFactoryImpl</code>.</p>

<p>Like the user connection, the user connection factory may have any
API appropriate to the connector.  For example, a JDBC connector will
user the standard <code>DataSource</code>.</p>

<p>The user connection factory must be thread-safe, since multiple
requests may need new connections simultaneously.</p>

<p>When the user requests a new user connection from the user
connection factory, the user factory calls Resin's
<code>ConnectionManager</code> interface to request a new connection.
To create the new connection, Resin asks the driver's
controlling class, the managed connection factory, for a new
managed connection.</p>

</section>

<section title="Managed Connection">

<p>Each user connection uses an underlying managed connection to talk
to the resource.  When the user is done with the connection, the
<code>close()</code> method puts the managed connection back into
Resin's pool for later reuse.  Once closed, the user connection is
discarded.</p>

<p>The driver can choose whether most of the user connection logic is
in the user connection or the managed connection.  If most of the
logic is in the user connection, the managed connection will typically
be responsible connection resources, like a socket, but the user
connection may be responsible for the protocol.  Another architecture
will have the user connection act as a facade to the underlying code
in the managed connection.  The architecture will depend on the
driver's needs.</p>

</section>

<section title="Managed Connection Factory">

<p>Resin's main interface to the connector is the managed
connection factory.  The managed connection factory is configured in
the web.xml using bean-style initialization.  Resin calls on
the managed connection factory for both the user connection factory
and to allocate new managed connections.</p>

</section>

</section>

<section title="Using the Connector">

<p>Using the JCA connector follows the same pattern as for JDBC.
The servlet looks up the <code>ConnectionFactory</code> in
the servlet's <code>init()</code> method and uses the connection in a
try .. finally block.</p>

<p>As with JDBC, the user must put the <code>close()</code> in a
finally block or the connection will leak.</p>

<example file="WEB-INF/classes/example/TestServlet.java">
void init()
{
  ...
    ic = new InitialConnection();
    _factory =
      (ConnectionFactoryImpl) ic.lookup("java:comp/env/factory");
}

void service(HttpServletRequest request,
             HttpServletResponse response)
  throws IOException, ServletException
{
  ConnectionImpl conn = null;

  try {
    conn = _factory.getConnection();

    ...
  } finally {
    if (conn != null)
      conn.close();
  }
}
</example>

<p>The demo servlet just prints the <code>ConnectionFactory</code>
and the <code>ConnectionImpl</code>.  As the following result show,
each connection request uses a new <code>ConnectionImpl</code>, but
keeps using the same <code>ManagedConnectionImpl</code>.</p>

<results>
Factory: ConnectionFactoryImpl[ManagedConnectionFactoryImpl[example]]
Connection: ConnectionImpl[example-12-conn,ManagedConnectionImpl[example-0]]
</results>

</section>

<section title="Configuration">

<p>As usual, Resin uses bean-style configuration for the
connector.  The example <code>ManagedConnectionFactoryImpl</code> has
a <code>setName</code> configuration method.  The &lt;init> tag in the
configuration file sets that value.  If needed, you can use JSP EL
expressions to assign the name value.</p>

<p>The <var/name/> attribute is the JNDI name for
the user connection factor, in this case
"java:comp/env/factory".  The &lt;type> tag is the class name of
the factory and the &lt;init> section initializes the factory.</p>

<example file="WEB-INF/web.xml">
&lt;resource name="factory">
  &lt;type>example.ManagedConnectionFactoryImpl&lt;/type>
  &lt;init>
    &lt;name>example&lt;/name>
  &lt;/init>
&lt;/resource>
</example>

</section>

<section title="Control Flow">

<p>Since looking at the implementation methods can be a bit confusing,
it's best to approach them as a set of method call chains.</p>

<section title="Installing the UserConnectionFactory">

<p>During configuration, Resin needs to get the
<code>UserConnectionFactory</code> from the
<code>ManagedConnectionFactory</code> and store it in JNDI.</p>

<ol>
<li>Resin instantiates and configures the
<code>ManagedConnectionFactory</code> from the configuration file.
<li>Resin calls
<code>ManagedConnectionFactory.createConnectionFactory</code> for the
user connection factory.  It passes along a
<code>ConnectionManager</code> which points back to Resin.
<li>Resin stores the user connection factory in JNDI.
</ol>

<p>The <code>ConnectionManager</code> will be important in the next
step to get a connection.</p>

</section>

<section title="Getting a new Connection">

<p>From the user's perspective, the main point of the connector is
getting a connection.  The user asks the user connection factory for
the request.</p>

<ol>
<li>The user calls the user connection factory's
<code>getConnection</code> method.  This method would be specific to
the user connection factory's API.
<li>The user connection factory calls Resin's
<code>ConnectionManager.allocateConnection</code> method to ask for a
new connection.
<li>Resin checks the pool but it's empty, so needs to get a new
connection.
<li>Resin calls the managed connection factory's
<code>createManagedConnection</code> method to get a new managed
connection.
<li>Resin registers itself as a listener for
the <code>ManagedConnection</code>, so it will know when the
connections close or have a fatal error.
<li>Resin calls the managed connection's <code>getConnection</code>
method to get a new user connection.
<li>Resin finally returns the user connection to the user.
</ol>

</section>

<section title="Returning a Connection to the pool">

<p>After the user is done with the connection, the finally block will
close the connection.  The connector takes the following steps to put
the connection into the pool:</p>

<ol>
<li>The user calls the connection's <code>close</code> method.  This
method is specific to each API, but <code>close</code> is a good
choice.
<li>The connection notifies the listeners in the managed connection
that the connection has closed.  In the example,
<code>ConnectionImpl</code> calls the
<code>ManagedConnectionImpl.close()</code> method.
<li>Since Resin is registered as a listener, the managed connection
calls Resin's <code>connectionClosed</code> method.
<li>Resin returns the managed connection to the pool and marks it
idle, ready for the next request.
</ol>

</section>

<section title="Getting a Connection from the pool">

<p>From the user's perspective this looks exactly like getting a new
connection does.  There's a bit more work for the managed connection
factory, though.</p>


<ol>
<li>The user calls the user connection factory's
<code>getConnection</code> method.  This method would be specific to
the user connection factory's API.
<li>The user connection factory calls Resin's
<code>ConnectionManager.allocateConnection</code> method to ask for a
new connection.
<li>Resin checks the pool and there are idle connections.  But Resin
needs to ask the managed connection factory if any can be used for
this request.
<li>Resin calls the managed connection factory's
<code>matchManagedConnections</code> with the idle managed connection
pool to see if any can be used.
<li>If there's a valid managed connection in the pool, the managed
connection factory return it.
<li>Resin then takes the managed connection from the pool.
<li>Resin calls the managed connection's <code>getConnection</code>
method to get a new user connection.
<li>Resin returns the user connection to the user.
</ol>

</section>
</section>

<section title="Compatibility">

<p>Since this example uses the JCA API, the code is compatible across
all application servers.  The configuration, of course, will be
different for each.  Many other applications will require generation
of a .rar file and some additional XML files, although those should be
relatively straightforward.</p>

</section>

</body>
</document>
