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