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: */
017: package org.apache.cocoon.components.xscript;
018:
019: import java.util.Map;
020:
021: /**
022: * <code>XScriptManager</code> is the public interface used to
023: * interact with the XScript component, which implements the
024: * supporting code for the XScript language.
025: *
026: * @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
027: * @author <a href="mailto:vgritsenko@apache.org">Vadim Gritsenko</a>
028: * @version CVS $Id: XScriptManager.java 433543 2006-08-22 06:22:54Z crossley $
029: * @since August 4, 2001
030: */
031: public interface XScriptManager {
032: String ROLE = "org.apache.cocoon.components.xscript.XScriptManager";
033:
034: String XSCRIPT_NS = "http://apache.org/xsp/xscript/1.0";
035:
036: /**
037: * The variable's global scope. Each Cocoon instance has exactly one
038: * global scope for variables.
039: */
040: int GLOBAL_SCOPE = 1;
041:
042: /**
043: * The session scope. This scope is specific to a particular
044: * activation of an XSP page, which is usually identified by the
045: * session id of the user that sent the HTTP request. From XScript's
046: * point of view however, the session identifier is not interpreted
047: * in any way, so a client can define its own notion of "session".
048: */
049: int SESSION_SCOPE = 2;
050:
051: /**
052: * The page scope. This is scope very specific to an XSP page, and
053: * defines variables visible only within the context of that
054: * page. No other XSP page can access these variables, unless it
055: * knows the identifier used by that page to store its
056: * variables. This identifier is not necessarily the URL or full
057: * path of that page; it is up to the page to define it.
058: */
059: int PAGE_SCOPE = 3;
060:
061: /**
062: * The request scope. This is scope specific to request, and
063: * defines variables visible only within the context of that
064: * request. Once request is processed, these variables are lost.
065: */
066: int REQUEST_SCOPE = 5;
067:
068: /**
069: * Search for a variable in all the accessible scopes. The variable
070: * is first searched in the current session scope. If no variable is
071: * found here, the current page scope is searched next. If nothing
072: * is found either, the global scope is searched.
073: */
074: int ALL_SCOPES = 4;
075:
076: /**
077: * Obtains the object value of the
078: * <code>name</code> variable in <code>scope</code>. The
079: * <code>context</code> parameter is interpreted differently
080: * depending on the value of <code>scope</code>, as follows:
081: *
082: * <ul>
083: *
084: * <li>if <code>scope</code> is <code>{@link #GLOBAL_SCOPE}</code>, the
085: * value of <code>context is ignored.
086: *
087: * <li>if <code>scope</code> is <code>{@link
088: * #SESSION_SCOPE}</code>, the value of <code>context</code> is
089: * interpreted as the session identifier.
090: *
091: * <li>if <code>scope</code> is <code>{@link #PAGE_SCOPE}</code>, the value
092: * of <code>context</code> is interpreted as an identifier of the
093: * page. This could be the URL of the page or the path of the file
094: * name in the file system.
095: *
096: * </ul>
097: *
098: * @param objectModel an instance of Cocoon object model used to obtain context
099: * @param name a <code>String</code> value
100: * @param scope an <code>int</code> value
101: * @return a <code>{@link XScriptObject}</code> value
102: */
103: XScriptObject get(XScriptVariableScope pageScope, Map objectModel,
104: String name, int scope) throws IllegalArgumentException;
105:
106: /**
107: * Search for the first occurence of the variable
108: * <code>name</code>.
109: *
110: * <p>The search happens first in the session scope
111: * identified by <code>sessionContext</code>. If no variable is
112: * found here, the search continues in the page scope identified by
113: * <code>pageContext</code>. If no variable is found here, it's
114: * finally searched in the global scope.
115: *
116: * <p>The <code>XScriptObject</code> value of the variable is
117: * returned if a variable is found in one of the scopes, otherwise
118: * an exception is thrown.
119: *
120: * @param objectModel an instance of Cocoon object model used to obtain context
121: * @param name a <code>String</code> value
122: * @return a <code>XScriptObject</code> value
123: * @exception IllegalArgumentException if an error occurs
124: */
125: XScriptObject getFirst(XScriptVariableScope pageScope,
126: Map objectModel, String name)
127: throws IllegalArgumentException;
128:
129: /**
130: * Defines or overwrites the value of variable
131: * <code>name</code> in <code>scope</code>. The <code>context</code>
132: * argument is interpreted as described in
133: * {@link #get(XScriptVariableScope, Map, String, int)}.
134: *
135: * @param objectModel an instance of Cocoon object model used to obtain context
136: * @param name a <code>String</code> value
137: * @param value a <code>XScriptObject</code> value
138: * @param scope an <code>int</code> value
139: */
140: void put(XScriptVariableScope pageScope, Map objectModel,
141: String name, XScriptObject value, int scope)
142: throws IllegalArgumentException;
143:
144: /**
145: * Removes a variable previously declared in <code>scope</code>
146: * within <code>context</code>. Such a variable could be declared
147: * using the {@link #put(XScriptVariableScope, Map, String, XScriptObject, int)}
148: * method.
149: *
150: * @param objectModel an instance of Cocoon object model used to obtain context
151: * @param name a <code>String</code> value
152: * @param scope an <code>int</code> value
153: * @exception IllegalArgumentException if an error occurs
154: */
155: XScriptObject remove(XScriptVariableScope pageScope,
156: Map objectModel, String name, int scope)
157: throws IllegalArgumentException;
158:
159: /**
160: * Remove the first appearance of <code>name</code> in the all the
161: * currently accessible scopes. The search happens as described in
162: * {@link #getFirst(XScriptVariableScope, Map, String)}.
163: *
164: * @param objectModel an instance of Cocoon object model used to obtain context
165: * @param name a <code>String</code> value
166: * @exception IllegalArgumentException if an error occurs
167: */
168: XScriptObject removeFirst(XScriptVariableScope pageScope,
169: Map objectModel, String name)
170: throws IllegalArgumentException;
171: }
|