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