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; 20 import java.io.InputStream; 21 import java.io.OutputStream; 22 import java.nio.channels.FileChannel; 23 import java.nio.channels.ReadableByteChannel; 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 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 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 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 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 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 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 getContentString(int length) throws ContentIOException; 182 } 183