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    
020    /**
021     * An <a href="http://activemq.apache.org/camel/endpoint.html">endpoint</a> implements the 
022     * <a href="http://activemq.apache.org/camel/message-endpoint.html">Message Endpoint</a>
023     * pattern and represents an endpoint that can send and receive message exchanges
024     *
025     * @see Exchange, Message
026     * @version $Revision: 541693 $
027     */
028    public interface Endpoint<E extends Exchange> {
029    
030        /**
031         * Returns if the endpoint should be a CamelContext singleton.  If the endpoint is a Singleton,
032         * then a single Endpoint instance will be shared by all routes with the same URI.  Because the endpoint
033         * is shared, it should be treated as an immutable.
034         */
035        boolean isSingleton();
036    
037        /**
038         * Returns the string representation of the endpoint URI
039         */
040        String getEndpointUri();
041        
042        /**
043         * Create a new exchange for communicating with this endpoint
044         */
045        E createExchange();
046    
047        /**
048         * Creates a new exchange for communicating with this exchange using the given exchange to pre-populate the values
049         * of the headers and messages
050         */
051        E createExchange(Exchange exchange);
052    
053        /**
054         * Converts the given exchange to this endpoints required type
055         */
056        E toExchangeType(Exchange exchange);
057    
058        /**
059         * Returns the context which created the endpoint
060         *
061         * @return the context which created the endpoint
062         */
063        CamelContext getContext();
064    
065        /**
066         * Creates a new producer which is used send messages into the endpoint
067         *
068         * @return a newly created producer
069         */
070        Producer<E> createProducer() throws Exception;
071    
072        /**
073         * Creates a new <a href="http://activemq.apache.org/camel/event-driven-consumer.html">Event Driven Consumer</a>
074         * which consumes messages from the endpoint using the given processor
075         *
076         * @return a newly created consumer
077         */
078        Consumer<E> createConsumer(Processor processor) throws Exception;
079    
080        /**
081         * Creates a new <a href="http://activemq.apache.org/camel/polling-consumer.html">Polling Consumer</a>
082         * so that the caller can poll message exchanges from the consumer
083         * using {@link PollingConsumer#receive()}, {@link PollingConsumer#receiveNoWait()} or {@link PollingConsumer#receive(long)}
084         * whenever it is ready to do so rather than using the
085         * <a href="http://activemq.apache.org/camel/event-driven-consumer.html">Event Based Consumer</a>
086         * returned by {@link #createConsumer(Processor)}
087         *
088         * @return a newly created pull consumer
089         * @throws Exception if the pull consumer could not be created
090         */
091        PollingConsumer<E> createPollingConsumer() throws Exception;
092    }