001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.camel.processor;
018    
019    import org.apache.camel.Endpoint;
020    import org.apache.camel.Exchange;
021    import org.apache.camel.PollingConsumer;
022    import org.apache.camel.Processor;
023    import org.apache.camel.impl.LoggingExceptionHandler;
024    import org.apache.camel.impl.ServiceSupport;
025    import org.apache.camel.processor.resequencer.ResequencerEngine;
026    import org.apache.camel.processor.resequencer.SequenceElementComparator;
027    import org.apache.camel.processor.resequencer.SequenceSender;
028    import org.apache.camel.spi.ExceptionHandler;
029    import org.apache.camel.util.ServiceHelper;
030    
031    /**
032     * A resequencer that re-orders a (continuous) stream of {@link Exchange}s. The
033     * algorithm implemented by {@link ResequencerEngine} is based on the detection
034     * of gaps in a message stream rather than on a fixed batch size. Gap detection
035     * in combination with timeouts removes the constraint of having to know the
036     * number of messages of a sequence (i.e. the batch size) in advance.
037     * <p>
038     * Messages must contain a unique sequence number for which a predecessor and a
039     * successor is known. For example a message with the sequence number 3 has a
040     * predecessor message with the sequence number 2 and a successor message with
041     * the sequence number 4. The message sequence 2,3,5 has a gap because the
042     * sucessor of 3 is missing. The resequencer therefore has to retain message 5
043     * until message 4 arrives (or a timeout occurs).
044     * <p>
045     * Instances of this class poll for {@link Exchange}s from a given
046     * <code>endpoint</code>. Resequencing work and the delivery of messages to
047     * the next <code>processor</code> is done within the single polling thread.
048     * 
049     * @author Martin Krasser
050     * 
051     * @version $Revision: 699788 $
052     * 
053     * @see ResequencerEngine
054     */
055    public class StreamResequencer extends ServiceSupport implements SequenceSender<Exchange>, Runnable, Processor {
056    
057        private ExceptionHandler exceptionHandler;
058        private ResequencerEngine<Exchange> engine;
059        private PollingConsumer<? extends Exchange> consumer;
060        private Endpoint<? extends Exchange> endpoint;
061        private Processor processor;
062        private Thread worker;
063        private int capacity;
064        
065        /**
066         * Creates a new {@link StreamResequencer} instance.
067         * 
068         * @param endpoint
069         *            endpoint to poll exchanges from.
070         * @param processor
071         *            next processor that processes re-ordered exchanges.
072         * @param comparator
073         *            a sequence element comparator for exchanges.
074         */
075        public StreamResequencer(Endpoint<? extends Exchange> endpoint, Processor processor, SequenceElementComparator<Exchange> comparator) {
076            this.exceptionHandler = new LoggingExceptionHandler(getClass());
077            this.engine = new ResequencerEngine<Exchange>(comparator);
078            this.engine.setSequenceSender(this);
079            this.endpoint = endpoint;
080            this.processor = processor;
081        }
082    
083        /**
084         * Returns this resequencer's exception handler.
085         * 
086         * @return this resequencer's exception handler.
087         */
088        public ExceptionHandler getExceptionHandler() {
089            return exceptionHandler;
090        }
091    
092        /**
093         * Returns the next processor.
094         * 
095         * @return the next processor.
096         */
097        public Processor getProcessor() {
098            return processor;
099        }
100    
101        /**
102         * Returns this resequencer's capacity. The capacity is the maximum number
103         * of exchanges that can be managed by this resequencer at a given point in
104         * time. If the capacity if reached, polling from the endpoint will be
105         * skipped for <code>timeout</code> milliseconds giving exchanges the
106         * possibility to time out and to be delivered after the waiting period.
107         * 
108         * @return this resequencer's capacity.
109         */
110        public int getCapacity() {
111            return capacity;
112        }
113    
114        /**
115         * Returns this resequencer's timeout. This sets the resequencer engine's
116         * timeout via {@link ResequencerEngine#setTimeout(long)}. This value is
117         * also used to define the polling timeout from the endpoint.
118         * 
119         * @return this resequencer's timeout.
120         * (Processor) 
121         * @see ResequencerEngine#setTimeout(long)
122         */
123        public long getTimeout() {
124            return engine.getTimeout();
125        }
126    
127        public void setCapacity(int capacity) {
128            this.capacity = capacity;
129        }
130    
131        public void setTimeout(long timeout) {
132            engine.setTimeout(timeout);
133        }
134    
135        @Override
136        public String toString() {
137            return "StreamResequencer[to: " + processor + "]";
138        }
139    
140        @Override
141        protected void doStart() throws Exception {
142            consumer = endpoint.createPollingConsumer();
143            ServiceHelper.startServices(processor, consumer);
144            worker = new Thread(this, this + " Polling Thread");
145            engine.start();
146            worker.start();
147        }
148    
149        @Override
150        protected void doStop() throws Exception {
151            // let's stop everything in the reverse order
152            // no need to stop the worker thread -- it will stop automatically when this service is stopped
153            engine.stop();
154            ServiceHelper.stopServices(consumer, processor);
155        }
156    
157        /**
158         * Sends the <code>exchange</code> to the next <code>processor</code>.
159         * 
160         * @param o
161         *            exchange to send.
162         */
163        public void sendElement(Exchange o) throws Exception {
164            processor.process(o);
165        }
166    
167        /**
168         * Loops over {@link #processExchange()}.
169         */
170        public void run() {
171            while (!isStopped() && !isStopping()) {
172                try {
173                    processExchange();
174                } catch (Exception e) {
175                    exceptionHandler.handleException(e);
176                }
177            }
178        }
179    
180        /**
181         * Processes an exchange received from the this resequencer's
182         * <code>endpoint</code>. Received exchanges are processed via
183         * {@link ResequencerEngine#insert(Object)}.
184         * {@link ResequencerEngine#deliver()} is then called in any case regardless
185         * whether a message was received or receiving timed out.
186         * 
187         * @throws Exception
188         *             if exchange delivery fails.
189         */
190        protected void processExchange() throws Exception {
191            if (engine.size() >= capacity) {
192                Thread.sleep(getTimeout());
193            } else {
194                Exchange exchange = consumer.receive(getTimeout());
195                if (exchange != null) {
196                    engine.insert(exchange);
197                }
198            }
199            engine.deliver();
200        }
201    
202        public void process(Exchange exchange) throws Exception {
203            // empty since exchanges come from endpoint's polling consumer
204        }
205    
206    }