Java Upload SDK

Last update:2023-02-01 18:26:06


For your convenience to upload your files to Cloud VoD and integrate the upload function into your own project, we provide upload SDK toolkit in Java language. You can embed the SDK into your own application to upload videos to Cloud VoD.


  • Supports both normal upload and multi-part upload.
  • Supports multi-thread upload.
  • Normal upload will be used accordingly when the file size is less than 50MB.
  • Multi-part upload will be used accordingly when the file size is greater than 50MB.
  • Hashes will be used automatically to verify file integrity once the file is uploaded.
  • If the file upload fails, the SDK will automatically perform a retry to re-upload the file, with 3 retries by default.


  • The SDK only supports the Java platform and requires JDK 1.6 or above. JDK 1.8 is recommended.

  • Please make sure Cloud VoD service is available and get your AccountID and AccessKey Secret before using SDK.


Getting Started with the SDK

  1. Download and unzip the Java SDK.
  2. Import cnc-java-sdk-cloudv-upload-xxx.jar to your java project.
  3. Add all third-party dependent jar packages in the lib folder to your java project.

File Upload

You can upload via class ** CloudvUploadHandler**. Here we give an overview of this class:

public String upload(String uploadFilePath, String userId, String secretKey, UploadObserver uploadObserver, UploadFileParam uploadFileParam)

Input Parameters

Parameter Type Required Description
uploadfilePath string Yes The full path of the file to upload.
userId string required Account ID, you can contact customer support to get your account ID.
secretKey string Yes AccessKey Secret, you can get the accesskey secret under Security Settings > Access Control > User Information Management > AccessKey Management on console .
uploadObserver uploadObserver No An instance of class CustomUploadObserver that implements interface uploadObserver, which is used to receive callback notifications for upload start, upload success, upload failure, and upload progress. See more details at Upload Progress Notification.
uploadFileParam uploadFileParam No It is used to set various parameters for configurations during the upload process, as described below.

Description of UploadFileParam

Parameter Type Required Description
categoryNameBeanList list optional Video categories, you can set parent both category and subcategory at a time.
For example, [{“childName”:“child-category1”,“parentName”:“parent-category1”},{“childName”:“child-category2”,“parentName”:“parent-category2”} ].
transCodeCombineName string optional Transcoding template. If specified, transcoding will be performed automatically after the file is uploaded.
waterMarkName string optional Watermark to add into the video. This parameter is valid only when a specific transcoding template is specified through transCodeCombineName. If only transCodeCombineName is specified but waterMarkName is not, the watermark will not work too.
domain string optional Play domain name. Fill in the domain name, if it is left blank or the domain name does not exist, the default domain name of the video on demand will be used.


Type Description
string Video ID, the unique identification of the uploaded video.


public static void main(String[] args) {
    try {
        CloudvUploadHandler cloudvUploadHandler = new CloudvUploadHandler();
        String filePath = "F:\\test.mp4";
        String userId = "xxxxxx";
        String secretKey = "xxxxxxxxxxxxxxxxxxxx";
        CategoryNameBean categoryNameBean = new CategoryNameBean();
        categoryNameBean.setParentName("Parent Category");
        categoryNameBean.setChildName("Child Category");
        List<CategoryNameBean> categoryNameBeanList = new ArrayList<CategoryNameBean>();
        String transCodeCombineName = "Transcoding Template Name";
        String waterMarkName = "Watermark";
        String domain = "Your domain";

        UploadFileParam uploadFileParam = new UploadFileParam();
        String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey, null, uploadFileParam);
    } catch (Exception e) {

Advanced Configuration

In general, the default configuration ensures a satisfying upload speed. If the upload speed or stability cannot meet your requirements, you can adjust the upload parameters for a further configuration, which will take effect globally at once.

Upload configuration


Parameter Description Defaults Configuration Example
BLOCK_SIZE The block size for multipart uploads. Value range: 4M-32M, and it is a multiple of 4. 4MB BaseBlockUtil.BLOCK_SIZE = 32 * BaseBlockUtil.MB
CHUNK_SIZE The chunk size for multipart uploads. Value range: 4M-32M, and it is a multiple of 4. This value should NOT be larger than the set block size.
Appropriately increasing the slice size may improve the upload speed.
4MB BaseBlockUtil.CHUNK_SIZE = 4 * BaseBlockUtil.MB
THREAD_NUN The number of threads when using multi-part uplaod, range 1-10. 5 BaseBlockUtil. THREAD_NUN = 5
FILE_BUFFER_SIZE The buffer size for reading the file content to be uploaded. Increasing buffer size appropriately may improve the upload speed, but may also increase the memory usage. The value should be a multiple of 4. 4KB BaseBlockUtil.FILE_BUFFER_SIZE = 1024 * BaseBlockUtil.KB
TRIED_TIMES The number of automatic retries in case of upload failure. 3 BaseBlockUtil.TRIED_TIMES = 5


public static void main(String[] args) {
    try {
        //Set the block size
        BaseBlockUtil.BLOCK_SIZE = 32 * BaseBlockUtil.MB;
        //Set the chunk size
        BaseBlockUtil.CHUNK_SIZE = 4 * BaseBlockUtil.MB;
        //Set the number of threads
        BaseBlockUtil.THREAD_NUN = 5;
        //Set the buffer size
        BaseBlockUtil.FILE_BUFFER_SIZE = 2 * BaseBlockUtil.MB;
        //Set retry times
        BaseBlockUtil.TRIED_TIMES = 5;
        CloudvUploadHandler cloudvUploadHandler = new CloudvUploadHandler();
        String filePath = "D:\\test.mp4";
        String userId = "xxxxxx";
        String secretKey = "xxxxxxxxxxxxxxxxxxxx";
        String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey, null);
    } catch (Exception e) {

Upload Progress Notification

You can customize the upload progress notification, including getting the upload progress of start upload, upload progress, successful upload and failed upload.

Getting Started

  1. Create a new class to implement interface UploadObserver.
  2. Implement the four functions onBegin, onSuccess4, onFail and onProcess inside UploadObserver.
  3. Add the uploadObserver in the parameters when calling cloudvUploadHandler.upload.
public interface UploadObserver {
     * Call this function before upload
     * @param id
     * @param filePath
    void onBegin(String id, String filePath);

     * Call this function after upload success
     * @param result
    void onSuccess(UploadResult result);

     * Call this function when there is an error
     * @param ex
    void onFail(Exception ex);

     * Callback after multi-part upload
     * @param uploaded 
     * @param total    
    void onProcess(long uploaded, long total);


An example to implement UploadObserver :

public class CustomUploadObserver implements UploadObserver {
    private static final Logger LOGGER = LoggerFactory.getLogger(CustomUploadObserver.class);
    private String videoId;
    private String filePath;

    public void onBegin(String videoId, String filePath) {
        this.videoId = videoId;
        this.filePath = filePath;"videoId:{}, filePath:{}, Start upload", videoId, filePath);

    public void onSuccess(UploadResult result) {"videoId:{}, filePath:{}, Success upload", videoId, filePath);

    public void onFail(Exception ex) {
        String message = "videoId:" + videoId + "filePath:" + filePath + ",Error occurs during upload";
        LOGGER.error("message:{}, error:", message, ex);
        throw new RuntimeException(message, ex);

    public void onProcess(long uploaded, long total) {"videoId:{},filePath:{}, Upload progress:{},", videoId, filePath, uploaded * 100 / total + "%");

How to use:

public static void main(String[] args) {
        try {
            CloudvUploadHandler cloudvUploadHandler = new CloudvUploadHandler();
            String filePath = "D:\\test.mp4";
            String userId = "xxxxxx";
            String secretKey = "xxxxxxxxxxxxxxxxxxxx";
            CustomUploadObserver uploadObserver = new CustomUploadObserver();
            String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey,  uploadObserver);
        } catch (Exception e) {
Is the content of this document helpful to you?
I have suggestion
Submitted successfully! Thank you very much for your feedback, we will continue to strive to do better!