View Javadoc

1   /*
2    * $Id: AbstractPollingMessageReceiver.java 19755 2010-09-28 14:05:50Z esteban.robles $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  
11  package org.mule.transport;
12  
13  import org.mule.api.MuleException;
14  import org.mule.api.construct.FlowConstruct;
15  import org.mule.api.endpoint.InboundEndpoint;
16  import org.mule.api.lifecycle.CreateException;
17  import org.mule.api.transport.Connector;
18  import org.mule.config.i18n.CoreMessages;
19  import org.mule.util.ObjectUtils;
20  
21  import java.util.Iterator;
22  import java.util.LinkedList;
23  import java.util.List;
24  
25  import edu.emory.mathcs.backport.java.util.concurrent.Future;
26  import edu.emory.mathcs.backport.java.util.concurrent.RejectedExecutionException;
27  import edu.emory.mathcs.backport.java.util.concurrent.ScheduledExecutorService;
28  import edu.emory.mathcs.backport.java.util.concurrent.ScheduledFuture;
29  import edu.emory.mathcs.backport.java.util.concurrent.TimeUnit;
30  
31  /**
32   * <code>AbstractPollingMessageReceiver</code> implements a base class for polling
33   * message receivers. The receiver provides a {@link #poll()} method that implementations
34   * must implement to execute their custom code. Note that the receiver will not poll if
35   * the associated connector is not started.
36   */
37  public abstract class AbstractPollingMessageReceiver extends AbstractMessageReceiver
38  {
39      public static final long DEFAULT_POLL_FREQUENCY = 1000;
40      public static final TimeUnit DEFAULT_POLL_TIMEUNIT = TimeUnit.MILLISECONDS;
41  
42      public static final long DEFAULT_STARTUP_DELAY = 1000;
43  
44      private long frequency = DEFAULT_POLL_FREQUENCY;
45      private TimeUnit timeUnit = DEFAULT_POLL_TIMEUNIT;
46  
47      // @GuardedBy(itself)
48      protected final List<ScheduledFuture> schedules = new LinkedList<ScheduledFuture>();
49  
50      public AbstractPollingMessageReceiver(Connector connector,
51                                            FlowConstruct flowConstruct,
52                                            final InboundEndpoint endpoint) throws CreateException
53      {
54          super(connector, flowConstruct, endpoint);
55      }
56  
57      @Override
58      protected void doStart() throws MuleException
59      {
60          try
61          {
62              this.schedule();
63          }
64          catch (Exception ex)
65          {
66              this.stop();
67              throw new CreateException(CoreMessages.failedToScheduleWork(), ex, this);
68          }
69      }
70  
71      @Override
72      protected void doStop() throws MuleException
73      {
74          this.unschedule();
75      }
76  
77      /**
78       * This method registers this receiver for periodic polling ticks with the connectors
79       * scheduler. Subclasses can override this in case they want to handle their polling
80       * differently.
81       * 
82       * @throws RejectedExecutionException
83       * @throws NullPointerException
84       * @throws IllegalArgumentException
85       * @see ScheduledExecutorService#scheduleWithFixedDelay(Runnable, long, long, TimeUnit)
86       */
87      protected void schedule()
88          throws RejectedExecutionException, NullPointerException, IllegalArgumentException
89      {
90          synchronized (schedules)
91          {
92              // we use scheduleWithFixedDelay to prevent queue-up of tasks when
93              // polling takes longer than the specified frequency, e.g. when the
94              // polled database or network is slow or returns large amounts of
95              // data.
96              ScheduledFuture schedule = connector.getScheduler().scheduleWithFixedDelay(
97                  new PollingReceiverWorkerSchedule(this.createWork()), DEFAULT_STARTUP_DELAY,
98                  this.getFrequency(), this.getTimeUnit());
99              schedules.add(schedule);
100 
101             if (logger.isDebugEnabled())
102             {
103                 logger.debug(ObjectUtils.identityToShortString(this) + " scheduled "
104                              + ObjectUtils.identityToShortString(schedule) + " with " + frequency
105                              + " " + getTimeUnit() + " polling frequency");
106             }
107         }
108     }
109 
110     /**
111      * This method cancels the schedules which were created in {@link #schedule()}.
112      * 
113      * @see Future#cancel(boolean)
114      */
115     protected void unschedule()
116     {
117         synchronized (schedules)
118         {
119             // cancel our schedules gently: do not interrupt when polling is in progress
120             for (Iterator<ScheduledFuture> i = schedules.iterator(); i.hasNext();)
121             {
122                 ScheduledFuture schedule = i.next();
123                 schedule.cancel(false);
124                 i.remove();
125 
126                 if (logger.isDebugEnabled())
127                 {
128                     logger.debug(ObjectUtils.identityToShortString(this) + " cancelled polling schedule: "
129                                  + ObjectUtils.identityToShortString(schedule));
130                 }
131             }
132         }
133     }
134     
135     public void disableNativeScheduling()
136     {
137         this.unschedule();
138     }
139 
140     protected PollingReceiverWorker createWork()
141     {
142         return new PollingReceiverWorker(this);
143     }
144 
145     public long getFrequency()
146     {
147         return frequency;
148     }
149 
150     // TODO a nifty thing would be on-the-fly adjustment (via JMX?) of the
151     // polling frequency by rescheduling without explicit stop()
152     public void setFrequency(long value)
153     {
154         if (value <= 0)
155         {
156             frequency = DEFAULT_POLL_FREQUENCY;
157         }
158         else
159         {
160             frequency = value;
161         }
162     }
163 
164     public TimeUnit getTimeUnit()
165     {
166         return timeUnit;
167     }
168 
169     public void setTimeUnit(TimeUnit timeUnit)
170     {
171         this.timeUnit = timeUnit;
172     }
173 
174     public abstract void poll() throws Exception;
175 
176 }