| /* |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| */ |
| package org.apache.wiki.variables; |
| |
| import org.apache.wiki.api.core.Context; |
| import org.apache.wiki.api.exceptions.NoSuchVariableException; |
| |
| /** |
| * Manages variables. Variables are case-insensitive. A list of all available variables is on a Wiki page called "WikiVariables". |
| * |
| * @since 1.9.20. |
| */ |
| public interface VariableManager { |
| |
| // FIXME: These are probably obsolete. |
| String VAR_ERROR = "error"; |
| String VAR_MSG = "msg"; |
| |
| /** If this variable is set to false, all filters are disabled when translating. */ |
| String VAR_RUNFILTERS = "jspwiki.runFilters"; |
| |
| /** |
| * Parses the link and finds a value. This is essentially used once |
| * {@link org.apache.wiki.parser.LinkParsingOperations#isVariableLink(String) LinkParsingOperations#isVariableLink(String)} |
| * has found that the link text actually contains a variable. For example, you could pass in "{$username}" and get back |
| * "JanneJalkanen". |
| * |
| * @param context The WikiContext |
| * @param link The link text containing the variable name. |
| * @return The variable value. |
| * @throws IllegalArgumentException If the format is not valid (does not start with "{$", is zero length, etc.) |
| * @throws NoSuchVariableException If a variable is not known. |
| */ |
| String parseAndGetValue( Context context, String link ) throws IllegalArgumentException, NoSuchVariableException; |
| |
| /** |
| * This method does in-place expansion of any variables. However, the expansion is not done twice, that is, |
| * a variable containing text $variable will not be expanded. |
| * <P> |
| * The variables should be in the same format ({$variablename} as in the web pages. |
| * |
| * @param context The WikiContext of the current page. |
| * @param source The source string. |
| * @return The source string with variables expanded. |
| */ |
| String expandVariables( Context context, String source ); |
| |
| /** |
| * Returns the value of a named variable. See {@link #getValue(Context, String)}. The only difference is that |
| * this method does not throw an exception, but it returns the given default value instead. |
| * |
| * @param context WikiContext |
| * @param varName The name of the variable |
| * @param defValue A default value. |
| * @return The variable value, or if not found, the default value. |
| */ |
| String getValue( Context context, String varName, String defValue ); |
| |
| /** |
| * Shortcut to getValue(). However, this method does not throw a NoSuchVariableException, but returns null |
| * in case the variable does not exist. |
| * |
| * @param context WikiContext to look the variable in |
| * @param name Name of the variable to look for |
| * @return Variable value, or null, if there is no such variable. |
| * @since 2.2 on Engine, moved to VariableManager on 2.11.0 |
| */ |
| String getVariable( Context context, String name ); |
| |
| /** |
| * Returns a value of the named variable. The resolving order is |
| * <ol> |
| * <li>Known "constant" name, such as "pagename", etc. This is so |
| * that pages could not override certain constants. |
| * <li>WikiContext local variable. This allows a programmer to |
| * set a parameter which cannot be overridden by user. |
| * <li>HTTP Session |
| * <li>HTTP Request parameters |
| * <li>WikiPage variable. As set by the user with the SET directive. |
| * <li>jspwiki.properties |
| * </ol> |
| * |
| * Use this method only whenever you really need to have a parameter that |
| * can be overridden by anyone using the wiki. |
| * |
| * @param context The WikiContext |
| * @param varName Name of the variable. |
| * |
| * @return The variable value. |
| * |
| * @throws IllegalArgumentException If the name is somehow broken. |
| * @throws NoSuchVariableException If a variable is not known. |
| */ |
| String getValue( Context context, String varName ) throws IllegalArgumentException, NoSuchVariableException; |
| |
| } |