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;
018
019 import java.util.Map;
020
021 /**
022 * An <a href="http://activemq.apache.org/camel/endpoint.html">endpoint</a>
023 * implements the <a
024 * href="http://activemq.apache.org/camel/message-endpoint.html">Message
025 * Endpoint</a> pattern and represents an endpoint that can send and receive
026 * message exchanges
027 *
028 * @see Exchange
029 * @see Message
030 * @version $Revision: 684667 $
031 */
032 public interface Endpoint<E extends Exchange> {
033
034 /**
035 * Returns if the endpoint should be a CamelContext singleton. If the
036 * endpoint is a Singleton, then a single Endpoint instance will be shared
037 * by all routes with the same URI. Because the endpoint is shared, it
038 * should be treated as an immutable.
039 */
040 boolean isSingleton();
041
042 /**
043 * Returns the string representation of the endpoint URI
044 */
045 String getEndpointUri();
046
047 /**
048 * Create a new exchange for communicating with this endpoint
049 */
050 E createExchange();
051
052 /**
053 * Create a new exchange for communicating with this endpoint
054 * with the specified {@link ExchangePattern} such as whether its going
055 * to be an {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} exchange
056 *
057 * @param pattern the message exchange pattern for the exchange
058 */
059 E createExchange(ExchangePattern pattern);
060
061 /**
062 * Creates a new exchange for communicating with this exchange using the
063 * given exchange to pre-populate the values of the headers and messages
064 */
065 E createExchange(Exchange exchange);
066
067 /**
068 * Returns the context which created the endpoint
069 *
070 * @return the context which created the endpoint
071 */
072 CamelContext getCamelContext();
073
074 /**
075 * Creates a new producer which is used send messages into the endpoint
076 *
077 * @return a newly created producer
078 */
079 Producer<E> createProducer() throws Exception;
080
081 /**
082 * Creates a new <a
083 * href="http://activemq.apache.org/camel/event-driven-consumer.html">Event
084 * Driven Consumer</a> which consumes messages from the endpoint using the
085 * given processor
086 *
087 * @return a newly created consumer
088 */
089 Consumer<E> createConsumer(Processor processor) throws Exception;
090
091 /**
092 * Creates a new <a
093 * href="http://activemq.apache.org/camel/polling-consumer.html">Polling
094 * Consumer</a> so that the caller can poll message exchanges from the
095 * consumer using {@link PollingConsumer#receive()},
096 * {@link PollingConsumer#receiveNoWait()} or
097 * {@link PollingConsumer#receive(long)} whenever it is ready to do so
098 * rather than using the <a
099 * href="http://activemq.apache.org/camel/event-driven-consumer.html">Event
100 * Based Consumer</a> returned by {@link #createConsumer(Processor)}
101 *
102 * @return a newly created pull consumer
103 * @throws Exception if the pull consumer could not be created
104 */
105 PollingConsumer<E> createPollingConsumer() throws Exception;
106
107 void configureProperties(Map options);
108
109 void setCamelContext(CamelContext context);
110
111 @Deprecated
112 CamelContext getContext();
113
114 @Deprecated
115 void setContext(CamelContext context);
116
117 /**
118 * Should all properties be known or does the endpoint allow unknown options?
119 * <p/>
120 * <tt>Lenient = false</tt> means that the endpoint should validate that all
121 * given options is known and configured properly
122 * <tt>lenient = true</tt> means that the endpoint allows additional unknown options to
123 * be passed to it but does not throw a ResolveEndpointFailedException when creating
124 * the endpoint.
125 * <p/>
126 * This options is used by a few components for instance the HTTP based that can have
127 * dynamic URI options appended that is targeted for an external system.
128 * <p/>
129 * Most endpoints is configued to be <b>not</b> lenient.
130 */
131 boolean isLenientProperties();
132
133 }