Home » quartz-1.6.0 » org » quartz » plugins » [javadoc | source]

    1   /* 
    2    * Copyright 2004-2006 OpenSymphony 
    3    * 
    4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not 
    5    * use this file except in compliance with the License. You may obtain a copy 
    6    * of the License at 
    7    * 
    8    *   http://www.apache.org/licenses/LICENSE-2.0 
    9    *   
   10    * Unless required by applicable law or agreed to in writing, software 
   11    * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 
   12    * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 
   13    * License for the specific language governing permissions and limitations 
   14    * under the License.
   15    */
   16   package org.quartz.plugins;
   17   
   18   import javax.transaction.Status;
   19   import javax.transaction.UserTransaction;
   20   
   21   import org.apache.commons.logging.Log;
   22   import org.apache.commons.logging.LogFactory;
   23   import org.quartz.Scheduler;
   24   import org.quartz.SchedulerException;
   25   import org.quartz.ee.jta.UserTransactionHelper;
   26   import org.quartz.spi.SchedulerPlugin;
   27   
   28   /**
   29    * Base class for plugins that wish to support having their start and
   30    * shutdown methods run within a <code>UserTransaction</code>.  This is 
   31    * often necessary if using the JobStoreCMT and the plugin interacts with
   32    * jobs/triggers. 
   33    * 
   34    * <p>
   35    * The subclass should implement start(UserTransaction) and 
   36    * shutdown(UserTransaction).  The <code>UserTransaction</code> will be 
   37    * non-null if property <em>wrapInUserTransaction</em> is set to true.
   38    * </p>
   39    * <p>
   40    * For convenience, this base class also provides an initialize() implementation
   41    * which saves the scheduler and plugin name, as well as getLog() for logging.
   42    * </p>
   43    */
   44   public abstract class SchedulerPluginWithUserTransactionSupport implements
   45       SchedulerPlugin {
   46   
   47       private String name;
   48       private Scheduler scheduler;
   49       private final Log log = LogFactory.getLog(getClass());
   50   
   51       // Properties
   52       
   53       private boolean wrapInUserTransaction = false;
   54   
   55       /**
   56        * <p>
   57        * Called when the associated <code>Scheduler</code> is started, in order
   58        * to let the plug-in know it can now make calls into the scheduler if it
   59        * needs to.
   60        * </p>
   61        * 
   62        * <p>
   63        * If UserTransaction is not null, the plugin can call setRollbackOnly()
   64        * on it to signal that the wrapped transaction should rollback.  
   65        * </p>
   66        * 
   67        * @param userTransaction The UserTranaction object used to provide a 
   68        * transaction around the start() operation.  It will be null if 
   69        * <em>wrapInUserTransaction</em> is false or if the transaction failed
   70        * to be started.
   71        */
   72       protected void start(UserTransaction userTransaction) {
   73       }
   74   
   75       /**
   76        * <p>
   77        * Called in order to inform the <code>SchedulerPlugin</code> that it
   78        * should free up all of it's resources because the scheduler is shutting
   79        * down.
   80        * </p>
   81        * 
   82        * <p>
   83        * If UserTransaction is not null, the plugin can call setRollbackOnly()
   84        * on it to signal that the wrapped transaction should rollback.  
   85        * </p>
   86        * 
   87        * @param userTransaction The UserTranaction object used to provide a 
   88        * transaction around the shutdown() operation.  It will be null if 
   89        * <em>wrapInUserTransaction</em> is false or if the transaction failed
   90        * to be started.
   91        */
   92       protected void shutdown(UserTransaction userTransaction) {
   93       }
   94   
   95       /**
   96        * Get the commons Log for this class.
   97        */
   98       protected Log getLog() {
   99           return log;
  100       }
  101   
  102       /**
  103        * Get the name of this plugin.  Set as part of initialize().
  104        */
  105       protected String getName() {
  106           return name;
  107       }
  108   
  109       /**
  110        * Get this plugin's <code>Scheduler</code>.  Set as part of initialize().
  111        */
  112       protected Scheduler getScheduler() {
  113           return scheduler;
  114       }
  115   
  116       public void initialize(String name, Scheduler scheduler) throws SchedulerException {
  117           this.name = name;
  118           this.scheduler = scheduler;
  119       }
  120       
  121       /**
  122        * Wrap the start() and shutdown() methods in a UserTransaction.  This is necessary
  123        * for some plugins if using the JobStoreCMT.
  124        */
  125       public boolean getWrapInUserTransaction() {
  126           return wrapInUserTransaction;
  127       }
  128   
  129       /**
  130        * Wrap the start() and shutdown() methods in a UserTransaction.  This is necessary
  131        * for some plugins if using the JobStoreCMT.
  132        */
  133       public void setWrapInUserTransaction(boolean wrapInUserTransaction) {
  134           this.wrapInUserTransaction = wrapInUserTransaction;
  135       }
  136   
  137       /**
  138        * Based on the value of <em>wrapInUserTransaction</em>, wraps the
  139        * call to start(UserTransaction) in a UserTransaction.
  140        */
  141       public void start() {
  142           UserTransaction userTransaction = startUserTransaction();
  143           try {
  144               start(userTransaction);
  145           } finally {
  146               resolveUserTransaction(userTransaction);
  147           }
  148       }
  149   
  150       /**
  151        * Based on the value of <em>wrapInUserTransaction</em>, wraps the
  152        * call to shutdown(UserTransaction) in a UserTransaction.
  153        */
  154       public void shutdown() {
  155           UserTransaction userTransaction = startUserTransaction();
  156           try {
  157               shutdown(userTransaction);
  158           } finally {
  159               resolveUserTransaction(userTransaction);
  160           }
  161       }
  162           
  163       /**
  164        * If <em>wrapInUserTransaction</em> is true, starts a new UserTransaction 
  165        * and returns it. Otherwise, or if establishing the transaction fail, it 
  166        * will return null.
  167        */
  168       private UserTransaction startUserTransaction() {
  169           if (wrapInUserTransaction == false) {
  170               return null;
  171           }
  172           
  173           UserTransaction userTransaction = null;
  174           try {
  175               userTransaction = UserTransactionHelper.lookupUserTransaction();
  176               userTransaction.begin();
  177           } catch (Throwable t) {
  178               UserTransactionHelper.returnUserTransaction(userTransaction);
  179               userTransaction = null;
  180               getLog().error("Failed to start UserTransaction for plugin: " + getName(), t);
  181           }
  182           
  183           return userTransaction;
  184       }
  185       
  186       /**
  187        * If the given UserTransaction is not null, it is committed/rolledback,
  188        * and then returned to the UserTransactionHelper.
  189        */
  190       private void resolveUserTransaction(UserTransaction userTransaction) {
  191           if (userTransaction != null) {
  192               try {
  193                   if (userTransaction.getStatus() == Status.STATUS_MARKED_ROLLBACK) {
  194                       userTransaction.rollback();
  195                   } else {
  196                       userTransaction.commit();
  197                   } 
  198               } catch (Throwable t) {
  199                   getLog().error("Failed to resolve UserTransaction for plugin: " + getName(), t);
  200               } finally {
  201                   UserTransactionHelper.returnUserTransaction(userTransaction);
  202               }
  203           }
  204       }
  205   }

Home » quartz-1.6.0 » org » quartz » plugins » [javadoc | source]