[Springframework-cvs] spring/docs/reference/src taskexecutor.xml,NONE,1.1 index.xml,1.70,1.71

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/springframework/spring/docs/reference/src
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30172/docs/reference/src

Modified Files:
	index.xml 
Added Files:
	taskexecutor.xml 
Log Message:
Added a TaskExecutor section and updated the TOC to include it.

Index: index.xml
===================================================================
RCS file: /cvsroot/springframework/spring/docs/reference/src/index.xml,v
retrieving revision 1.70
retrieving revision 1.71
diff -C2 -d -r1.70 -r1.71
*** index.xml	19 Apr 2006 11:50:20 -0000	1.70
--- index.xml	20 Apr 2006 01:45:34 -0000	1.71
***************
*** 26,29 ****
--- 26,30 ----
  <!ENTITY mail				SYSTEM "mail.xml">
  <!ENTITY scheduling			SYSTEM "scheduling.xml">
+ <!ENTITY taskexecutor		SYSTEM "taskexecutor.xml">
  <!ENTITY testing			SYSTEM "testing.xml">
  <!ENTITY scripting			SYSTEM "scripting.xml">
***************
*** 35,39 ****
  ]>
  <book>
!     <bookinfo>
  		<title>The Spring Framework - Reference Documentation</title>
  		<releaseinfo>Version 2.0 M4</releaseinfo>
--- 36,40 ----
  ]>
  <book>
! 	<bookinfo>
  		<title>The Spring Framework - Reference Documentation</title>
  		<releaseinfo>Version 2.0 M4</releaseinfo>
***************
*** 91,103 ****
  				<surname>Evans</surname>
  			</author>
  		</authorgroup>
  		<legalnotice>
! 			Copies of this document may be made for your own use and for distribution to others, provided that
! 			you do not charge any fee for such copies and further provided that each copy contains this
! 			Copyright Notice, whether distributed in print or electronically.
  		</legalnotice>
  	</bookinfo>
  	<!-- front matter -->
!     <toc />
  	&overview;
  	&background;
--- 92,110 ----
  				<surname>Evans</surname>
  			</author>
+ 			<author>
+ 				<firstname>Ben</firstname>
+ 				<surname>Hale</surname>
+ 			</author>
  		</authorgroup>
  		<legalnotice>
! 			Copies of this document may be made for your own use and for
! 			distribution to others, provided that you do not charge any
! 			fee for such copies and further provided that each copy
! 			contains this Copyright Notice, whether distributed in print
! 			or electronically.
  		</legalnotice>
  	</bookinfo>
  	<!-- front matter -->
! 	<toc />
  	&overview;
  	&background;
***************
*** 107,128 ****
  		<partintro>
  			<para>
! 				This initial part of the reference documentation covers all of those
! 				technologies that are absolutely integral to the Spring Framework.
  			</para>
  			<para>
! 				Foremost amongst these is the Spring Framework's Inversion of Control (IoC)
! 				container.
  			</para>
  			<para>
! 				A thorough treatment of the Spring Framework's IoC container is closely
! 				followed by comprehensive coverage of Spring's Aspect-Oriented Programming (AOP)
! 				technologies. The Spring Framework has its own AOP framework, which is
! 				conceptually easy to understand, and which (successfully) addresses the 80%
! 				sweet spot of AOP requirements in Java enterprise programming.
  			</para>
  			<para>
! 				Coverage of Spring's integration with AspectJ (currently the richest - in
! 				terms of features - and certainly most mature AOP implementation in the
! 				Java enterprise space) is also provided.
  			</para>
  			<itemizedlist>
--- 114,139 ----
  		<partintro>
  			<para>
! 				This initial part of the reference documentation covers
! 				all of those technologies that are absolutely integral
! 				to the Spring Framework.
  			</para>
  			<para>
! 				Foremost amongst these is the Spring Framework's
! 				Inversion of Control (IoC) container.
  			</para>
  			<para>
! 				A thorough treatment of the Spring Framework's IoC
! 				container is closely followed by comprehensive coverage
! 				of Spring's Aspect-Oriented Programming (AOP)
! 				technologies. The Spring Framework has its own AOP
! 				framework, which is conceptually easy to understand, and
! 				which (successfully) addresses the 80% sweet spot of AOP
! 				requirements in Java enterprise programming.
  			</para>
  			<para>
! 				Coverage of Spring's integration with AspectJ (currently
! 				the richest - in terms of features - and certainly most
! 				mature AOP implementation in the Java enterprise space)
! 				is also provided.
  			</para>
  			<itemizedlist>
***************
*** 154,164 ****
  		<partintro>
  			<para>
! 				This part of the reference documentation is concerned with the middle tier,
! 				and specifically the data access responsibilities of said tier.
  			</para>
  			<para>
! 				Spring's comprehensive transaction management support is covered in some detail,
! 				followed by thorough coverage of the various middle tier data access frameworks
! 				and technologies that the Spring Framework integrates with.
  			</para>
  			<itemizedlist>
--- 165,177 ----
  		<partintro>
  			<para>
! 				This part of the reference documentation is concerned
! 				with the middle tier, and specifically the data access
! 				responsibilities of said tier.
  			</para>
  			<para>
! 				Spring's comprehensive transaction management support is
! 				covered in some detail, followed by thorough coverage of
! 				the various middle tier data access frameworks and
! 				technologies that the Spring Framework integrates with.
  			</para>
  			<itemizedlist>
***************
*** 181,204 ****
  		&jdbc;
  		&orm;
! 	</part>	
  	<part>
  		<title>The Web</title>
  		<partintro>
  			<para>
! 				This part of the reference documentation covers the Spring Framework's
! 				support for the presentation tier (and specifically web-based presentation
! 				tiers).
  			</para>
  			<para>
! 				The Spring Framework's own web framework, <link linkend="mvc">Spring MVC</link>,
! 				is coevered in the first couple of chapters. A number of the remaining chapters in
! 				this part of the reference documentation are concerned with the Spring Framework's
! 				integration with other web technologies, including as other web frameworks such as
! 				<link linkend="struts">Struts</link> and <link linkend="jsf">JSF</link> (to name
! 				but a few).
  			</para>
  			<para>
  				This section concludes with coverage of Spring's
! 				<link linkend="portlet">portlet framework</link>.
  			</para>
  			<itemizedlist>
--- 194,223 ----
  		&jdbc;
  		&orm;
! 	</part>
  	<part>
  		<title>The Web</title>
  		<partintro>
  			<para>
! 				This part of the reference documentation covers the
! 				Spring Framework's support for the presentation tier
! 				(and specifically web-based presentation tiers).
  			</para>
  			<para>
! 				The Spring Framework's own web framework,
! 				<link linkend="mvc">Spring MVC</link>
! 				, is coevered in the first couple of chapters. A number
! 				of the remaining chapters in this part of the reference
! 				documentation are concerned with the Spring Framework's
! 				integration with other web technologies, including as
! 				other web frameworks such as
! 				<link linkend="struts">Struts</link>
! 				and
! 				<link linkend="jsf">JSF</link>
! 				(to name but a few).
  			</para>
  			<para>
  				This section concludes with coverage of Spring's
! 				<link linkend="portlet">portlet framework</link>
! 				.
  			</para>
  			<itemizedlist>
***************
*** 226,231 ****
  		<partintro>
  			<para>
! 				This final part of the reference documentation covers the Spring Framework's
! 				integration with a number of J2EE (and related) technologies.
  			</para>
  			<itemizedlist>
--- 245,251 ----
  		<partintro>
  			<para>
! 				This final part of the reference documentation covers
! 				the Spring Framework's integration with a number of J2EE
! 				(and related) technologies.
  			</para>
  			<itemizedlist>
***************
*** 252,255 ****
--- 272,278 ----
  				</listitem>
  				<listitem>
+ 					<xref linkend="taskexecutor" />
+ 				</listitem>
+ 				<listitem>
  					<xref linkend="dynamic-language" />
  				</listitem>
***************
*** 269,272 ****
--- 292,296 ----
  		&mail;
  		&scheduling;
+ 		&taskexecutor;
  		&dynamic-languages;
  		&testing;

--- NEW FILE: taskexecutor.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="taskexecutor">
  <title><classname>TaskExecutor</classname></title>

  <section>
    <title>Introduction</title>

    <para>Spring 2.0 introduces a new abstraction for dealing with Executors.
    Executors are the Java 5 name for the concept of thread pools. The odd
    naming is due to the fact that there is no guarentee that the underlying
    implementation of is actually a pool. In fact in many cases the executor
    is single threaded. Spring's abstraction helps bring thread pooling to
    Java 1.3 and 1.4 environments as well as hiding implementations details
    between 1.3, 1.4, 5, and JEE environments.</para>
  </section>

  <section>
    <title>The <classname>TaskExecutor</classname> Interface</title>

    <para>Spring's <classname>TaskExecutor</classname> interface is identical
    to the <classname>java.util.concurrent.Executor</classname> interface. In
    fact it's primary reason for existence is to abstract away the need for
    Java 5 when using thread pools. The interface has a single method
    <classname>execute(Runnable task)</classname> which accepts a task for
    execution based on the semantics and configuration of the thread
    pool.</para>
  </section>

  <section>
    <title>Where to use a <classname>TaskExecutor</classname></title>

    <para>The <classname>TaskExecutor</classname> was originally created to
    give other Spring components an abstraction for thread pooling where
    needed. Components such as the
    <classname>ApplicationEventMulticaster</classname>, JMS's
    <classname>AbstractMessageListenerContainer</classname>, and Quartz
    integration use the <classname>TaskExecutor</classname> abstraction to
    pool threads. However, if your beans need thread pooling behavior, it is
    possible to reuse this abstraction for your own needs.</para>
  </section>

  <section>
    <title>Types of <classname>TaskExecutor</classname>s</title>

    <para>There are a number of pre-built implementations of
    <classname>TaskExecutor</classname> included with the Spring distribution.
    In all likelihood, you shouldn't ever need to implement your own.</para>

    <section>
      <title><classname>SimpleAsyncTaskExecutor</classname></title>

      <para>This implementation does not reuse any threads, rather it starts
      up a new thread for each invocation. However, it does support a
      concurrency limit which will block any invocations that are over the
      limit until a slot has been freed up. If you're looking for true
      pooling, keep looking further down the page.</para>
    </section>

    <section id="syncTaskExecutor">
      <title><classname>SyncTaskExecutor</classname></title>

      <para>This implementation doesn't even execution invocations
      asynchronously. Instead each invocation takes place in the calling
      thread. It is primarily used in situations where mutlithreading isn't
      necessary such as simple test cases.</para>
    </section>

    <section id="concurrentTaskExecutor">
      <title><classname>ConcurrentTaskExecutor</classname></title>

      <para>This implementation is a wrapper for a Java 5
      <classname>java.util.concurrent.Executor</classname>. There is an
      alternative, <classname>ThreadPoolTaskExecutor</classname>, that exposes
      the <classname>Executor</classname> configuration parameters as bean
      properties. It is rare to use the
      <classname>ConcurrentTaskExecutor</classname> but if the
      <classname>ThreadPoolTaskExecutor</classname> isn't robust enough for
      your needs, the <classname>ConcurrentTaskExecutor</classname> is
      there.</para>

      <itemizedlist>
        <listitem>
          <para><xref linkend="threadPoolTaskExecutor" /></para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title
      id="simpleThreadPoolTaskExecutor"><classname>SimpleThreadPoolTaskExecutor</classname></title>

      <para>This implementation is actually a subclass of Quartz's
      <classname>SimpleThreadPool</classname> which listens to Spring's
      lifecycle callbacks. This is typically used when you have a threadpool
      that may need to be shared by both Quartz and non-Quartz
      components.</para>
    </section>

    <section id="threadPoolTaskExecutor">
      <title><classname>ThreadPoolTaskExecutor</classname></title>

      <sidebar>
        <para>It is not possible to use any backport or alternate version of
        the <classname>java.util.concurrent</classname> package with this
        implementation. Both Doug Lea's and Dawid Kurzyniec's implementations
        use different package structures which will prevent them from working
        correctly.</para>
      </sidebar>

      <para>This implementation can only be used in a Java 5 environment but
      is the most typically used there. It exposes bean properties for
      configuring a
      <classname>java.util.concurrent.ThreadPoolExecutor</classname> and wraps
      it in a <classname>TaskExecutor</classname>. If you need something
      advanced such as a <classname>ScheduledThreadPoolExecutor</classname>,
      it is recommended that you use a
      <classname>ConcurrentTaskExecutor</classname> instead.</para>

      <itemizedlist>
        <listitem>
          <para><xref linkend="concurrentTaskExecutor" /></para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title><classname>TimeTaskExecutor</classname></title>

      <para>This implementation uses a single <classname>TimerTask</classname>
      as it's backing implementation. It's different from the
      <classname>SyncTaskExecutor</classname> in that the method invocations
      are executed in a separate thread, although they are synchronous in that
      thread.</para>

      <itemizedlist>
        <listitem>
          <para><xref linkend="syncTaskExecutor" /></para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title><classname>WorkManagerTaskExecutor</classname></title>

      <sidebar>
        <para>CommonJ is a set of specifications jointly developed between BEA
        and IBM. These specifications are not JEE standards, but are standard
        across BEA's and IBM's Application Server implementations.</para>
      </sidebar>

      <para>This implementation uses the CommonJ WorkManager as its backing
      implementation and is the central convience class for setting up a
      CommonJ WorkManager reference in a Spring context. Similarly to the
      <classname>SimpleThreadPoolTaskExecutor</classname>, this class
      implements the WorkManager interface and therefore can be used directly
      as a WorkManager as well.</para>

      <itemizedlist>
        <listitem>
          <para><xref linkend="simpleThreadPoolTaskExecutor" /></para>
        </listitem>
      </itemizedlist>
    </section>
  </section>
</chapter>