KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > alfresco > service > cmr > repository > ContentReader


1 /*
2  * Copyright (C) 2005 Alfresco, Inc.
3  *
4  * Licensed under the Mozilla Public License version 1.1
5  * with a permitted attribution clause. You may obtain a
6  * copy of the License at
7  *
8  * http://www.alfresco.org/legal/license.txt
9  *
10  * Unless required by applicable law or agreed to in writing,
11  * software distributed under the License is distributed on an
12  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13  * either express or implied. See the License for the specific
14  * language governing permissions and limitations under the
15  * License.
16  */
17 package org.alfresco.service.cmr.repository;
18
19 import java.io.File JavaDoc;
20 import java.io.InputStream JavaDoc;
21 import java.io.OutputStream JavaDoc;
22 import java.nio.channels.FileChannel JavaDoc;
23 import java.nio.channels.ReadableByteChannel JavaDoc;
24
25 /**
26  * Represents a handle to read specific content. Content may only be accessed
27  * once per instance.
28  * <p>
29  * Implementations of this interface <b>might</b> be <code>Serializable</code>
30  * but client code could should check suitability before attempting to serialize
31  * it.
32  * <p>
33  * Implementations that are able to provide inter-VM streaming, such as accessing
34  * WebDAV, would be <code>Serializable</code>. An accessor that has to access a
35  * local file on the server could not provide inter-VM streaming unless it specifically
36  * makes remote calls and opens sockets, etc.
37  *
38  * @see org.alfresco.service.cmr.repository.ContentWriter
39  *
40  * @author Derek Hulley
41  */
42 public interface ContentReader extends ContentAccessor
43 {
44     /**
45      * Convenience method to get another reader onto the underlying content.
46      *
47      * @return Returns a reader onto the underlying content
48      * @throws ContentIOException
49      */
50     public ContentReader getReader() throws ContentIOException;
51     
52     /**
53      * Check if the {@link ContentAccessor#getContentUrl() underlying content} is present.
54      *
55      * @return Returns true if there is content at the URL refered to by this reader
56      */
57     public boolean exists();
58     
59     /**
60      * Gets the time of the last modification of the underlying content.
61      *
62      * @return Returns the last modification time using the standard <tt>long</tt>
63      * time, or <code>0L</code> if the content doesn't {@link #exists() exist}.
64      *
65      * @see System#currentTimeMillis()
66      */
67     public long getLastModified();
68
69     /**
70      * Convenience method to find out if this reader has been closed.
71      * Once closed, the content can no longer be read. This method could
72      * be used to wait for a particular read operation to complete, for example.
73      *
74      * @return Return true if the content input stream has been used and closed
75      * otherwise false.
76      */
77     public boolean isClosed();
78     
79     /**
80      * Provides low-level access to the underlying content.
81      * <p>
82      * Once the stream is provided to a client it should remain active
83      * (subject to any timeouts) until closed by the client.
84      *
85      * @return Returns a stream that can be read at will, but must be closed when completed
86      * @throws ContentIOException
87      */
88     public ReadableByteChannel JavaDoc getReadableChannel() throws ContentIOException;
89     
90     /**
91      * Provides read-only, random-access to the underlying content. In general, this method
92      * should be considered more expensive than the sequential-access method,
93      * {@link #getReadableChannel()}.
94      *
95      * @return Returns a random-access channel onto the content
96      * @throws ContentIOException
97      *
98      * @see #getReadableChannel()
99      * @see java.io.RandomAccessFile#getChannel()
100      */
101     public FileChannel JavaDoc getFileChannel() throws ContentIOException;
102
103     /**
104      * Get a stream to read from the underlying channel
105      *
106      * @return Returns an input stream onto the underlying channel
107      * @throws ContentIOException
108      *
109      * @see #getReadableChannel()
110      */
111     public InputStream JavaDoc getContentInputStream() throws ContentIOException;
112
113     /**
114      * Gets content from the repository.
115      * <p>
116      * All resources will be closed automatically.
117      * <p>
118      * Care must be taken that the bytes read from the stream are properly
119      * decoded according to the {@link ContentAccessor#getEncoding() encoding}
120      * property.
121      *
122      * @param os the stream to which to write the content
123      * @throws ContentIOException
124      *
125      * @see #getReadableChannel()
126      */
127     public void getContent(OutputStream JavaDoc os) throws ContentIOException;
128     
129     /**
130      * Gets content from the repository direct to file
131      * <p>
132      * All resources will be closed automatically.
133      *
134      * @param file the file to write the content to - it will be overwritten
135      * @throws ContentIOException
136      *
137      * @see #getContentInputStream()
138      */
139     public void getContent(File JavaDoc file) throws ContentIOException;
140
141     /**
142      * Gets content from the repository direct to <code>String</code>.
143      * <p>
144      * If the {@link ContentAccessor#getEncoding() encoding } is known then it will be used
145      * otherwise the default system <tt>byte[]</tt> to <tt>String</tt> conversion
146      * will be used.
147      * <p>
148      * All resources will be closed automatically.
149      * <p>
150      * <b>WARNING: </b> This should only be used when the size of the content
151      * is known in advance.
152      *
153      * @return Returns a String representation of the content
154      * @throws ContentIOException
155      *
156      * @see #getContentString(int)
157      * @see #getContentInputStream()
158      * @see String#String(byte[])
159      */
160     public String JavaDoc getContentString() throws ContentIOException;
161     
162     /**
163      * Gets content from the repository direct to <code>String</code>, but limiting
164      * the string size to a given number of characters.
165      * <p>
166      * If the {@link ContentAccessor#getEncoding() encoding } is known then it will be used
167      * otherwise the default system <tt>byte[]</tt> to <tt>String</tt> conversion
168      * will be used.
169      * <p>
170      * All resources will be closed automatically.
171      *
172      * @param length the maximum number of characters to retrieve
173      * @return Returns a truncated String representation of the content
174      * @throws ContentIOException
175      * @throws java.lang.IllegalArgumentException if the length is < 0 or > {@link Integer#MAX_VALUE}
176      *
177      * @see #getContentString()
178      * @see #getContentInputStream()
179      * @see String#String(byte[])
180      */
181     public String JavaDoc getContentString(int length) throws ContentIOException;
182 }
183
Popular Tags