0
# Media Operations
1

2
Resumable upload and download functionality for large files with built-in progress tracking, error recovery, and configurable chunk sizes.
3

4
## Core Imports
5

6
```java
7
import com.google.api.client.googleapis.media.MediaHttpUploader;
8
import com.google.api.client.googleapis.media.MediaHttpUploaderProgressListener;
9
import com.google.api.client.googleapis.media.MediaHttpDownloader;
10
import com.google.api.client.googleapis.media.MediaHttpDownloaderProgressListener;
11
import com.google.api.client.googleapis.media.MediaUploadErrorHandler;
12
```
13

14
## Media Upload
15

16
### MediaHttpUploader
17

18
Handles resumable media uploads with progress tracking and error recovery.
19

20
```java { .api }
21
public final class MediaHttpUploader {
22
    public static final String CONTENT_LENGTH_HEADER = "X-Upload-Content-Length";
23
    public static final String CONTENT_TYPE_HEADER = "X-Upload-Content-Type";
24
    public static final int MINIMUM_CHUNK_SIZE = 262144; // 256KB
25
    public static final int DEFAULT_CHUNK_SIZE = 10485760; // 10MB
26
    
27
    public MediaHttpUploader(AbstractInputStreamContent mediaContent, HttpTransport transport, 
28
        HttpRequestInitializer httpRequestInitializer);
29
    
30
    public HttpResponse upload(GenericUrl initiationRequestUrl) throws IOException;
31
    
32
    public MediaHttpUploader setProgressListener(MediaHttpUploaderProgressListener progressListener);
33
    public MediaHttpUploaderProgressListener getProgressListener();
34
    
35
    public MediaHttpUploader setChunkSize(int chunkSize);
36
    public int getChunkSize();
37
    
38
    public MediaHttpUploader setDirectUploadEnabled(boolean directUploadEnabled);
39
    public boolean isDirectUploadEnabled();
40
    
41
    public MediaHttpUploader setDisableGZipContent(boolean disableGZipContent);
42
    public boolean getDisableGZipContent();
43
    
44
    public MediaHttpUploader setInitiationHeaders(HttpHeaders initiationHeaders);
45
    public HttpHeaders getInitiationHeaders();
46
    
47
    public MediaHttpUploader setInitiationRequestMethod(String initiationRequestMethod);
48
    public String getInitiationRequestMethod();
49
    
50
    public MediaHttpUploader setMetadata(HttpContent metadata);
51
    public HttpContent getMetadata();
52
    
53
    public HttpContent getMediaContent();
54
    public HttpTransport getTransport();
55
    
56
    public MediaHttpUploader setSleeper(Sleeper sleeper);
57
    public Sleeper getSleeper();
58
    
59
    public UploadState getUploadState();
60
    public double getProgress() throws IOException;
61
    public long getNumBytesUploaded();
62
    
63
    public enum UploadState {
64
        NOT_STARTED,
65
        INITIATION_STARTED,
66
        INITIATION_COMPLETE,
67
        MEDIA_IN_PROGRESS,
68
        MEDIA_COMPLETE
69
    }
70
}
71
```
72

73
### MediaHttpUploaderProgressListener
74

75
Interface for tracking upload progress.
76

77
```java { .api }
78
public interface MediaHttpUploaderProgressListener {
79
    void progressChanged(MediaHttpUploader uploader) throws IOException;
80
}
81
```
82

83
**Usage Example:**
84

85
```java
86
import com.google.api.client.googleapis.media.MediaHttpUploader;
87
import com.google.api.client.googleapis.media.MediaHttpUploaderProgressListener;
88
import com.google.api.client.http.FileContent;
89

90
// Create media content
91
File mediaFile = new File("path/to/large-file.mp4");
92
FileContent mediaContent = new FileContent("video/mp4", mediaFile);
93

94
// Create uploader
95
MediaHttpUploader uploader = new MediaHttpUploader(mediaContent, transport, credential);
96

97
// Set chunk size (default is 10MB)
98
uploader.setChunkSize(MediaHttpUploader.DEFAULT_CHUNK_SIZE);
99

100
// Add progress listener
101
uploader.setProgressListener(new MediaHttpUploaderProgressListener() {
102
    @Override
103
    public void progressChanged(MediaHttpUploader uploader) throws IOException {
104
        switch (uploader.getUploadState()) {
105
            case INITIATION_STARTED:
106
                System.out.println("Upload initiation started");
107
                break;
108
            case INITIATION_COMPLETE:
109
                System.out.println("Upload initiation completed");
110
                break;
111
            case MEDIA_IN_PROGRESS:
112
                System.out.println("Upload progress: " + 
113
                    Math.round(uploader.getProgress() * 100) + "%");
114
                break;
115
            case MEDIA_COMPLETE:
116
                System.out.println("Upload completed");
117
                break;
118
        }
119
    }
120
});
121

122
// Perform upload
123
GenericUrl uploadUrl = new GenericUrl("https://www.googleapis.com/upload/storage/v1/b/bucket/o");
124
HttpResponse response = uploader.upload(uploadUrl);
125
```
126

127
## Media Download
128

129
### MediaHttpDownloader
130

131
Handles resumable media downloads with progress tracking.
132

133
```java { .api }
134
public final class MediaHttpDownloader {
135
    public static final int MAXIMUM_CHUNK_SIZE = 33554432; // 32MB
136
    
137
    public MediaHttpDownloader(HttpTransport transport, HttpRequestInitializer httpRequestInitializer);
138
    
139
    public void download(GenericUrl requestUrl, OutputStream outputStream) throws IOException;
140
    public void download(GenericUrl requestUrl, HttpHeaders requestHeaders, OutputStream outputStream) throws IOException;
141
    
142
    public MediaHttpDownloader setProgressListener(MediaHttpDownloaderProgressListener progressListener);
143
    public MediaHttpDownloaderProgressListener getProgressListener();
144
    
145
    public MediaHttpDownloader setChunkSize(int chunkSize);
146
    public int getChunkSize();
147
    
148
    public MediaHttpDownloader setDirectDownloadEnabled(boolean directDownloadEnabled);
149
    public boolean isDirectDownloadEnabled();
150
    
151
    public DownloadState getDownloadState();
152
    public double getProgress();
153
    public long getNumBytesDownloaded();
154
    public long getContentLength();
155
    
156
    public MediaHttpDownloader setBytesDownloaded(long bytesDownloaded);
157
    
158
    public enum DownloadState {
159
        NOT_STARTED,
160
        MEDIA_IN_PROGRESS,
161
        MEDIA_COMPLETE
162
    }
163
}
164
```
165

166
### MediaHttpDownloaderProgressListener
167

168
Interface for tracking download progress.
169

170
```java { .api }
171
public interface MediaHttpDownloaderProgressListener {
172
    void progressChanged(MediaHttpDownloader downloader) throws IOException;
173
}
174
```
175

176
**Usage Example:**
177

178
```java
179
import com.google.api.client.googleapis.media.MediaHttpDownloader;
180
import com.google.api.client.googleapis.media.MediaHttpDownloaderProgressListener;
181
import java.io.FileOutputStream;
182

183
// Create downloader
184
MediaHttpDownloader downloader = new MediaHttpDownloader(transport, credential);
185

186
// Set chunk size for resumable downloads
187
downloader.setChunkSize(MediaHttpDownloader.MAXIMUM_CHUNK_SIZE);
188

189
// Add progress listener
190
downloader.setProgressListener(new MediaHttpDownloaderProgressListener() {
191
    @Override
192
    public void progressChanged(MediaHttpDownloader downloader) throws IOException {
193
        switch (downloader.getDownloadState()) {
194
            case MEDIA_IN_PROGRESS:
195
                System.out.println("Download progress: " + 
196
                    Math.round(downloader.getProgress() * 100) + "% (" +
197
                    downloader.getNumBytesDownloaded() + " / " + 
198
                    downloader.getContentLength() + " bytes)");
199
                break;
200
            case MEDIA_COMPLETE:
201
                System.out.println("Download completed");
202
                break;
203
        }
204
    }
205
});
206

207
// Perform download
208
GenericUrl downloadUrl = new GenericUrl("https://www.googleapis.com/storage/v1/b/bucket/o/file?alt=media");
209
FileOutputStream outputStream = new FileOutputStream("downloaded-file.dat");
210
try {
211
    downloader.download(downloadUrl, outputStream);
212
} finally {
213
    outputStream.close();
214
}
215
```
216

217
## Error Handling
218

219
### MediaUploadErrorHandler
220

221
Error handler for media upload operations.
222

223
```java { .api }
224
public class MediaUploadErrorHandler implements HttpUnsuccessfulResponseHandler {
225
    public MediaUploadErrorHandler();
226
    public MediaUploadErrorHandler(BackOff backOff);
227
    
228
    public boolean handleResponse(HttpRequest request, HttpResponse response, boolean supportsRetry) throws IOException;
229
    
230
    public final BackOff getBackOff();
231
    public MediaUploadErrorHandler setBackOff(BackOff backOff);
232
}
233
```
234

235
**Usage Example:**
236

237
```java
238
import com.google.api.client.googleapis.media.MediaUploadErrorHandler;
239
import com.google.api.client.util.ExponentialBackOff;
240

241
// Create error handler with exponential backoff
242
MediaUploadErrorHandler errorHandler = new MediaUploadErrorHandler(
243
    new ExponentialBackOff.Builder()
244
        .setInitialIntervalMillis(1000)
245
        .setMaxElapsedTimeMillis(300000) // 5 minutes
246
        .build()
247
);
248

249
// Apply to HTTP request
250
HttpRequest request = transport.createRequestFactory(credential)
251
    .buildPostRequest(uploadUrl, mediaContent);
252
request.setUnsuccessfulResponseHandler(errorHandler);
253
```
254

255
## Constants and Configuration
256

257
### Default Values
258

259
```java { .api }
260
// Upload chunk sizes
261
public static final int MINIMUM_CHUNK_SIZE = 262144; // 256KB for uploads
262
public static final int DEFAULT_CHUNK_SIZE = 10485760; // 10MB for uploads
263

264
// Download chunk sizes  
265
public static final int MAXIMUM_CHUNK_SIZE = 33554432; // 32MB for downloads
266

267
// Upload states
268
enum UploadState {
269
    NOT_STARTED,
270
    INITIATION_STARTED, 
271
    INITIATION_COMPLETE,
272
    MEDIA_IN_PROGRESS,
273
    MEDIA_COMPLETE
274
}
275

276
// Download states
277
enum DownloadState {
278
    NOT_STARTED,
279
    MEDIA_IN_PROGRESS,
280
    MEDIA_COMPLETE
281
}
282
```
283

284
## Best Practices
285

286
### Upload Optimization
287

288
```java
289
// For large files, use appropriate chunk size
290
uploader.setChunkSize(MediaHttpUploader.DEFAULT_CHUNK_SIZE * 4); // 40MB chunks
291

292
// Enable direct upload for small files
293
if (fileSize < MediaHttpUploader.DEFAULT_CHUNK_SIZE) {
294
    uploader.setDirectUploadEnabled(true);
295
}
296

297
// Set metadata for the upload
298
HttpContent metadata = new JsonHttpContent(jsonFactory, fileMetadata);
299
uploader.setMetadata(metadata);
300
```
301

302
### Download Optimization
303

304
```java
305
// Use maximum chunk size for faster downloads
306
downloader.setChunkSize(MediaHttpDownloader.MAXIMUM_CHUNK_SIZE);
307

308
// Enable direct download for small files
309
downloader.setDirectDownloadEnabled(true);
310

311
// Resume interrupted downloads
312
if (previouslyDownloadedBytes > 0) {
313
    downloader.setBytesDownloaded(previouslyDownloadedBytes);
314
}
315
```
316

317
## Types
318

319
### AbstractInputStreamContent
320

321
Base class for input stream content used in uploads.
322

323
### HttpContent
324

325
Interface for HTTP content.
326

327
### FileContent
328

329
HTTP content implementation for files.
330

331
### HttpTransport
332

333
HTTP transport interface.
334

335
### HttpRequestInitializer
336

337
Interface for initializing HTTP requests.
338

339
### HttpResponse
340

341
HTTP response container.
342

343
### HttpHeaders
344

345
HTTP headers container.
346

347
### GenericUrl
348

349
Generic URL builder.
350

351
### OutputStream
352

353
Java output stream for writing downloaded data.
354

355
### IOException
356

357
Exception for I/O operations.
358

359
### BackOff
360

361
Interface for backoff strategies during retries.
362

363
### Sleeper
364

365
Interface for controlling sleep behavior during uploads.