XScriptManager


1   /*
2    * Copyright 1999-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.components.xscript;
17  
18  import java.util.Map  ;
19  
20  /**
21   * <code>XScriptManager</code> is the public interface used to
22   * interact with the XScript component, which implements the
23   * supporting code for the XScript language.
24   *
25   * @author <a HREF="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
26   * @author <a HREF="mailto:vgritsenko@apache.org">Vadim Gritsenko</a>
27   * @version CVS $Id: XScriptManager.java 30932 2004-07-29 17:35:38Z vgritsenko $
28   * @since August  4, 2001
29   */
30  public interface XScriptManager
31  {
32      String   ROLE = "org.apache.cocoon.components.xscript.XScriptManager";
33  
34      String   XSCRIPT_NS = "http://apache.org/xsp/xscript/1.0";
35  
36      /**
37       * The variable's global scope. Each Cocoon instance has exactly one
38       * global scope for variables.
39       */
40      int GLOBAL_SCOPE = 1;
41  
42      /**
43       * The session scope. This scope is specific to a particular
44       * activation of an XSP page, which is usually identified by the
45       * session id of the user that sent the HTTP request. From XScript's
46       * point of view however, the session identifier is not interpreted
47       * in any way, so a client can define its own notion of "session".
48       */
49      int SESSION_SCOPE = 2;
50  
51      /**
52       * The page scope. This is scope very specific to an XSP page, and
53       * defines variables visible only within the context of that
54       * page. No other XSP page can access these variables, unless it
55       * knows the identifier used by that page to store its
56       * variables. This identifier is not necessarily the URL or full
57       * path of that page; it is up to the page to define it.
58       */
59      int PAGE_SCOPE = 3;
60  
61      /**
62       * The request scope. This is scope specific to request, and
63       * defines variables visible only within the context of that
64       * request. Once request is processed, these variables are lost.
65       */
66      int REQUEST_SCOPE = 5;
67  
68      /**
69       * Search for a variable in all the accessible scopes. The variable
70       * is first searched in the current session scope. If no variable is
71       * found here, the current page scope is searched next. If nothing
72       * is found either, the global scope is searched.
73       */
74      int ALL_SCOPES = 4;
75  
76      /**
77       * Obtains the object value of the
78       * <code>name</code> variable in <code>scope</code>. The
79       * <code>context</code> parameter is interpreted differently
80       * depending on the value of <code>scope</code>, as follows:
81       *
82       * <ul>
83       *
84       *  <li>if <code>scope</code> is <code>{@link #GLOBAL_SCOPE}</code>, the
85       *  value of <code>context is ignored.
86       *
87       *  <li>if <code>scope</code> is <code>{@link
88       *  #SESSION_SCOPE}</code>, the value of <code>context</code> is
89       *  interpreted as the session identifier.
90       *
91       *  <li>if <code>scope</code> is <code>{@link #PAGE_SCOPE}</code>, the value
92       *  of <code>context</code> is interpreted as an identifier of the
93       *  page. This could be the URL of the page or the path of the file
94       *  name in the file system.
95       *
96       * </ul>
97       *
98       * @param objectModel an instance of Cocoon object model used to obtain context
99       * @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,
104                       Map   objectModel,
105                       String   name,
106                       int scope) throws IllegalArgumentException  ;
107 
108     /**
109      * Search for the first occurence of the variable
110      * <code>name</code>.
111      *
112      * <p>The search happens first in the session scope
113      * identified by <code>sessionContext</code>. If no variable is
114      * found here, the search continues in the page scope identified by
115      * <code>pageContext</code>. If no variable is found here, it's
116      * finally searched in the global scope.
117      *
118      * <p>The <code>XScriptObject</code> value of the variable is
119      * returned if a variable is found in one of the scopes, otherwise
120      * an exception is thrown.
121      *
122      * @param objectModel an instance of Cocoon object model used to obtain context
123      * @param name a <code>String</code> value
124      * @return a <code>XScriptObject</code> value
125      * @exception IllegalArgumentException if an error occurs
126      */
127     XScriptObject getFirst(XScriptVariableScope pageScope,
128                            Map   objectModel,
129                            String   name) throws IllegalArgumentException  ;
130 
131     /**
132      * Defines or overwrites the value of variable
133      * <code>name</code> in <code>scope</code>. The <code>context</code>
134      * argument is interpreted as described in
135      * {@link #get(XScriptVariableScope, Map, String, int)}.
136      *
137      * @param objectModel an instance of Cocoon object model used to obtain context
138      * @param name a <code>String</code> value
139      * @param value a <code>XScriptObject</code> value
140      * @param scope an <code>int</code> value
141      */
142     void put(XScriptVariableScope pageScope,
143              Map   objectModel,
144              String   name,
145              XScriptObject value,
146              int scope) throws IllegalArgumentException  ;
147 
148     /**
149      * Removes a variable previously declared in <code>scope</code>
150      * within <code>context</code>. Such a variable could be declared
151      * using the {@link #put(XScriptVariableScope, Map, String, XScriptObject, int)}
152      * method.
153      *
154      * @param objectModel an instance of Cocoon object model used to obtain context
155      * @param name a <code>String</code> value
156      * @param scope an <code>int</code> value
157      * @exception IllegalArgumentException if an error occurs
158      */
159     XScriptObject remove(XScriptVariableScope pageScope,
160                          Map   objectModel,
161                          String   name,
162                          int scope) throws IllegalArgumentException  ;
163 
164     /**
165      * Remove the first appearance of <code>name</code> in the all the
166      * currently accessible scopes. The search happens as described in
167      * {@link #getFirst(XScriptVariableScope, Map, String)}.
168      *
169      * @param objectModel an instance of Cocoon object model used to obtain context
170      * @param name a <code>String</code> value
171      * @exception IllegalArgumentException if an error occurs
172      */
173     XScriptObject removeFirst(XScriptVariableScope pageScope,
174                               Map   objectModel,
175                               String   name) throws IllegalArgumentException  ;
176 }
177
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags