View Javadoc

1   /* 
2    * Copyright 2002-2004 The Apache Software Foundation
3    * Licensed  under the  Apache License,  Version 2.0  (the "License");
4    * you may not use  this file  except in  compliance with the License.
5    * You may obtain a copy of the License at 
6    * 
7    *   http://www.apache.org/licenses/LICENSE-2.0
8    * 
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed  under the  License is distributed on an "AS IS" BASIS,
11   * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
12   * implied.
13   * 
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.struts.flow.core.source;
18  
19  import java.io.IOException;
20  import java.io.OutputStream;
21  
22  /***
23   * A {@link Source} that can be written to.
24   * <p>
25   * As far a possible, implementations should provide a kind of transaction or
26   * buffering of data written to the source. This is especially important in
27   * stream-based systems such as Cocoon where an error that occurs during the
28   * processing should lead to cancelling data written to the source.
29   * <p>
30   * This is the role of the {@link #canCancel(OutputStream)} and
31   * {@link #cancel(OutputStream)} methods.
32   *
33   * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
34   * @version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:26 $
35   */
36  public interface ModifiableSource
37      extends Source
38  {
39      /***
40       * Return an {@link OutputStream} to write to.
41       *
42       * The returned stream must be closed or cancelled by the calling code.
43       */
44      OutputStream getOutputStream() throws IOException;
45      
46      /***
47       * Delete the source 
48       */
49      void delete() throws SourceException;
50  
51      /***
52       * Can the data sent to an <code>OutputStream</code> returned by
53       * {@link #getOutputStream()} be cancelled ?
54       *
55       * @return true if the stream can be cancelled
56       */
57      boolean canCancel(OutputStream stream);
58  
59      /***
60       * Cancel the data sent to an <code>OutputStream</code> returned by
61       * {@link #getOutputStream()}.  Cancelling the stream will also close it.
62       *
63       * <p>After cancelling, the stream should no longer be used.</p>
64       */
65      void cancel(OutputStream stream) throws IOException;
66      
67  }