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.webapps.session.context;
018:
019: import java.io.IOException;
020: import java.io.Serializable;
021:
022: import org.w3c.dom.DocumentFragment;
023: import org.w3c.dom.Node;
024: import org.w3c.dom.NodeList;
025:
026: import org.xml.sax.SAXException;
027: import org.xml.sax.ContentHandler;
028: import org.xml.sax.ext.LexicalHandler;
029: import org.apache.excalibur.source.SourceParameters;
030: import org.apache.cocoon.ProcessingException;
031:
032: /**
033: * Interface for a SessionContext.
034: * This interface describes a SessionContext. The SessionContext is a data
035: * container containing structured XML which can be retrieved/set by the
036: * session transformer.
037: * This interface does not specify how the session context stores the data.
038: * This is left to the implementation itself, but actually this interface
039: * is build in the DOM model.
040: * As this context is used in a web context, all methods must be synchronized.
041: *
042: * @author <a href="mailto:cziegeler@s-und-n.de">Carsten Ziegeler</a>
043: * @deprecated This block is deprecated and will be removed in future versions.
044: * @version CVS $Id: SessionContext.java 433543 2006-08-22 06:22:54Z crossley $
045: */
046: public interface SessionContext extends Serializable {
047:
048: /** Set the name of the context.
049: * This method must be invoked in the init phase.
050: * In addition a load and a save resource can be provided.
051: */
052: void setup(String value, String loadResource, String saveResource);
053:
054: /**
055: * Get the name of the context
056: */
057: String getName();
058:
059: /**
060: * Get a document fragment.
061: * If the node specified by the path exist, its content is returned
062: * as a DocumentFragment.
063: * If the node does not exists, <CODE>null</CODE> is returned.
064: */
065: DocumentFragment getXML(String path) throws ProcessingException;
066:
067: /**
068: * Set a document fragment at the given path.
069: * The implementation of this method is context specific.
070: * Usually all children of the node specified by the path are removed
071: * and the children of the fragment are inserted as new children.
072: * If the path is not existent it is created.
073: */
074: void setXML(String path, DocumentFragment fragment)
075: throws ProcessingException;
076:
077: /**
078: * Append a document fragment at the given path.
079: * The implementation of this method is context specific.
080: * Usually the children of the fragment are appended as new children of the
081: * node specified by the path.
082: * If the path is not existent it is created and this method should work
083: * in the same way as setXML.
084: */
085: void appendXML(String path, DocumentFragment fragment)
086: throws ProcessingException;
087:
088: /**
089: * Remove some content from the context.
090: * The implementation of this method is context specific.
091: * Usually this method should remove all children of the node specified
092: * by the path.
093: */
094: void removeXML(String path) throws ProcessingException;
095:
096: /**
097: * Set a context attribute.
098: * Attributes over a means to store any data (object) in a session
099: * context. If <CODE>value</CODE> is <CODE>null</CODE> the attribute is
100: * removed. If already an attribute exists with the same key, the value
101: * is overwritten with the new one.
102: */
103: void setAttribute(String key, Object value)
104: throws ProcessingException;
105:
106: /**
107: * Get the value of a context attribute.
108: * If the attribute is not available return <CODE>null</CODE>.
109: */
110: Object getAttribute(String key) throws ProcessingException;
111:
112: /**
113: * Get the value of a context attribute.
114: * If the attribute is not available the return the
115: * <CODE>defaultObject</CODE>.
116: */
117: Object getAttribute(String key, Object defaultObject)
118: throws ProcessingException;
119:
120: /**
121: * Get a copy of the first node specified by the path.
122: * If the node does not exist, <CODE>null</CODE> is returned.
123: */
124: Node getSingleNode(String path) throws ProcessingException;
125:
126: /**
127: * Get a copy of all nodes specified by the path.
128: */
129: NodeList getNodeList(String path) throws ProcessingException;
130:
131: /**
132: * Set the value of a node. The node is copied before insertion.
133: */
134: void setNode(String path, Node node) throws ProcessingException;
135:
136: /**
137: * Get the value of this node.
138: * This is similiar to the xsl:value-of function.
139: * If the node does not exist, <code>null</code> is returned.
140: */
141: String getValueOfNode(String path) throws ProcessingException;
142:
143: /**
144: * Set the value of a node.
145: * All children of the node are removed beforehand and one single text
146: * node with the given value is appended to the node.
147: */
148: void setValueOfNode(String path, String value)
149: throws ProcessingException;
150:
151: /**
152: * Stream the XML directly to the handler.
153: * This streams the contents of getXML() to the given handler without
154: * creating a DocumentFragment containing a copy of the data.
155: * If no data is available (if the path does not exist) <code>false</code> is
156: * returned, otherwise <code>true</code>.
157: */
158: boolean streamXML(String path, ContentHandler contentHandler,
159: LexicalHandler lexicalHandler) throws SAXException,
160: ProcessingException;
161:
162: /**
163: * Try to load XML into the context.
164: * If the context does not provide the ability of loading,
165: * an exception is thrown.
166: */
167: void loadXML(String path, SourceParameters parameters)
168: throws SAXException, ProcessingException, IOException;
169:
170: /**
171: * Try to save XML from the context.
172: * If the context does not provide the ability of saving,
173: * an exception is thrown.
174: */
175: void saveXML(String path, SourceParameters parameters)
176: throws SAXException, ProcessingException, IOException;
177: }
|