001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.util;
029
030/**
031 * Describes a macro mapper, which is used to efficiently resolve macros
032 * in the form of <code>%(key)</code> or <code>${key}</code> in an input String.<p>
033 *
034 * Starting with OpenCms 7.0, the preferred form of a macro is <code>%(key)</code>. This is to
035 * avoid conflicts / confusion with the JSP EL, which also uses the <code>${key}</code> syntax.<p>
036 *
037 * The macro replacement is pre-implemented in
038 * <code>{@link org.opencms.util.CmsMacroResolver#resolveMacros(String, I_CmsMacroResolver)}</code>.<p>
039 *
040 * @since 6.0.0
041 */
042public interface I_CmsMacroResolver {
043
044    /** Delimiter char <code>'%'</code> for a macro - new / current style. */
045    char MACRO_DELIMITER = '%';
046
047    /** Delimiter char <code>'$'</code> for a macro - old style. */
048    char MACRO_DELIMITER_OLD = '$';
049
050    /** End char <code>')'</code> for a macro - new / current style. */
051    char MACRO_END = ')';
052
053    /** End char <code>'}'</code> for a macro - old style. */
054    char MACRO_END_OLD = '}';
055
056    /** Start char <code>'('</code> for a macro - new / current style. */
057    char MACRO_START = '(';
058
059    /** Start char <code>'{'</code> for a macro - old style.  */
060    char MACRO_START_OLD = '{';
061
062    /**
063     * Resolves a single macro to the macro value, returns <code>null</code> if the macro could not be resolved.<p>
064     *
065     * @param macro the macro to resolve
066     * @return the resolved macro or <code>null</code> if the macro could not be resolved
067     */
068    String getMacroValue(String macro);
069
070    /**
071     * Returns <code>true</code> if macros that could not be resolved are kept "as is" in the
072     * input String, <code>false</code> if they are replaced by an empty String.<p>
073     *
074     * @return <code>true</code> if macros that could not be resolved are kept "as is" in the
075     *      input String, <code>false</code> if they are replaced by an empty String
076     */
077    boolean isKeepEmptyMacros();
078
079    /**
080     * Resolves all macros in the input, replacing them with the macro values.<p>
081     *
082     * The flag {@link #isKeepEmptyMacros()} controls how to deal with
083     * macros found in the input that can not be resolved.
084     *
085     * @param input the input to resolve the macros in
086     *
087     * @return the input with all macros resolved
088     */
089    String resolveMacros(String input);
090}