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