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