KickJava   Java API By Example, From Geeks To Geeks.

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


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.WritableByteChannel JavaDoc;
24
25
26 /**
27  * Represents a handle to write specific content. Content may only be accessed
28  * once per instance.
29  * <p>
30  * Implementations of this interface <b>might</b> be <code>Serializable</code>
31  * but client code could should check suitability before attempting to serialize
32  * it.
33  * <p>
34  * Implementations that are able to provide inter-VM streaming, such as accessing
35  * WebDAV, would be <code>Serializable</code>. An accessor that has to access a
36  * local file on the server could not provide inter-VM streaming unless it specifically
37  * makes remote calls and opens sockets, etc.
38  *
39  * @see org.alfresco.service.cmr.repository.ContentReader
40  *
41  * @author Derek Hulley
42  */
43 public interface ContentWriter extends ContentAccessor
44 {
45     /**
46      * Convenience method to get a reader onto newly written content. This
47      * method will return null if the content has not yet been written by the
48      * writer or if the output stream is still open.
49      *
50      * @return Returns a reader onto the underlying content that this writer
51      * will or has written to
52      * @throws ContentIOException
53      */
54     public ContentReader getReader() throws ContentIOException;
55     
56     /**
57      * Convenience method to find out if this writer has been closed.
58      * Once closed, the content can no longer be written to and it become possible
59      * to get readers onto the written content.
60      *
61      * @return Return true if the content output stream has been used and closed
62      * otherwise false.
63      */
64     public boolean isClosed();
65     
66     /**
67      * Provides low-level access to write to repository content.
68      * <p>
69      * The channel returned to the client should remain open (subject to timeouts)
70      * until closed by the client. All lock detection, read-only access and other
71      * concurrency issues are dealt with during this operation. It remains
72      * possible that implementations will throw exceptions when the channel is closed.
73      * <p>
74      * The stream will notify any listeners according to the listener interface.
75      *
76      * @return Returns a channel with which to write content
77      * @throws ContentIOException
78      */
79     public WritableByteChannel JavaDoc getWritableChannel() throws ContentIOException;
80
81     /**
82      * Provides read-write, random-access to the underlying content. In general, this method
83      * should be considered more expensive than the sequential-access method,
84      * {@link #getWritableChannel()}.
85      * <p>
86      * Underlying implementations use the <code>truncate</code> parameter to determine the
87      * most effective means of providing access to the content.
88      *
89      * @param truncate true to start with zero length content
90      * @return Returns a random-access channel onto the content
91      * @throws ContentIOException
92      *
93      * @see #getWritableChannel()
94      * @see java.io.RandomAccessFile#getChannel()
95      */
96     public FileChannel JavaDoc getFileChannel(boolean truncate) throws ContentIOException;
97
98     /**
99      * Get a stream to write to the underlying channel.
100      *
101      * @return Returns an output stream onto the underlying channel
102      * @throws ContentIOException
103      *
104      * @see #getWritableChannel()
105      */
106     public OutputStream JavaDoc getContentOutputStream() throws ContentIOException;
107     
108     /**
109      * Copies content from the reader.
110      * <p>
111      * All resources will be closed automatically.
112      *
113      * @param reader the reader acting as the source of the content
114      * @throws ContentIOException
115      *
116      * @see #getWritableChannel()
117      */
118     public void putContent(ContentReader reader) throws ContentIOException;
119     
120     /**
121      * Puts content to the repository
122      * <p>
123      * All resources will be closed automatically.
124      *
125      * @param is the input stream from which the content will be read
126      * @throws ContentIOException
127      *
128      * @see #getWritableChannel()
129      */
130     public void putContent(InputStream JavaDoc is) throws ContentIOException;
131     
132     /**
133      * Puts content to the repository direct from file
134      * <p>
135      * All resources will be closed automatically.
136      *
137      * @param file the file to load the content from
138      * @throws ContentIOException
139      *
140      * @see #getWritableChannel()
141      */
142     public void putContent(File JavaDoc file) throws ContentIOException;
143     
144     /**
145      * Puts content to the repository direct from <code>String</code>.
146      * <p>
147      * If the {@link ContentAccessor#getEncoding() encoding } is known then it will be used
148      * otherwise the default system <tt>String</tt> to <tt>byte[]</tt> conversion
149      * will be used.
150      * <p>
151      * All resources will be closed automatically.
152      *
153      * @param content a string representation of the content
154      * @throws ContentIOException
155      *
156      * @see #getWritableChannel()
157      * @see String#getBytes(java.lang.String)
158      */
159     public void putContent(String JavaDoc content) throws ContentIOException;
160 }
161
Popular Tags