View Javadoc

1   /*
2    * Copyright (c) 2003 Peter Antman, Teknik i Media  <peter.antman@tim.se>
3    *
4    * $Id: CachedStream.java,v 1.1.1.1 2004/05/19 12:07:30 pra Exp $
5    *
6    * This library is free software; you can redistribute it and/or
7    * modify it under the terms of the GNU Lesser General Public
8    * License as published by the Free Software Foundation; either
9    * version 2 of the License, or (at your option) any later version
10   * 
11   * This library is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   * Lesser General Public License for more details.
15   * 
16   * You should have received a copy of the GNU Lesser General Public
17   * License along with this library; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19   */
20  package org.backsource.utils.io;
21  import java.io.InputStream;
22  import java.io.IOException;
23  /***
24   * Helper class to work with cached streams.
25   *
26   * <p>A CachedStream should normally/allways be obtained through the {@link CachedStreamFactory}.</p>
27   *
28   * <p>A cached stream is a stream that is cached in memory or some other place like in a file.They should basically be used when the same stream will be use (emptied) a multitude of times and
29   it is important to do this without a lot of work.</p>
30   <p>Use it when you need to get data from an external source and reuse it.</p>
31   <pre>
32    CachedStreamFactory factory = CachedStreamFactory.newInstance();
33    CachedStream cache = factory.getCachedStream();
34    OutputStream os = cache.getOutputStream();
35    // Let external write to it
36    ftp.get("filename",os);
37    // Get a reusable input stream
38    CachedInputStream is = cache.getInputStream( os );
39   </pre>
40   <p>This is also possible when you get an InputStream.</p>
41   <pre>
42     InputStream is = url.openStream();
43     CachedInputStream cis = cache.getInputStream( is );
44   </pre>
45   <p>The getInputStream know if it gets a CachedInputStream and will return that, so in situations where stuff takes an InputStream which might already be a CachedInput stream, just use getInputStream. The helper method rewind will rewind the stream, if only if the stream is really rewindable: otherwise it will raise an exception.</p>
46   <p>CachedInputStreams are not possible to close through the normal close method because there are a lot of utilities out there that will close your stream for you under the hood. Use {@link CachedInputStream#close(boolean)} to really close the stream.</p>
47   
48   *
49   * @author <a href="mailto:pra@tim.se">Peter Antman</a>
50   * @version $Revision: 1.1.1.1 $
51   */
52  
53  public interface CachedStream {
54  
55     /***
56      * Get a CachedOutputStream.
57      *
58      * <p>The typical usecase for this is to later use it to get
59      * a CachedInputStream from it.
60      */
61     public CachedOutputStream getOutputStream() throws IOException;
62  
63     /***
64      * Get a rewindable input stream from the given CacheOutputStream.
65      * @throws IOException if the CachedOutputStream is not of the correct type (not from the same cache) or if an underlying IOException happens.
66      */
67     public CachedInputStream getInputStream(CachedOutputStream cout)throws IOException;
68     
69     /***
70      * Get a rewindable inputstream from the given input stream, if the stream is a Rewindable input stream, it is just returned.
71      */
72     public CachedInputStream getInputStream(InputStream is) throws IOException;
73  
74     /***
75      * Rewind this stream if it is rewindable, otherwise throw an IOException.
76      */
77     public void rewind(InputStream is) throws IOException;
78  
79     /***
80      * Set a CacheStream specific property.
81      */
82     public void setProperty(String name, String value);
83  
84     /***
85      * Chech if property is set.
86      */
87     public String getProperty(String name);
88     
89  }// CachedStream