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.spi;
018
019import java.util.List;
020import java.util.Optional;
021import java.util.Properties;
022import java.util.function.Predicate;
023
024import org.apache.camel.Component;
025import org.apache.camel.StaticService;
026
027/**
028 * Component for property placeholders and loading properties from sources
029 * (such as .properties file from classpath or file system)
030 */
031public interface PropertiesComponent extends Component, StaticService {
032
033    /**
034     * The prefix token.
035     */
036    String PREFIX_TOKEN = "{{";
037
038    /**
039     * The suffix token.
040     */
041    String SUFFIX_TOKEN = "}}";
042
043    /**
044     * Has the component been created as a default by {@link org.apache.camel.CamelContext} during starting up Camel.
045     */
046    String DEFAULT_CREATED = "PropertiesComponentDefaultCreated";
047
048    /**
049     * Parses the input text and resolve all property placeholders from within the text.
050     *
051     * @param uri  input text
052     * @return text with resolved property placeholders
053     * @throws IllegalArgumentException is thrown if error during parsing
054     */
055    String parseUri(String uri);
056
057    /**
058     * Looks up the property with the given key
059     *
060     * @param key  the name of the property
061     * @return the property value if present
062     */
063    Optional<String> resolveProperty(String key);
064
065    /**
066     * Loads the properties from the default locations and sources.
067     *
068     * @return the properties loaded.
069     */
070    Properties loadProperties();
071
072    /**
073     * Loads the properties from the default locations and sources filtering them out according to a predicate.
074     * </p>
075     * <pre>{@code
076     *     PropertiesComponent pc = getPropertiesComponent();
077     *     Properties props = pc.loadProperties(key -> key.startsWith("camel.component.seda"));
078     * }</pre>
079     *
080     * @param filter the predicate used to filter out properties based on the key.
081     * @return the properties loaded.
082     */
083    Properties loadProperties(Predicate<String> filter);
084
085    /**
086     * Gets the configured properties locations.
087     * This may be empty if the properties component has only been configured with {@link PropertiesSource}.
088     */
089    List<String> getLocations();
090
091    /**
092     * A list of locations to load properties. You can use comma to separate multiple locations.
093     * This option will override any default locations and only use the locations from this option.
094     */
095    void setLocation(String location);
096
097    /**
098     * Adds the list of locations to the current locations, where to load properties.
099     * You can use comma to separate multiple locations.
100     */
101    void addLocation(String location);
102
103    /**
104     * Adds a custom {@link PropertiesSource} to use as source for loading and/or looking up property values.
105     */
106    void addPropertiesSource(PropertiesSource propertiesSource);
107
108    /**
109     * Whether to silently ignore if a location cannot be located, such as a properties file not found.
110     */
111    void setIgnoreMissingLocation(boolean ignoreMissingLocation);
112
113    /**
114     * Sets initial properties which will be added before any property locations are loaded.
115     */
116    void setInitialProperties(Properties initialProperties);
117
118    /**
119     * Sets a special list of override properties that take precedence
120     * and will use first, if a property exist.
121     */
122    void setOverrideProperties(Properties overrideProperties);
123
124}