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