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 */
017package org.apache.camel.spi;
018
019import java.util.concurrent.CompletableFuture;
020import java.util.concurrent.RejectedExecutionException;
021
022import org.apache.camel.AsyncCallback;
023import org.apache.camel.AsyncProcessor;
024import org.apache.camel.AsyncProducer;
025import org.apache.camel.Endpoint;
026import org.apache.camel.Exchange;
027import org.apache.camel.ExchangePattern;
028import org.apache.camel.Processor;
029import org.apache.camel.Producer;
030import org.apache.camel.Service;
031
032/**
033 * Cache containing created {@link Producer}.
034 */
035public interface ProducerCache extends Service {
036
037    /**
038     * Acquires a pooled producer which you <b>must</b> release back again after usage using the
039     * {@link #releaseProducer(org.apache.camel.Endpoint, org.apache.camel.AsyncProducer)} method.
040     * <p/>
041     * If the producer is currently starting then the cache will wait at most 30 seconds for the producer
042     * to finish starting and be ready for use.
043     *
044     * @param endpoint the endpoint
045     * @return the producer
046     */
047    AsyncProducer acquireProducer(Endpoint endpoint);
048
049    /**
050     * Releases an acquired producer back after usage.
051     *
052     * @param endpoint the endpoint
053     * @param producer the producer to release
054     */
055    void releaseProducer(Endpoint endpoint, AsyncProducer producer);
056
057    /**
058     * Sends the exchange to the given endpoint.
059     * <p>
060     * This method will <b>not</b> throw an exception. If processing of the given
061     * Exchange failed then the exception is stored on the provided Exchange
062     *
063     * @param endpoint the endpoint to send the exchange to
064     * @param exchange the exchange to send
065     * @throws RejectedExecutionException is thrown if CamelContext is stopped
066     */
067    Exchange send(Endpoint endpoint, Exchange exchange, Processor resultProcessor);
068
069    /**
070     * Asynchronously sends an exchange to an endpoint using a supplied
071     * {@link Processor} to populate the exchange
072     * <p>
073     * This method will <b>neither</b> throw an exception <b>nor</b> complete future exceptionally.
074     * If processing of the given Exchange failed then the exception is stored on the return Exchange
075     *
076     * @param endpoint        the endpoint to send the exchange to
077     * @param pattern         the message {@link ExchangePattern} such as
078     *                        {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
079     * @param processor       the transformer used to populate the new exchange
080     * @param resultProcessor a processor to process the exchange when the send is complete.
081     * @param exchange        an exchange to use in processing. Exchange will be created if parameter is null.
082     * @param future          the preexisting future to complete when processing is done or null if to create new one
083     * @return future that completes with exchange when processing is done. Either passed into future parameter
084     *              or new one if parameter was null
085     */
086    CompletableFuture<Exchange> asyncSendExchange(Endpoint endpoint, ExchangePattern pattern,
087            Processor processor, Processor resultProcessor, Exchange exchange, CompletableFuture<Exchange> future);
088
089    /**
090     * Gets the source which uses this cache
091     *
092     * @return the source
093     */
094    Object getSource();
095
096    /**
097     * Returns the current size of the cache
098     *
099     * @return the current size
100     */
101    int size();
102
103    /**
104     * Gets the maximum cache size (capacity).
105     *
106     * @return the capacity
107     */
108    int getCapacity();
109
110    /**
111     * Gets the cache hits statistic
112     * <p/>
113     * Will return <tt>-1</tt> if it cannot determine this if a custom cache was used.
114     *
115     * @return the hits
116     */
117    long getHits();
118
119    /**
120     * Gets the cache misses statistic
121     * <p/>
122     * Will return <tt>-1</tt> if it cannot determine this if a custom cache was used.
123     *
124     * @return the misses
125     */
126    long getMisses();
127
128    /**
129     * Gets the cache evicted statistic
130     * <p/>
131     * Will return <tt>-1</tt> if it cannot determine this if a custom cache was used.
132     *
133     * @return the evicted
134     */
135    long getEvicted();
136
137    /**
138     * Resets the cache statistics
139     */
140    void resetCacheStatistics();
141
142    /**
143     * Purges this cache
144     */
145    void purge();
146
147    /**
148     * Cleanup the cache (purging stale entries)
149     */
150    void cleanUp();
151
152    boolean isEventNotifierEnabled();
153
154    /**
155     * Whether {@link org.apache.camel.spi.EventNotifier} is enabled
156     */
157    void setEventNotifierEnabled(boolean eventNotifierEnabled);
158
159    /**
160     * Gets the endpoint statistics
161     */
162    EndpointUtilizationStatistics getEndpointUtilizationStatistics();
163
164    /**
165     * Sends an exchange to an endpoint using a supplied callback supporting the asynchronous routing engine.
166     * <p/>
167     * If an exception was thrown during processing, it would be set on the given Exchange
168     *
169     * @param endpoint         the endpoint to send the exchange to
170     * @param exchange         the exchange, can be <tt>null</tt> if so then create a new exchange from the producer
171     * @param callback         the asynchronous callback
172     * @param producerCallback the producer template callback to be executed
173     * @return (doneSync) <tt>true</tt> to continue execute synchronously, <tt>false</tt> to continue being executed asynchronously
174     */
175    boolean doInAsyncProducer(Endpoint endpoint, Exchange exchange, AsyncCallback callback, AsyncProducerCallback producerCallback);
176
177    /**
178     * Callback for sending a exchange message to a endpoint using an {@link AsyncProcessor} capable producer.
179     * <p/>
180     * Using this callback as a template pattern ensures that Camel handles the resource handling and will
181     * start and stop the given producer, to avoid resource leaks.
182     */
183    interface AsyncProducerCallback {
184
185        /**
186         * Performs operation on the given producer to send the given exchange.
187         *
188         * @param asyncProducer   the async producer, is never <tt>null</tt>
189         * @param exchange        the exchange to process
190         * @param callback        the async callback
191         * @return (doneSync) <tt>true</tt> to continue execute synchronously, <tt>false</tt> to continue being executed asynchronously
192         */
193        boolean doInAsyncProducer(AsyncProducer asyncProducer, Exchange exchange, AsyncCallback callback);
194    }
195
196}