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