com.brightcove.proserve.mediaapi.wrapper
Class WriteApi

java.lang.Object
  com.brightcove.proserve.mediaapi.wrapper.WriteApi

public class WriteApi
extends java.lang.Object

This is a wrapper for the HTTP/JSON Media API provided by Brightcove (http://www.brightcove.com)

While this library has been created by a member of Brightcove Professional Services, it IS NOT provided by Brightcove - no support, guarantees or warantees are provided. Brightcove may change the Media API at any point, rendering this library crippled or disabled until it is updated.

The purpose of this library is to provide a simple interface from Java applications to the Brightcove Media API. This class provides the interface to the WRITE portion of the Media API.

This library relies on the 3rd party JSON library from http://www.json.org/java/ which must be on the classpath.

For more information on the Media API, see http://support.brightcove.com/en/docs/getting-started-media-api.

Author:

Sander Gates

Constructor Summary

WriteApi()
Default constructor

WriteApi(java.util.logging.Logger log)
Constructor with logging

WriteApi(java.util.logging.Logger log, java.lang.String characterEncoding)
Constructor with character set and logging

WriteApi(java.lang.String characterEncoding)
Constructor with character set

Method Summary

Image	AddImage(java.lang.String writeToken, Image image, java.lang.String filename, java.lang.Long videoId, java.lang.String videoReferenceId, java.lang.Boolean resize) Add a new thumbnail or video still image to a video, or assign an existing image to another video.
java.lang.Long	CreatePlaylist(java.lang.String writeToken, Playlist playlist) Creates a playlist.
java.lang.Long	CreateVideo(java.lang.String writeToken, Video video, java.lang.String filename, TranscodeEncodeToEnum encodeTo, java.lang.Boolean createMultipleRenditions, java.lang.Boolean preserveSourceRendition, java.lang.Boolean h264NoProcessing) Create a new video in the account.
JSONObject	DeletePlaylist(java.lang.String writeToken, java.lang.Long playlistId, java.lang.String referenceId, java.lang.Boolean cascade) Deletes a playlist, specified by playlist id.
JSONObject	DeleteVideo(java.lang.String writeToken, java.lang.Long videoId, java.lang.String referenceId, java.lang.Boolean cascade, java.lang.Boolean deleteShares) Deletes a video.
UploadStatusEnum	GetUploadStatus(java.lang.String writeToken, java.lang.Long videoId, java.lang.String referenceId) Call this function in an HTTP POST request to determine the status of an upload.
java.util.List<java.lang.Long>	ShareVideo(java.lang.String writeToken, java.lang.Long videoId, java.lang.Boolean autoAccept, java.util.List<java.lang.Long> shareeAccountIds) Shares the specified video with a list of sharee accounts
java.util.List<java.lang.Long>	ShareVideo(java.lang.String writeToken, java.lang.Long videoId, java.lang.Boolean autoAccept, java.util.List<java.lang.Long> shareeAccountIds, java.lang.Boolean forceReshare) Shares the specified video with a list of sharee accounts
Playlist	UpdatePlaylist(java.lang.String writeToken, Playlist playlist) Updates a playlist, specified by playlist id.
Video	UpdateVideo(java.lang.String writeToken, Video video) Use this method to modify the metadata for a single video in your Brightcove Media Library.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WriteApi

public WriteApi()

Default constructor

Creates a new Read API wrapper object with default settings

• No logging
• UTF-8 character set

WriteApi

public WriteApi(java.util.logging.Logger log)

Constructor with logging

Creates a new Read API wrapper object with the following settings

• Logging to Logger object provided
• UTF-8 character set

Parameters:

log - java.util.logging.Logger object to log to

WriteApi

public WriteApi(java.lang.String characterEncoding)

Constructor with character set

Creates a new Read API wrapper object with the following settings

• No logging
• Character set specified

Parameters:

characterEncoding - Character encoding to use for HTTP URLs and responses

WriteApi

public WriteApi(java.util.logging.Logger log,
                java.lang.String characterEncoding)

Constructor with character set and logging

Creates a new Read API wrapper object with the following settings

• Logging to Logger object provided
• Character set specified

Parameters:

log - java.util.logging.Logger object to log to

characterEncoding - Character encoding to use for HTTP URLs and responses

Method Detail

CreateVideo

public java.lang.Long CreateVideo(java.lang.String writeToken,
                                  Video video,
                                  java.lang.String filename,
                                  TranscodeEncodeToEnum encodeTo,
                                  java.lang.Boolean createMultipleRenditions,
                                  java.lang.Boolean preserveSourceRendition,
                                  java.lang.Boolean h264NoProcessing)
                           throws BrightcoveException

Create a new video in the account.

Parameters:

writeToken - Write Media API token for the account.

video - Video object with all of the meta data to create

filename - Name of file to use for the video rendition

encodeTo - If the file requires transcoding, use this parameter to specify the target encoding. Valid values are MP4 or FLV, representing the H264 and VP6 codecs respectively. Note that transcoding of FLV files to another codec is not currently supported.

createMultipleRenditions - If the file is a supported transcodeable type, this optional flag can be used to control the number of transcoded renditions. If true (default), multiple renditions at varying encoding rates and dimensions are created. Setting this to false will cause a single transcoded VP6 rendition to be created at the standard encoding rate and dimensions.

preserveSourceRendition - If the video file is H.264 encoded and if create_multiple_ renditions=true, then multiple VP6 renditions are created and in addition the H.264 source is retained as an additional rendition.

h264NoProcessing - Use this option to prevent H.264 source files from being transcoded. This parameter cannot be used in combination with create_multiple_renditions. It is optional and defaults to false.

Returns:

The video id of the video that's been created.

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Video can not be created
• Response from the Media API couldn't be parsed

AddImage

public Image AddImage(java.lang.String writeToken,
                      Image image,
                      java.lang.String filename,
                      java.lang.Long videoId,
                      java.lang.String videoReferenceId,
                      java.lang.Boolean resize)
               throws BrightcoveException

Add a new thumbnail or video still image to a video, or assign an existing image to another video.

Parameters:

writeToken - Write Media API token for the account.

image - Image object with all of the meta data to create

filename - Name of file to use for the image

videoId - The id of the video to associate this image with

videoReferenceId - The reference id of the video to associate this image with

resize - Set this to false if you don't want your image to be automatically resized to the default size for its type. By default images will be resized.

Returns:

Image object representing the image that's been created.

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Image could not be added
• Response from the Media API couldn't be parsed

GetUploadStatus

public UploadStatusEnum GetUploadStatus(java.lang.String writeToken,
                                        java.lang.Long videoId,
                                        java.lang.String referenceId)
                                 throws BrightcoveException

Call this function in an HTTP POST request to determine the status of an upload.

Parameters:

writeToken - The Write API authentication token required to use this method.

videoId - The id of the video whose status you'd like to get.

referenceId - The publisher-assigned reference id of the video whose status you'd like to get.

Returns:

UploadStatusEnum object indicating the status of the video

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Video could not be found or status could not be determined
• Response from the Media API couldn't be parsed

DeleteVideo

public JSONObject DeleteVideo(java.lang.String writeToken,
                              java.lang.Long videoId,
                              java.lang.String referenceId,
                              java.lang.Boolean cascade,
                              java.lang.Boolean deleteShares)
                       throws BrightcoveException

Deletes a video.

Parameters:

writeToken - The Write API authentication token required to use this method. A string, generally ending in . (dot).

videoId - The id of the video you'd like to delete

referenceId - The publisher-assigned reference id of the video you'd like to delete.

cascade - Set this to true if you want to delete this video even if it is part of a manual playlist or assigned to a player. The video will be removed from all playlists and players in which it appears, then deleted.

deleteShares - Set this to true if you want also to delete shared copies of this video. Note that this will delete all shared copies from sharee accounts, regardless of whether or not those accounts are currently using the video in playlists or players.

Returns:

Any output from the Media API as a JSON Object, but this generally will be void or null

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Video could not be deleted
• Response from the Media API couldn't be parsed

ShareVideo

public java.util.List<java.lang.Long> ShareVideo(java.lang.String writeToken,
                                                 java.lang.Long videoId,
                                                 java.lang.Boolean autoAccept,
                                                 java.util.List<java.lang.Long> shareeAccountIds)
                                          throws BrightcoveException

Shares the specified video with a list of sharee accounts

Parameters:

writeToken - The Write API authentication token required to use this method.

videoId - The id for video that will be shared.

autoAccept - If the target account has the option enabled, setting this flag to true will bypass the approval process, causing the shared video to automatically appear in the target account's library. If the target account does not have the option enabled, or this flag is unspecified or false, then the shared video will be queued up to be approved by the target account before appearing in their library.

shareeAccountIds - List of Account IDs to share video with.

Returns:

Array of new video IDs (one for each account id).

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Video could not be shared
• Response from the Media API couldn't be parsed

ShareVideo

public java.util.List<java.lang.Long> ShareVideo(java.lang.String writeToken,
                                                 java.lang.Long videoId,
                                                 java.lang.Boolean autoAccept,
                                                 java.util.List<java.lang.Long> shareeAccountIds,
                                                 java.lang.Boolean forceReshare)
                                          throws BrightcoveException

Shares the specified video with a list of sharee accounts

Parameters:

writeToken - The Write API authentication token required to use this method.

videoId - The id for video that will be shared.

autoAccept - If the target account has the option enabled, setting this flag to true will bypass the approval process, causing the shared video to automatically appear in the target account's library. If the target account does not have the option enabled, or this flag is unspecified or false, then the shared video will be queued up to be approved by the target account before appearing in their library.

shareeAccountIds - List of Account IDs to share video with.

forceReshare - Setting force_reshare to true indicates that if the shared video already exists in the target account's library, it should be overwritten by the video in the sharer's account

Returns:

Array of new video IDs (one for each account id).

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Video could not be shared
• Response from the Media API couldn't be parsed

UpdateVideo

public Video UpdateVideo(java.lang.String writeToken,
                         Video video)
                  throws BrightcoveException

Use this method to modify the metadata for a single video in your Brightcove Media Library.

Parameters:

writeToken - The Write API authentication token required to use this method.

video - The video meta data to be updated.

Returns:

The video object updated.

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Video could not be updated
• Response from the Media API couldn't be parsed

CreatePlaylist

public java.lang.Long CreatePlaylist(java.lang.String writeToken,
                                     Playlist playlist)
                              throws BrightcoveException

Creates a playlist. This method must be called using an HTTP POST request and JSON parameters.

Parameters:

writeToken - The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).

playlist - The metadata for the playlist you'd like to create. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Playlist object. Populate the videoIds property of the playlist, not the videos property.

Returns:

The ID of the Playlist you created.

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Playlist could not be created
• Response from the Media API couldn't be parsed

UpdatePlaylist

public Playlist UpdatePlaylist(java.lang.String writeToken,
                               Playlist playlist)
                        throws BrightcoveException

Updates a playlist, specified by playlist id. This method must be called using an HTTP POST request and JSON parameters.

Parameters:

writeToken - The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).

playlist - The metadata for the playlist you'd like to create. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Playlist object. Populate the videoIds property of the playlist, not the videos property.

Returns:

The Playlist updated

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Playlist could not be updated
• Response from the Media API couldn't be parsed

DeletePlaylist

public JSONObject DeletePlaylist(java.lang.String writeToken,
                                 java.lang.Long playlistId,
                                 java.lang.String referenceId,
                                 java.lang.Boolean cascade)
                          throws BrightcoveException

Deletes a playlist, specified by playlist id.

Parameters:

writeToken - The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).

playlistId - the id for the playlist to delete

referenceId - The publisher-assigned reference id of the playlist you'd like to delete.

cascade - Set this to true if you'd like to delete this playlist even if it is referenced by players. The playlist will be removed from all players in which it appears, then deleted.

Returns:

Any response messages from the server

Throws:

BrightcoveException - If any of the following are true:

• Request to the Media API fails
• Media API reports an error with the request
• Playlist could not be deleted
• Response from the Media API couldn't be parsed