5176e6aa5a7fc6f5c0f30040742b3fb00850ef82
[jFCPlib.git] / src / main / java / net / pterodactylus / fcp / ClientPut.java
1 /*
2  * jFCPlib - ClientPut.java - Copyright © 2008 David Roden
3  *
4  * This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
17  */
18
19 package net.pterodactylus.fcp;
20
21 /**
22  * A “ClientPut” requests inserts a single file into freenet, either uploading
23  * it directly with this messge ({@link UploadFrom#direct}), uploading it from
24  * disk ({@link UploadFrom#disk}) or by creating a redirect to another URI (
25  * {@link UploadFrom#redirect}).
26  *
27  * @author David ‘Bombe’ Roden <bombe@freenetproject.org>
28  */
29 public class ClientPut extends FcpMessage {
30
31         /**
32          * Creates a new “ClientPut” message that inserts a file to the given URI.
33          * The file data <em>has</em> to be supplied to this message using
34          * {@link #setPayloadInputStream(java.io.InputStream)}! Using this
35          * constructor is the same as using
36          * {@link #ClientPut(String, String, UploadFrom)} with
37          * {@link UploadFrom#direct} as third parameter.
38          *
39          * @param uri
40          *            The URI to insert the file to
41          * @param identifier
42          *            The identifier of the request
43          */
44         public ClientPut(String uri, String identifier) {
45                 this(uri, identifier, UploadFrom.direct);
46         }
47
48         /**
49          * Creates a new “ClientPut” message that inserts a file to the given URI.
50          * Depending on <code>uploadFrom</code> the file data has to be supplied in
51          * different ways: If <code>uploadFrom</code> is {@link UploadFrom#direct},
52          * use {@link #setPayloadInputStream(java.io.InputStream)} to supply the
53          * input data. If <code>uploadFrom</code> is {@link UploadFrom#disk}, use
54          * {@link #setFilename(String)} to supply the file to upload. You have to
55          * test your direct-disk access (see {@link TestDDARequest},
56          * {@link TestDDAReply}, {@link TestDDAResponse}, {@link TestDDAComplete})
57          * before using this option! If <code>uploadFrom</code> is
58          * {@link UploadFrom#redirect}, use {@link #setTargetURI(String)} to set the
59          * target URI of the redirect.
60          *
61          * @param uri
62          *            The URI to insert to
63          * @param identifier
64          *            The identifier of the insert
65          * @param uploadFrom
66          *            The source of the upload
67          */
68         public ClientPut(String uri, String identifier, UploadFrom uploadFrom) {
69                 super("ClientPut");
70                 setField("URI", uri);
71                 setField("Identifier", identifier);
72                 setField("UploadFrom", String.valueOf(uploadFrom));
73         }
74
75         /**
76          * The MIME type of the content.
77          *
78          * @param metadataContentType
79          *            The MIME type of the content
80          */
81         public void setMetadataContentType(String metadataContentType) {
82                 setField("Metadata.ContentType", metadataContentType);
83         }
84
85         /**
86          * The verbosity of the request. Depending on this parameter you will
87          * received only the bare minimum of messages for the request (i.e. “it
88          * completed”) or a whole lot more.
89          *
90          * @see Verbosity
91          * @param verbosity
92          *            The verbosity of the request
93          */
94         public void setVerbosity(Verbosity verbosity) {
95                 setField("Verbosity", String.valueOf(verbosity));
96         }
97
98         /**
99          * The number of retries for a request if the initial try failed.
100          *
101          * @param maxRetries
102          *            The maximum number of retries after failure, or
103          *            <code>-1</code> to retry forever.
104          */
105         public void setMaxRetries(int maxRetries) {
106                 setField("MaxRetries", String.valueOf(maxRetries));
107         }
108
109         /**
110          * Sets the priority of the request.
111          *
112          * @param priority
113          *            The priority of the request
114          */
115         public void setPriority(Priority priority) {
116                 setField("PriorityClass", String.valueOf(priority));
117         }
118
119         /**
120          * Determines whether the node should really insert the data or generate the
121          * final CHK only.
122          *
123          * @param getCHKOnly
124          *            <code>true</code> to generate the final CHK only,
125          *            <code>false</code> to really insert the data
126          */
127         public void setGetCHKOnly(boolean getCHKOnly) {
128                 setField("GetCHKOnly", String.valueOf(getCHKOnly));
129         }
130
131         /**
132          * Sets whether an insert request should be forked when it is cached.
133          *
134          * @param forkOnCacheable
135          *            {@code true} to fork the insert when it is cached, {@code
136          *            false} otherwise
137          */
138         public void setForkOnCacheable(boolean forkOnCacheable) {
139                 setField("ForkOnCacheable", String.valueOf(forkOnCacheable));
140         }
141
142         /**
143          * Sets the number of additional inserts of single blocks.
144          *
145          * @param extraInsertsSingleBlock
146          *            The number of additional inserts
147          */
148         public void setExtraInsertsSingleBlock(int extraInsertsSingleBlock) {
149                 setField("ExtraInsertsSingleBlock", String.valueOf(extraInsertsSingleBlock));
150         }
151
152         /**
153          * Sets the number of additional inserts of splitfile header blocks.
154          *
155          * @param extraInsertsSplitfileHeaderBlock
156          *            The number of additional inserts
157          */
158         public void setExtraInsertsSplitfileHeaderBlock(int extraInsertsSplitfileHeaderBlock) {
159                 setField("ExtraInsertsSplitfileHeaderBlock", String.valueOf(extraInsertsSplitfileHeaderBlock));
160         }
161
162         /**
163          * Determines whether this request appears on the global queue.
164          *
165          * @param global
166          *            <code>true</code> to put the request on the global queue,
167          *            <code>false</code> for the client-local queue.
168          */
169         public void setGlobal(boolean global) {
170                 setField("Global", String.valueOf(global));
171         }
172
173         /**
174          * Determines whether the node should skip compression because the file has
175          * already been compressed.
176          *
177          * @param dontCompress
178          *            <code>true</code> to skip compression of the data in the node,
179          *            <code>false</code> to allow compression
180          */
181         public void setDontCompress(boolean dontCompress) {
182                 setField("DontCompress", String.valueOf(dontCompress));
183         }
184
185         /**
186          * Sets an optional client token. This client token is mentioned in progress
187          * and other request-related messages and can be used to identify this
188          * request.
189          *
190          * @param clientToken
191          *            The client token
192          */
193         public void setClientToken(String clientToken) {
194                 setField("ClientToken", clientToken);
195         }
196
197         /**
198          * Sets the persistence of this request.
199          *
200          * @param persistence
201          *            The persistence of this request
202          */
203         public void setPersistence(Persistence persistence) {
204                 setField("Persistence", String.valueOf(persistence));
205         }
206
207         /**
208          * Sets the target filename of the inserted file. This value is ignored for
209          * all inserts that do not have “CHK@” as a target.
210          *
211          * @param targetFilename
212          *            The filename of the target
213          */
214         public void setTargetFilename(String targetFilename) {
215                 setField("TargetFilename", targetFilename);
216         }
217
218         /**
219          * Determines whether to encode the complete file early in the life of the
220          * request.
221          *
222          * @param earlyEncode
223          *            <code>true</code> to generate the final key long before the
224          *            file is completely fetchable
225          */
226         public void setEarlyEncode(boolean earlyEncode) {
227                 setField("EarlyEncode", String.valueOf(earlyEncode));
228         }
229
230         /**
231          * Sets the length of the data that will be transferred after this message
232          * if <code>uploadFrom</code> is {@link UploadFrom#direct} is used.
233          *
234          * @param dataLength
235          *            The length of the data
236          */
237         public void setDataLength(long dataLength) {
238                 setField("DataLength", String.valueOf(dataLength));
239         }
240
241         /**
242          * Sets the name of the file to upload the data from.
243          *
244          * @param filename
245          *            The filename to upload
246          */
247         public void setFilename(String filename) {
248                 setField("Filename", filename);
249         }
250
251         /**
252          * If <code>uploadFrom</code> is {@link UploadFrom#redirect}, use this
253          * method to determine that target of the redirect.
254          *
255          * @param targetURI
256          *            The target URI to redirect to
257          */
258         public void setTargetURI(String targetURI) {
259                 setField("TargetURI", targetURI);
260         }
261
262 }