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:
018: package org.apache.cocoon.environment;
019:
020: import java.io.IOException;
021: import java.io.OutputStream;
022:
023: import org.apache.cocoon.ProcessingException;
024:
025: import org.xml.sax.ContentHandler;
026: import org.xml.sax.SAXException;
027:
028: /**
029: * A {@link Source} that can be written to. It provides two methods that
030: * allow for SAX-based and byte-based output.
031: * <p>
032: * Callers will use the most appropriate method for their use and
033: * it's up to the implementation to handle both sources. For example,
034: * an XML-based implementation can use a parser to convert bytes written
035: * to the <code>OutputStream</code> to SAX events, and a byte-based
036: * implementation (such as file), can use a serializer to convert
037: * SAX events to a byte stream.
038: *
039: * @deprecated Use the {@link org.apache.excalibur.source.ModifiableSource} interface instead
040: * @author <a href="mailto:sylvain@apache.org">Sylvain Wallez</a>
041: * @version CVS $Id: WriteableSource.java 433543 2006-08-22 06:22:54Z crossley $
042: */
043: public interface WriteableSource extends ModifiableSource {
044:
045: /**
046: * Does this source actually exist ?
047: *
048: * @return true if the resource exists.
049: */
050: boolean exists();
051:
052: /**
053: * Get a <code>ContentHandler</code> where an XML document can
054: * be written using SAX events.
055: * <p>
056: * Care should be taken that the returned handler can actually
057: * be a {@link org.apache.cocoon.xml.XMLConsumer} supporting also
058: * lexical events such as comments.
059: *
060: * @return a handler for SAX events
061: */
062: ContentHandler getContentHandler() throws SAXException,
063: ProcessingException;
064:
065: /**
066: * Get an <code>InputStream</code> where raw bytes can be written to.
067: * The signification of these bytes is implementation-dependent and
068: * is not restricted to a serialized XML document.
069: *
070: * @return a stream to write to
071: */
072: OutputStream getOutputStream() throws IOException,
073: ProcessingException;
074:
075: /**
076: * Can the data sent to a <code>ContentHandler</code> returned by
077: * {@link #getContentHandler()} be cancelled ?
078: *
079: * @return true if the handler can be cancelled
080: */
081: boolean canCancel(ContentHandler handler);
082:
083: /**
084: * Can the data sent to an <code>OutputStream</code> returned by
085: * {@link #getOutputStream()} be cancelled ?
086: *
087: * @return true if the stream can be cancelled
088: */
089: boolean canCancel(OutputStream stream);
090:
091: /**
092: * Cancel the data sent to a <code>ContentHandler</code> returned by
093: * {@link #getContentHandler()}.
094: * <p>
095: * After cancel, the handler should no more be used.
096: */
097: void cancel(ContentHandler handler) throws Exception;
098:
099: /**
100: * Cancel the data sent to an <code>OutputStream</code> returned by
101: * {@link #getOutputStream()}.
102: * <p>
103: * After cancel, the stream should no more be used.
104: */
105: void cancel(OutputStream stream) throws Exception;
106: }
|