Contents

• Features
• Requirement
• Instructions
• Getting Started with the SDK
• File Upload
• Input Parameters
• Response
• example
• Advanced Configuration
• Upload configuration
• Parameters
• Example
• Upload Progress Notification
• Getting Started
• Example

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.

Features

• 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.

Requirement

• 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.

Instructions

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.

Response

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

example

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>();
        categoryNameBeanList.add(categoryNameBean);
        String transCodeCombineName = "Transcoding Template Name";
        String waterMarkName = "Watermark";
        String domain = "Your domain";

        UploadFileParam uploadFileParam = new UploadFileParam();
        uploadFileParam.setCategoryNameBeanList(categoryNameBeanList);
        uploadFileParam.setTransCodeCombineName(transCodeCombineName);
        uploadFileParam.setWaterMarkName(waterMarkName);
        uploadFileParam.setDomain(domain);
        String videoId = cloudvUploadHandler.upload(filePath, userId, secretKey, null, uploadFileParam);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

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

Parameters

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

Example

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) {
        e.printStackTrace();
    }
}

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);
}

Example

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;

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

    @Override
    public void onSuccess(UploadResult result) {
        LOGGER.info("videoId:{}, filePath:{}, Success upload", videoId, filePath);
    }

    @Override
    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);
    }

    @Override
    public void onProcess(long uploaded, long total) {
        LOGGER.info("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) {
            e.printStackTrace();
        }
    }