    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.variables;
    020
    021import org.apache.wiki.api.core.Context;
    022import org.apache.wiki.api.exceptions.NoSuchVariableException;
    023
    024/**
    025 *  Manages variables.  Variables are case-insensitive.  A list of all available variables is on a Wiki page called "WikiVariables".
    026 *
    027 *  @since 1.9.20.
    028 */
    029public interface VariableManager {
    030
    031    // FIXME: These are probably obsolete.
    032    String VAR_ERROR = "error";
    033    String VAR_MSG   = "msg";
    034
    035    /** If this variable is set to false, all filters are disabled when translating. */
    036    String VAR_RUNFILTERS   = "jspwiki.runFilters";
    037
    038    /**
    039     *  Parses the link and finds a value.  This is essentially used once
    040     *  {@link org.apache.wiki.parser.LinkParsingOperations#isVariableLink(String) LinkParsingOperations#isVariableLink(String)}
    041     *  has found that the link text actually contains a variable.  For example, you could pass in "{$username}" and get back
    042     *  "JanneJalkanen".
    043     *
    044     *  @param  context The WikiContext
    045     *  @param  link    The link text containing the variable name.
    046     *  @return The variable value.
    047     *  @throws IllegalArgumentException If the format is not valid (does not start with "{$", is zero length, etc.)
    048     *  @throws NoSuchVariableException If a variable is not known.
    049     */
    050    String parseAndGetValue( Context context, String link ) throws IllegalArgumentException, NoSuchVariableException;
    051
    052    /**
    053     *  This method does in-place expansion of any variables.  However, the expansion is not done twice, that is,
    054     *  a variable containing text $variable will not be expanded.
    055     *  <P>
    056     *  The variables should be in the same format ({$variablename} as in the web pages.
    057     *
    058     *  @param context The WikiContext of the current page.
    059     *  @param source  The source string.
    060     *  @return The source string with variables expanded.
    061     */
    062    String expandVariables( Context context, String source );
    063
    064    /**
    065     *  Returns the value of a named variable.  See {@link #getValue(Context, String)}. The only difference is that
    066     *  this method does not throw an exception, but it returns the given default value instead.
    067     *
    068     *  @param context WikiContext
    069     *  @param varName The name of the variable
    070     *  @param defValue A default value.
    071     *  @return The variable value, or if not found, the default value.
    072     */
    073    String getValue( Context context, String varName, String defValue );
    074
    075    /**
    076     *  Shortcut to getValue(). However, this method does not throw a NoSuchVariableException, but returns null
    077     *  in case the variable does not exist.
    078     *
    079     *  @param context WikiContext to look the variable in
    080     *  @param name Name of the variable to look for
    081     *  @return Variable value, or null, if there is no such variable.
    082     *  @since 2.2 on Engine, moved to VariableManager on 2.11.0
    083     */
    084    String getVariable( Context context, String name );
    085
    086    /**
    087     *  Returns a value of the named variable.  The resolving order is
    088     *  <ol>
    089     *    <li>Known "constant" name, such as "pagename", etc.  This is so
    090     *        that pages could not override certain constants.
    091     *    <li>WikiContext local variable.  This allows a programmer to
    092     *        set a parameter which cannot be overridden by user.
    093     *    <li>HTTP Session
    094     *    <li>HTTP Request parameters
    095     *    <li>WikiPage variable.  As set by the user with the SET directive.
    096     *    <li>jspwiki.properties
    097     *  </ol>
    098     *
    099     *  Use this method only whenever you really need to have a parameter that
    100     *  can be overridden by anyone using the wiki.
    101     *
    102     *  @param context The WikiContext
    103     *  @param varName Name of the variable.
    104     *
    105     *  @return The variable value.
    106     *
    107     *  @throws IllegalArgumentException If the name is somehow broken.
    108     *  @throws NoSuchVariableException If a variable is not known.
    109     */
    110    String getValue( Context context, String varName ) throws IllegalArgumentException, NoSuchVariableException;
    111
    112}