KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > webapps > session > context > SessionContext


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.webapps.session.context;
17
18 import java.io.IOException JavaDoc;
19 import java.io.Serializable JavaDoc;
20
21 import org.w3c.dom.DocumentFragment JavaDoc;
22 import org.w3c.dom.Node JavaDoc;
23 import org.w3c.dom.NodeList JavaDoc;
24
25 import org.xml.sax.SAXException JavaDoc;
26 import org.xml.sax.ContentHandler JavaDoc;
27 import org.xml.sax.ext.LexicalHandler JavaDoc;
28 import org.apache.excalibur.source.SourceParameters;
29 import org.apache.cocoon.ProcessingException;
30
31 /**
32  * Interface for a SessionContext.
33  * This interface describes a SessionContext. The SessionContext is a data
34  * container containing structured XML which can be retrieved/set by the
35  * session transformer.
36  * This interface does not specify how the session context stores the data.
37  * This is left to the implementation itself, but actually this interface
38  * is build in the DOM model.
39  * As this context is used in a web context, all methods must be synchronized.
40  *
41  * @author <a HREF="mailto:cziegeler@s-und-n.de">Carsten Ziegeler</a>
42  * @version CVS $Id: SessionContext.java 30932 2004-07-29 17:35:38Z vgritsenko $
43 */
44 public interface SessionContext
45 extends Serializable JavaDoc {
46
47     /** Set the name of the context.
48      * This method must be invoked in the init phase.
49      * In addition a load and a save resource can be provided.
50      */
51     void setup(String JavaDoc value, String JavaDoc loadResource, String JavaDoc saveResource);
52
53     /**
54      * Get the name of the context
55      */
56     String JavaDoc getName();
57
58     /**
59      * Get a document fragment.
60      * If the node specified by the path exist, its content is returned
61      * as a DocumentFragment.
62      * If the node does not exists, <CODE>null</CODE> is returned.
63      */
64     DocumentFragment JavaDoc getXML(String JavaDoc path)
65     throws ProcessingException ;
66
67     /**
68      * Set a document fragment at the given path.
69      * The implementation of this method is context specific.
70      * Usually all children of the node specified by the path are removed
71      * and the children of the fragment are inserted as new children.
72      * If the path is not existent it is created.
73      */
74     void setXML(String JavaDoc path, DocumentFragment JavaDoc fragment)
75     throws ProcessingException;
76
77     /**
78      * Append a document fragment at the given path.
79      * The implementation of this method is context specific.
80      * Usually the children of the fragment are appended as new children of the
81      * node specified by the path.
82      * If the path is not existent it is created and this method should work
83      * in the same way as setXML.
84      */
85     void appendXML(String JavaDoc path, DocumentFragment JavaDoc fragment)
86     throws ProcessingException;
87
88     /**
89      * Remove some content from the context.
90      * The implementation of this method is context specific.
91      * Usually this method should remove all children of the node specified
92      * by the path.
93      */
94     void removeXML(String JavaDoc path)
95     throws ProcessingException;
96
97     /**
98      * Set a context attribute.
99      * Attributes over a means to store any data (object) in a session
100      * context. If <CODE>value</CODE> is <CODE>null</CODE> the attribute is
101      * removed. If already an attribute exists with the same key, the value
102      * is overwritten with the new one.
103      */
104     void setAttribute(String JavaDoc key, Object JavaDoc value)
105     throws ProcessingException;
106
107     /**
108      * Get the value of a context attribute.
109      * If the attribute is not available return <CODE>null</CODE>.
110      */
111     Object JavaDoc getAttribute(String JavaDoc key)
112     throws ProcessingException;
113
114     /**
115      * Get the value of a context attribute.
116      * If the attribute is not available the return the
117      * <CODE>defaultObject</CODE>.
118      */
119     Object JavaDoc getAttribute(String JavaDoc key, Object JavaDoc defaultObject)
120     throws ProcessingException;
121
122     /**
123      * Get a copy of the first node specified by the path.
124      * If the node does not exist, <CODE>null</CODE> is returned.
125      */
126     Node JavaDoc getSingleNode(String JavaDoc path)
127     throws ProcessingException;
128
129     /**
130      * Get a copy of all nodes specified by the path.
131      */
132     NodeList JavaDoc getNodeList(String JavaDoc path)
133     throws ProcessingException;
134
135     /**
136      * Set the value of a node. The node is copied before insertion.
137      */
138     void setNode(String JavaDoc path, Node JavaDoc node)
139     throws ProcessingException;
140
141     /**
142      * Get the value of this node.
143      * This is similiar to the xsl:value-of function.
144      * If the node does not exist, <code>null</code> is returned.
145      */
146     String JavaDoc getValueOfNode(String JavaDoc path)
147     throws ProcessingException;
148
149     /**
150      * Set the value of a node.
151      * All children of the node are removed beforehand and one single text
152      * node with the given value is appended to the node.
153      */
154     void setValueOfNode(String JavaDoc path, String JavaDoc value)
155     throws ProcessingException;
156
157     /**
158      * Stream the XML directly to the handler.
159      * This streams the contents of getXML() to the given handler without
160      * creating a DocumentFragment containing a copy of the data.
161      * If no data is available (if the path does not exist) <code>false</code> is
162      * returned, otherwise <code>true</code>.
163      */
164     boolean streamXML(String JavaDoc path,
165                       ContentHandler JavaDoc contentHandler,
166                       LexicalHandler JavaDoc lexicalHandler)
167     throws SAXException JavaDoc, ProcessingException;
168
169     /**
170      * Try to load XML into the context.
171      * If the context does not provide the ability of loading,
172      * an exception is thrown.
173      */
174     void loadXML(String JavaDoc path,
175                  SourceParameters parameters)
176     throws SAXException JavaDoc, ProcessingException, IOException JavaDoc;
177
178     /**
179      * Try to save XML from the context.
180      * If the context does not provide the ability of saving,
181      * an exception is thrown.
182      */
183     void saveXML(String JavaDoc path,
184                  SourceParameters parameters)
185     throws SAXException JavaDoc, ProcessingException, IOException JavaDoc;
186 }
187
Popular Tags