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.net.URISyntaxException;
020 import java.util.List;
021 import java.util.Map;
022 import java.util.SortedMap;
023
024 import org.apache.camel.impl.ParameterConfiguration;
025
026 /**
027 * Represents a set of configuration values for an endpoint URI which can be created from a URI string
028 * or a base URI string and a set of parameter names and values.
029 *
030 * The configuration values can then be introspected, modified and converted back into a URI string
031 * or Endpoint.
032 *
033 * For @{link UriEndpointComponent} implementations created for Endpoints annotated with {@link org.apache.camel.spi.UriEndpoint} and the
034 * associated annotations then all the parameter values can be introspected and the parameter values are converted to their
035 * correct type.
036 *
037 * Other implementations keep all the types as String and there is no validation until you try to create
038 * an Endpoint from the values.
039 */
040 public interface ComponentConfiguration {
041
042 /**
043 * Returns the base URI without any query parameters added
044 */
045 String getBaseUri();
046
047 /**
048 * Sets the base URI without any query parameters added
049 */
050 void setBaseUri(String baseUri);
051
052 /**
053 * Returns the current parameters of the configuration (usually encoded as ?foo=bar&whatnot=something URI query parameters)
054 */
055 Map<String, Object> getParameters();
056
057 /**
058 * Sets the parameter values of this configuration
059 */
060 void setParameters(Map<String, Object> propertyValues);
061
062 /**
063 * Returns the parameter value for the given name
064 *
065 * @param name the name of the URI query parameter to get
066 * @return the value of the parameter
067 */
068 Object getParameter(String name);
069
070 /**
071 * Sets the parameter value of the given name
072 *
073 * @param name the name of the URI query parameter
074 * @param value the new value of the parameter
075 */
076 void setParameter(String name, Object value);
077
078
079 /**
080 * Returns the URI string (without schema) with query parameters for the current
081 * configuration which can then be used to create an {@link org.apache.camel.Endpoint}
082 */
083 String getUriString();
084
085 /**
086 * Sets the URI string (without schema but with optional query parameters)
087 * which will update the {@link #getBaseUri()} and the {@link #getParameters()} values
088 *
089 * @param newValue the new URI string with query arguments
090 */
091 void setUriString(String newValue) throws URISyntaxException;
092
093 /**
094 * Returns the URI query parameter configuration for the given parameter name or null if it does not exist
095 */
096 ParameterConfiguration getParameterConfiguration(String name);
097
098 /**
099 * Returns the sorted map of all the parameter names to their {@link ParameterConfiguration} objects
100 */
101 SortedMap<String, ParameterConfiguration> getParameterConfigurationMap();
102
103 /**
104 * Converts the configuration into a URI and then looks up the endpoint in the {@link CamelContext}
105 * which typically results in a new {@link Endpoint} instance being created.
106 */
107 Endpoint createEndpoint() throws Exception;
108
109 /**
110 * Applies the current set of parameters to the given endpoint instance.
111 * <p/>
112 * Note that typically parts of the URI are not injected into the Endpoint; this method purely
113 *
114 * @param endpoint
115 */
116 void configureEndpoint(Endpoint endpoint);
117
118 /**
119 * Gets the named URI parameter value on the given endpoint
120 *
121 * @param endpoint the endpoint instance
122 * @param name the name of the URI query parameter
123 * @return the value of the parameter
124 * @throws RuntimeCamelException if the parameter name does not exist on the endpoint
125 */
126 Object getEndpointParameter(Endpoint endpoint, String name) throws RuntimeCamelException;
127
128 /**
129 * Sets the named URI query parameter value on the given endpoint
130 *
131 * @param endpoint the endpoint instance
132 * @param name the name of the URI query parameter
133 * @param value the new value of the URI query parameter
134 * @throws RuntimeCamelException
135 */
136 void setEndpointParameter(Endpoint endpoint, String name, Object value) throws RuntimeCamelException;
137
138 /**
139 * A helper method for tools such as CLIs, IDEs or web tools that provides a completion list for Endpoint Paths
140 * rather like bash tab completion or Karaf attribute or option completion handers.
141 *
142 * So given the current configuration data, return a list of completions given the specified text.
143 *
144 * e.g. return the files in a directory, the matching queues in a message broker, the database tables in a database component etc
145 *
146 * @param completionText the prefix text used to complete on (usually a matching bit of text)
147 *
148 * @return a list of matches
149 * @return a list of matches
150 */
151 List<String> completeEndpointPath(String completionText);
152
153 /**
154 * Creates a <a href="http://json-schema.org/">JSON schema</a> representation of the
155 * configuration parameters for this endpoint and the types and validation rules.
156 *
157 * @return a JSON string which represents the JSON schema for this endpoints configuration parameters.
158 */
159 String createParameterJsonSchema();
160 }
161