<document>
<header>
<product>resin</product>
<type>tutorial</type>
<title>Resource Thread Management</title>

<description>
<p>Resources using threads will want to use JCA's work management API.
The work management API lets Resin manage threads for the
resource rather than forcing the resource to manage its own threads.
Since Resin is in a better position to manager threads, using the
Work API is not only a convenience, but is a cleaner and more reliable
implementation.</p>
</description>
 <tutorial-startpage>index.jsp</tutorial-startpage>

</header>
<body>

<summary/>

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/web.xml"/>
    <td>Configures the WorkResource
<tr><td><viewfile-link file="WEB-INF/classes/example/WorkResource.java"/>
    <td>The resource implementation launches the Work task and provides common state.
<tr><td><viewfile-link file="WEB-INF/classes/example/WorkTask.java"/>
    <td>The work task sleeps and counts.
<tr><td><viewfile-link file="index.jsp"/>
    <td>The starting page for the tutorial
</deftable>
</section>

<section title="The Work task">

<p>A <code>Work</code> task implements the
<code>javax.resource.work.Work</code> interface.  Like the familiar
<code>Runnable</code> interface, <code>Work</code> has a
public <code>run()</code> method as the main thread method.
<code>Work</code> adds a <code>release()</code> method which allows
Resin to notify the task when the resource should shut down.</p>

<p>The example task increments a counter and sleeps.
The <code>run</code> method has the main loop.</p>

<p>The only complexity in the task implements the <code>release()</code>
capability.  The <code>_isActive</code> flag indicates whether the
server is still alive.  It is important that <code>_isActive</code> is
set before the work task is submitted to avoid timing issues.  In
other words, it would be a mistake to set <code>_isActive = true</code>
in the <code>run()</code> method since Resin could call
<code>release()</code> before the run thread started.</p>

<p>The task uses <code>wait(long)</code> for sleeping.
The <code>release()</code> will wake the task to let it shut down.
In a work task, the main blocking calls should have timeouts or
will be interruptable.  A real application like a chat server might be
reading a socket or waiting for a new connection.  Those calls need
timeouts so the task can shut down the service at the appropriate time.</p>

<example title="WorkTask.java">
import javax.resource.Work;

public class WorkTask implements Work {
  private volatile boolean _isActive = true;
  private int _count;

  int getCount()
  {
    return _count;
  }

  public void run()
  {
    while (_isActive) {
      _count++;

      try {
        synchronized (this) {
          wait(10000);
        }
      } catch (Throwable e) {
      }
    }
  }

  public void release()
  {
    _isActive = false;

    try {
      synchronized (this) {
        notifyAll();
      }
    } catch (Throwable e) {
    }
  }
</example>

</section>

<section title="The Resource">

<p>The <code>WorkResource</code> in this example is simple since it only
needs to launch the work task.  As with the previous examples, the
resource extends <code>com.caucho.jca.AbstractResourceAdapter</code>
to simplify the example.</p>

<example title="WorkResource.java">

import com.caucho.jca.AbstractResourceAdapter;

public class WorkResource extends AbstractResourceAdapter {
  public void start(BootstrapContext ctx)
    throws ResourceAdapterInternalException
  {
    WorkTask work = new WorkTask();

    WorkManager workManager = ctx.getWorkManager();
    
    try {
      // Submits the work, but does not wait for the result.
      // In other words, it spawns a new thread
      workManager.startWork(work);
    } catch (WorkException e) {
      throw new ResourceAdapterInternalException(e);
    }
  }

  public String toString()
  {
    return "WorkResource[" + _workTask.getCount() + "]";
  }
}
</example>

</section>

</body>
</document>
