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: 45729 $
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    }