RELEASE_2_1_13/src/blocks/xsp/java/org/apache/cocoon/components/xscript/XScriptManager.java

/*
 * 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.cocoon.components.xscript;

import java.util.Map;

/**
 * <code>XScriptManager</code> is the public interface used to
 * interact with the XScript component, which implements the
 * supporting code for the XScript language.
 *
 * @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
 * @author <a href="mailto:vgritsenko@apache.org">Vadim Gritsenko</a>
 * @version CVS $Id$
 * @since August  4, 2001
 */
public interface XScriptManager
{
    String ROLE = "org.apache.cocoon.components.xscript.XScriptManager";

    String XSCRIPT_NS = "http://apache.org/xsp/xscript/1.0";

    /**
     * The variable's global scope. Each Cocoon instance has exactly one
     * global scope for variables.
     */
    int GLOBAL_SCOPE = 1;

    /**
     * The session scope. This scope is specific to a particular
     * activation of an XSP page, which is usually identified by the
     * session id of the user that sent the HTTP request. From XScript's
     * point of view however, the session identifier is not interpreted
     * in any way, so a client can define its own notion of "session".
     */
    int SESSION_SCOPE = 2;

    /**
     * The page scope. This is scope very specific to an XSP page, and
     * defines variables visible only within the context of that
     * page. No other XSP page can access these variables, unless it
     * knows the identifier used by that page to store its
     * variables. This identifier is not necessarily the URL or full
     * path of that page; it is up to the page to define it.
     */
    int PAGE_SCOPE = 3;

    /**
     * The request scope. This is scope specific to request, and
     * defines variables visible only within the context of that
     * request. Once request is processed, these variables are lost.
     */
    int REQUEST_SCOPE = 5;

    /**
     * Search for a variable in all the accessible scopes. The variable
     * is first searched in the current session scope. If no variable is
     * found here, the current page scope is searched next. If nothing
     * is found either, the global scope is searched.
     */
    int ALL_SCOPES = 4;

    /**
     * Obtains the object value of the
     * <code>name</code> variable in <code>scope</code>. The
     * <code>context</code> parameter is interpreted differently
     * depending on the value of <code>scope</code>, as follows:
     *
     * <ul>
     *
     *  <li>if <code>scope</code> is <code>{@link #GLOBAL_SCOPE}</code>, the
     *  value of <code>context is ignored.
     *
     *  <li>if <code>scope</code> is <code>{@link
     *  #SESSION_SCOPE}</code>, the value of <code>context</code> is
     *  interpreted as the session identifier.
     *
     *  <li>if <code>scope</code> is <code>{@link #PAGE_SCOPE}</code>, the value
     *  of <code>context</code> is interpreted as an identifier of the
     *  page. This could be the URL of the page or the path of the file
     *  name in the file system.
     *
     * </ul>
     *
     * @param objectModel an instance of Cocoon object model used to obtain context
     * @param name a <code>String</code> value
     * @param scope an <code>int</code> value
     * @return a <code>{@link XScriptObject}</code> value
     */
    XScriptObject get(XScriptVariableScope pageScope,
                      Map objectModel,
                      String name,
                      int scope) throws IllegalArgumentException;

    /**
     * Search for the first occurence of the variable
     * <code>name</code>.
     *
     * <p>The search happens first in the session scope
     * identified by <code>sessionContext</code>. If no variable is
     * found here, the search continues in the page scope identified by
     * <code>pageContext</code>. If no variable is found here, it's
     * finally searched in the global scope.
     *
     * <p>The <code>XScriptObject</code> value of the variable is
     * returned if a variable is found in one of the scopes, otherwise
     * an exception is thrown.
     *
     * @param objectModel an instance of Cocoon object model used to obtain context
     * @param name a <code>String</code> value
     * @return a <code>XScriptObject</code> value
     * @exception IllegalArgumentException if an error occurs
     */
    XScriptObject getFirst(XScriptVariableScope pageScope,
                           Map objectModel,
                           String name) throws IllegalArgumentException;

    /**
     * Defines or overwrites the value of variable
     * <code>name</code> in <code>scope</code>. The <code>context</code>
     * argument is interpreted as described in
     * {@link #get(XScriptVariableScope, Map, String, int)}.
     *
     * @param objectModel an instance of Cocoon object model used to obtain context
     * @param name a <code>String</code> value
     * @param value a <code>XScriptObject</code> value
     * @param scope an <code>int</code> value
     */
    void put(XScriptVariableScope pageScope,
             Map objectModel,
             String name,
             XScriptObject value,
             int scope) throws IllegalArgumentException;

    /**
     * Removes a variable previously declared in <code>scope</code>
     * within <code>context</code>. Such a variable could be declared
     * using the {@link #put(XScriptVariableScope, Map, String, XScriptObject, int)}
     * method.
     *
     * @param objectModel an instance of Cocoon object model used to obtain context
     * @param name a <code>String</code> value
     * @param scope an <code>int</code> value
     * @exception IllegalArgumentException if an error occurs
     */
    XScriptObject remove(XScriptVariableScope pageScope,
                         Map objectModel,
                         String name,
                         int scope) throws IllegalArgumentException;

    /**
     * Remove the first appearance of <code>name</code> in the all the
     * currently accessible scopes. The search happens as described in
     * {@link #getFirst(XScriptVariableScope, Map, String)}.
     *
     * @param objectModel an instance of Cocoon object model used to obtain context
     * @param name a <code>String</code> value
     * @exception IllegalArgumentException if an error occurs
     */
    XScriptObject removeFirst(XScriptVariableScope pageScope,
                              Map objectModel,
                              String name) throws IllegalArgumentException;
}