KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > environment > WriteableSource


1 /*
2  * Copyright 2001,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
17 package org.apache.cocoon.environment;
18
19 import java.io.IOException JavaDoc;
20 import java.io.OutputStream JavaDoc;
21
22 import org.apache.cocoon.ProcessingException;
23
24 import org.xml.sax.ContentHandler JavaDoc;
25 import org.xml.sax.SAXException JavaDoc;
26
27 /**
28  * A {@link Source} that can be written to. It provides two methods that
29  * allow for SAX-based and byte-based output.
30  * <p>
31  * Callers will use the most appropriate method for their use and
32  * it's up to the implementation to handle both sources. For example,
33  * an XML-based implementation can use a parser to convert bytes written
34  * to the <code>OutputStream</code> to SAX events, and a byte-based
35  * implementation (such as file), can use a serializer to convert
36  * SAX events to a byte stream.
37  *
38  * @deprecated Use the {@link org.apache.excalibur.source.ModifiableSource} interface instead
39  * @author <a HREF="mailto:sylvain@apache.org">Sylvain Wallez</a>
40  * @version CVS $Id: WriteableSource.java 30932 2004-07-29 17:35:38Z vgritsenko $
41  */
42 public interface WriteableSource extends ModifiableSource {
43
44     /**
45      * Does this source actually exist ?
46      *
47      * @return true if the resource exists.
48      */
49     boolean exists();
50
51     /**
52      * Get a <code>ContentHandler</code> where an XML document can
53      * be written using SAX events.
54      * <p>
55      * Care should be taken that the returned handler can actually
56      * be a {@link org.apache.cocoon.xml.XMLConsumer} supporting also
57      * lexical events such as comments.
58      *
59      * @return a handler for SAX events
60      */
61     ContentHandler JavaDoc getContentHandler() throws SAXException JavaDoc, ProcessingException;
62
63     /**
64      * Get an <code>InputStream</code> where raw bytes can be written to.
65      * The signification of these bytes is implementation-dependent and
66      * is not restricted to a serialized XML document.
67      *
68      * @return a stream to write to
69      */
70     OutputStream JavaDoc getOutputStream() throws IOException JavaDoc, ProcessingException;
71
72     /**
73      * Can the data sent to a <code>ContentHandler</code> returned by
74      * {@link #getContentHandler()} be cancelled ?
75      *
76      * @return true if the handler can be cancelled
77      */
78     boolean canCancel(ContentHandler JavaDoc handler);
79
80     /**
81      * Can the data sent to an <code>OutputStream</code> returned by
82      * {@link #getOutputStream()} be cancelled ?
83      *
84      * @return true if the stream can be cancelled
85      */
86     boolean canCancel(OutputStream JavaDoc stream);
87
88     /**
89      * Cancel the data sent to a <code>ContentHandler</code> returned by
90      * {@link #getContentHandler()}.
91      * <p>
92      * After cancel, the handler should no more be used.
93      */
94     void cancel(ContentHandler JavaDoc handler) throws Exception JavaDoc;
95
96     /**
97      * Cancel the data sent to an <code>OutputStream</code> returned by
98      * {@link #getOutputStream()}.
99      * <p>
100      * After cancel, the stream should no more be used.
101      */
102     void cancel(OutputStream JavaDoc stream) throws Exception JavaDoc;
103 }
104
Popular Tags