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