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