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://camel.apache.org/endpoint.html">endpoint</a>
023 * implements the <a
024 * href="http://camel.apache.org/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: 979164 $
031 */
032 public interface Endpoint extends IsSingleton, Service {
033
034 /**
035 * Returns the string representation of the endpoint URI
036 *
037 * @return the endpoint URI
038 */
039 String getEndpointUri();
040
041 /**
042 * Returns a string key of this endpoint.
043 * <p/>
044 * This key is used by {@link org.apache.camel.spi.LifecycleStrategy} when registering endpoint.
045 * This allows to register different instances of endpoints with the same key.
046 * <p/>
047 * For JMX mbeans this allows us to use the same JMX Mbean for all endpoints that are logical
048 * the same but have different parameters. For instance the http endpoint.
049 *
050 * @return the endpoint key
051 */
052 String getEndpointKey();
053
054 /**
055 * Create a new exchange for communicating with this endpoint
056 *
057 * @return a new exchange
058 */
059 Exchange createExchange();
060
061 /**
062 * Create a new exchange for communicating with this endpoint
063 * with the specified {@link ExchangePattern} such as whether its going
064 * to be an {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} exchange
065 *
066 * @param pattern the message exchange pattern for the exchange
067 * @return a new exchange
068 */
069 Exchange createExchange(ExchangePattern pattern);
070
071 /**
072 * Creates a new exchange for communicating with this exchange using the
073 * given exchange to pre-populate the values of the headers and messages
074 *
075 * @param exchange given exchange to use for pre-populate
076 * @return a new exchange
077 */
078 Exchange createExchange(Exchange exchange);
079
080 /**
081 * Returns the context which created the endpoint
082 *
083 * @return the context which created the endpoint
084 */
085 CamelContext getCamelContext();
086
087 /**
088 * Creates a new producer which is used send messages into the endpoint
089 *
090 * @return a newly created producer
091 * @throws Exception can be thrown
092 */
093 Producer createProducer() throws Exception;
094
095 /**
096 * Creates a new <a
097 * href="http://camel.apache.org/event-driven-consumer.html">Event
098 * Driven Consumer</a> which consumes messages from the endpoint using the
099 * given processor
100 *
101 * @param processor the given processor
102 * @return a newly created consumer
103 * @throws Exception can be thrown
104 */
105 Consumer createConsumer(Processor processor) throws Exception;
106
107 /**
108 * Creates a new <a
109 * href="http://camel.apache.org/polling-consumer.html">Polling
110 * Consumer</a> so that the caller can poll message exchanges from the
111 * consumer using {@link PollingConsumer#receive()},
112 * {@link PollingConsumer#receiveNoWait()} or
113 * {@link PollingConsumer#receive(long)} whenever it is ready to do so
114 * rather than using the <a
115 * href="http://camel.apache.org/event-driven-consumer.html">Event
116 * Based Consumer</a> returned by {@link #createConsumer(Processor)}
117 *
118 * @return a newly created pull consumer
119 * @throws Exception if the pull consumer could not be created
120 */
121 PollingConsumer createPollingConsumer() throws Exception;
122
123 /**
124 * Configure properties on this endpoint.
125 *
126 * @param options the options (properties)
127 */
128 void configureProperties(Map<String, Object> options);
129
130 /**
131 * Sets the camel context.
132 *
133 * @param context the camel context
134 */
135 void setCamelContext(CamelContext context);
136
137 /**
138 * Should all properties be known or does the endpoint allow unknown options?
139 * <p/>
140 * <tt>lenient = false</tt> means that the endpoint should validate that all
141 * given options is known and configured properly.
142 * <tt>lenient = true</tt> means that the endpoint allows additional unknown options to
143 * be passed to it but does not throw a ResolveEndpointFailedException when creating
144 * the endpoint.
145 * <p/>
146 * This options is used by a few components for instance the HTTP based that can have
147 * dynamic URI options appended that is targeted for an external system.
148 * <p/>
149 * Most endpoints is configured to be <b>not</b> lenient.
150 *
151 * @return whether properties is lenient or not
152 */
153 boolean isLenientProperties();
154 }