org.alembik
Class TranscodingManager

java.lang.Object
  org.alembik.TranscodingManager

All Implemented Interfaces:

java.io.Serializable

public class TranscodingManager
extends java.lang.Object
implements java.io.Serializable

The cornerstone singleton component, which provides access to Alembik service and various utility methods for creating and executing transcoding requests.

Since:

1.0-beta1

See Also:

getInstance(), Serialized Form

Method Summary

static TranscodingManager	getInstance()
java.lang.String	getProperty(java.lang.String name) Returns the service connection property of the given name.
java.lang.String	getTranscodedUrl(java.lang.String sourceUrl, java.lang.String profileID, java.lang.Long maxSize) Returns the transcoded file location for a job scheduled with the given parameters set.
JobResult	getTranscodingInfo(TranscodingRequest request, java.lang.String jobID) Fetches a detailed processing results of the given job.
TranscodingParams	getTranscodingProfile(TranscodingJob job) Returns a transcoding profile resolved for the given job.
boolean	isSourceFileComplete(TranscodingRequest request, java.lang.String jobID) Checks whether a loaded source file has not been truncated by a DownloadLimit transformation.
boolean	isSourceFileReady(TranscodingRequest request, java.lang.String jobID) Checks whether a source file of the given job has been already loaded into the Alembik storage.
boolean	isTranscodedFileReady(java.lang.String sourceUrl, java.lang.String profileID, java.lang.Long maxSize) Checks whether a source file, whose processing was scheduled with the given parameters set has been already transcoded.
boolean	isTranscodedFileReady(TranscodingRequest request, java.lang.String jobID) Checks whether a source file of the given job has been already transcoded.
static TranscodingRequest	prepareBestMatchingRequest(java.lang.String sourceUrl, java.lang.String userAgent, java.lang.Class<? extends Media> mediaType, Quality quality, boolean isStreaming) Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and desired quality of a predefined profile selected by "best matching" strategy algorithm.
static TranscodingRequest	prepareRequest(java.lang.String sourceUrl, java.lang.String profileID, java.lang.String contentType, java.lang.Long maxSize) Creates a single-job trancoding request instance with the given transcoding parameters set.
static TranscodingRequest	prepareUARequest(java.lang.String sourceUrl, java.lang.String userAgent, java.lang.Class<? extends Media> mediaType, java.lang.Integer width, java.lang.Integer height) Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and (optionally) dimensions.
static TranscodingRequest	prepareUARequest(java.lang.String sourceUrl, java.lang.String userAgent, java.lang.Class<? extends Media> mediaType, java.lang.Long maxSize) Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and (optionally) size limit.
static TranscodingRequest	prepareUARequestStreamingVideo(java.lang.String sourceUrl, java.lang.String userAgent, java.lang.Long maxSize) Creates a single-job streaming video transcoding request for the given source location, User-Agent string and (optionally) size limit.
static TranscodingRequest	prepareUARequestWithScaling(java.lang.String sourceUrl, java.lang.String userAgent, java.lang.Class<? extends Media> mediaType, java.lang.Integer relativeWidth, java.lang.Integer relativeHeight) Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and (optionally) dimensions in the form of percentage of a device screen size.
void	processAsync(java.lang.String sourceUrl, java.lang.String profileID, java.lang.Long maxSize) Sends a single-job transcoding request to be processed asynchronously.
void	processAsync(TranscodingRequest request) Sends the given transcoding request to be processed asynchronously.
java.lang.String	processSync(java.lang.String sourceUrl, java.lang.String profileID, java.lang.Long maxSize) Sends a single-job transcoding request to be processed synchronously.
TranscodingResponse	processSync(TranscodingRequest request) Sends the given transcoding request to be processed synchronously.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static TranscodingManager getInstance()

Returns:

class singleton instance

getProperty

public java.lang.String getProperty(java.lang.String name)

Returns the service connection property of the given name.

Parameters:

name - name of the requested connection property

Returns:

the property value, if found; otherwise null

processSync

public TranscodingResponse processSync(TranscodingRequest request)
                                throws TranscodingException

Sends the given transcoding request to be processed synchronously.

In general the method returns a transcoding response with the appropriate return result (success, warn or error), although some unexpected error may produce a transcoding exception.

Parameters:

request - transcoding request with at least one job defined

Returns:

transcoding response with the result info on each request's job

Throws:

TranscodingException - if the request cannot be processed

See Also:

processSync(String, String, Long), TranscodingResponse.getMainReturnResult(), TranscodingService.processSync(TranscodingRequest)

processAsync

public void processAsync(TranscodingRequest request)
                  throws TranscodingException

Sends the given transcoding request to be processed asynchronously.

The jobs progress and processing details can be retrieved subsequently with the getTranscodingInfo(TranscodingRequest, String) method.

Parameters:

request - transcoding request with at least one job defined

Throws:

TranscodingException - if the request cannot be processed

See Also:

getTranscodingInfo(TranscodingRequest, String), TranscodingService.processAsync(TranscodingRequest)

isSourceFileReady

public boolean isSourceFileReady(TranscodingRequest request,
                                 java.lang.String jobID)
                          throws java.lang.IllegalStateException

Checks whether a source file of the given job has been already loaded into the Alembik storage.

Parameters:

request - request containing the inquired job

jobID - id of the inquired job

Returns:

true if the source file is ready; otherwise false

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

TranscodingService.isSourceFileReady(TranscodingRequest, String)

isTranscodedFileReady

public boolean isTranscodedFileReady(TranscodingRequest request,
                                     java.lang.String jobID)
                              throws java.lang.IllegalStateException

Checks whether a source file of the given job has been already transcoded.

Parameters:

request - request containing the inquired job

jobID - id of the inquired job

Returns:

true if the transcoded file is ready; otherwise false

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

processAsync(TranscodingRequest), TranscodingService.isTranscodedFileReady(TranscodingRequest, String)

getTranscodingInfo

public JobResult getTranscodingInfo(TranscodingRequest request,
                                    java.lang.String jobID)
                             throws java.lang.IllegalStateException

Fetches a detailed processing results of the given job.

The returned JobResult object contains either the information on the transcoded result (if successful), error codes and messages (upon job failure) or transcoding progress (when job is still in process).

Parameters:

request - request containing the inquired job

jobID - id of the inquired job

Returns:

job result object if the job has been identified; otherwise null

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

JobResult.Output.getLocation(), JobResult.getMainReturnResult(), TranscodingUtils.getResultInfo(JobResult, org.alembik.util.TranscodingUtils.FileInfo), TranscodingUtils.getResultState(JobResult)

isSourceFileComplete

public boolean isSourceFileComplete(TranscodingRequest request,
                                    java.lang.String jobID)
                             throws java.lang.IllegalStateException

Checks whether a loaded source file has not been truncated by a DownloadLimit transformation.

Parameters:

request - request containing the inquired job

jobID - id of the inquired job

Returns:

true if the source file is ready and has not been truncated; otherwise false

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

TranscodingUtils.FileInfo.COMPLETE, TranscodingUtils.getResultInfo(JobResult, FileInfo)

getTranscodingProfile

public TranscodingParams getTranscodingProfile(TranscodingJob job)
                                        throws java.lang.IllegalStateException

Returns a transcoding profile resolved for the given job.

The method is useful to obtain the detailed transcoding parameters as resolved by the server on the basis of the passed job's profileID field. Then the returned object is an instance of a predefined profile or a result of User-Agent resolution.

Parameters:

job - transcoding job to be resolved

Returns:

resolved transcoding profile

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

TranscodingUtils.getMatchedId(TranscodingParams), WURFLUtils, TranscodingService.getTranscodingProfile(TranscodingJob)

processSync

public java.lang.String processSync(java.lang.String sourceUrl,
                                    java.lang.String profileID,
                                    java.lang.Long maxSize)
                             throws TranscodingException

Sends a single-job transcoding request to be processed synchronously.

The method is primarily intended to transcode content with a predefined transcoding profile (defined in the server-side profile-defs.xml).

Parameters:

sourceUrl - source file location (accessed with HTTP protocol)

profileID - id of the selected predefined profile

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Returns:

transcoded file location if succefully processed; otherwise null

Throws:

TranscodingException - if the request cannot be processed

See Also:

prepareRequest(String, String, String, Long), processSync(TranscodingRequest)

processAsync

public void processAsync(java.lang.String sourceUrl,
                         java.lang.String profileID,
                         java.lang.Long maxSize)
                  throws TranscodingException

Sends a single-job transcoding request to be processed asynchronously. The transcoded file location may be subsequently retrieved by the getTranscodedUrl(String, String, Long) method.

The method is primarily intended to transcode content with a predefined transcoding profile (defined in the server-side profile-defs.xml).

Parameters:

sourceUrl - source file location (accessed with HTTP protocol)

profileID - id of the selected predefined profile

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Throws:

TranscodingException - if the request cannot be processed

See Also:

getTranscodedUrl(String, String, Long), prepareRequest(String, String, String, Long), processAsync(TranscodingRequest)

isTranscodedFileReady

public boolean isTranscodedFileReady(java.lang.String sourceUrl,
                                     java.lang.String profileID,
                                     java.lang.Long maxSize)
                              throws java.lang.IllegalStateException

Checks whether a source file, whose processing was scheduled with the given parameters set has been already transcoded.

Parameters:

sourceUrl - source file location (accessed with HTTP protocol)

profileID - id of the selected predefined profile

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Returns:

true if the transcoded file is ready; otherwise false

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

processAsync(String, String, Long)

getTranscodedUrl

public java.lang.String getTranscodedUrl(java.lang.String sourceUrl,
                                         java.lang.String profileID,
                                         java.lang.Long maxSize)
                                  throws java.lang.IllegalStateException

Returns the transcoded file location for a job scheduled with the given parameters set.

Parameters:

sourceUrl - source file location (accessed with HTTP protocol)

profileID - id of the selected predefined profile

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Returns:

transcoded file location if available; otherwise null

Throws:

java.lang.IllegalStateException - upon any connection error

See Also:

processAsync(String, String, Long)

prepareRequest

public static TranscodingRequest prepareRequest(java.lang.String sourceUrl,
                                                java.lang.String profileID,
                                                java.lang.String contentType,
                                                java.lang.Long maxSize)

Creates a single-job trancoding request instance with the given transcoding parameters set.

The method is primarily intended for the transcoding jobs of a predefined transcoding profile (defined in the server-side profile-defs.xml).

Parameters:

sourceUrl - source file location (accessed with HTTP protocol)

profileID - id of the selected predefined profile

contentType - mime-type of the source file; if null Alembik will evaluate it itself

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Returns:

transcoding request with one job specified

See Also:

TranscodingJob.Source.setLocation(String), TranscodingJob.Target.setProfileID(String), TranscodingJob.Source.setContentType(String), OMAUtils.getSizeLimit(TranscodingJob)

prepareUARequest

public static TranscodingRequest prepareUARequest(java.lang.String sourceUrl,
                                                  java.lang.String userAgent,
                                                  java.lang.Class<? extends Media> mediaType,
                                                  java.lang.Long maxSize)
                                           throws java.lang.IllegalArgumentException

Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and (optionally) size limit.

The method is generally intended for the transcoding jobs that process mobile content.

Parameters:

sourceUrl - source file location

userAgent - device's User-Agent string

mediaType - output media type

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Returns:

transcoding request with one job specified

Throws:

java.lang.IllegalArgumentException - if mediaType is not the class of Image, Audio, Video or Text type

See Also:

TranscodingJob.Source.setLocation(String), TranscodingJob.Target.setProfileID(String), OMAUtils.setMedia(TranscodingParams, Media), OMAUtils.getSizeLimit(TranscodingJob)

prepareUARequest

public static TranscodingRequest prepareUARequest(java.lang.String sourceUrl,
                                                  java.lang.String userAgent,
                                                  java.lang.Class<? extends Media> mediaType,
                                                  java.lang.Integer width,
                                                  java.lang.Integer height)
                                           throws java.lang.IllegalArgumentException

Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and (optionally) dimensions.

The method is generally intended for the transcoding jobs that process mobile content. The output content will be resized to the specified dimensions using the OMAUtils.RESIZE_ASPECT_RATIO directive.

Parameters:

sourceUrl - source file location

userAgent - device's User-Agent string

mediaType - output media type

width - transcoded content's width (in pixels); may be null

height - transcoded content's height (in pixels); may be null

Returns:

transcoding request with one job specified

Throws:

java.lang.IllegalArgumentException - if mediaType is not the class of Image, Video or Text type

See Also:

TranscodingJob.Source.setLocation(String), TranscodingJob.Target.setProfileID(String), OMAUtils.setMedia(TranscodingParams, Media), TranscodingUtils.setDimensions(Media, Integer, Integer)

prepareUARequestWithScaling

public static TranscodingRequest prepareUARequestWithScaling(java.lang.String sourceUrl,
                                                             java.lang.String userAgent,
                                                             java.lang.Class<? extends Media> mediaType,
                                                             java.lang.Integer relativeWidth,
                                                             java.lang.Integer relativeHeight)
                                                      throws java.lang.IllegalArgumentException

Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and (optionally) dimensions in the form of percentage of a device screen size.

The method is generally intended for the transcoding jobs that process mobile content. The output content will be resized to the specified dimensions using the OMAUtils.RESIZE_ASPECT_RATIO directive.

Parameters:

sourceUrl - source file location

userAgent - device's User-Agent string

mediaType - output media type

relativeWidth - transcoded content's width relative to a device's screen; may be null

relativeHeight - transcoded content's height relative to a device's screen may be null

Returns:

transcoding request with one job specified

Throws:

java.lang.IllegalArgumentException - if mediaType is not the class of Image or Video type

See Also:

TranscodingJob.Source.setLocation(String), TranscodingJob.Target.setProfileID(String), OMAUtils.setMedia(TranscodingParams, Media), TranscodingUtils.addRelativeResize(Media, Integer, Integer, String)

prepareUARequestStreamingVideo

public static TranscodingRequest prepareUARequestStreamingVideo(java.lang.String sourceUrl,
                                                                java.lang.String userAgent,
                                                                java.lang.Long maxSize)

Creates a single-job streaming video transcoding request for the given source location, User-Agent string and (optionally) size limit.

The method is generally intended for the transcoding jobs that process video streaming to mobile devices.

Parameters:

sourceUrl - source file location

userAgent - device's User-Agent string

maxSize - size limit (in bytes) for the transcoded file; if null the file size will be unlimited

Returns:

transcoding request with one streaming video job specified

See Also:

TranscodingUtils.TRANSFORMATION_STREAMING, prepareUARequest(String, String, Class, Long)

prepareBestMatchingRequest

public static TranscodingRequest prepareBestMatchingRequest(java.lang.String sourceUrl,
                                                            java.lang.String userAgent,
                                                            java.lang.Class<? extends Media> mediaType,
                                                            Quality quality,
                                                            boolean isStreaming)
                                                     throws java.lang.IllegalArgumentException

Creates a single-job transcoding request instance for the given source location, User-Agent string, specified transcoded content's type and desired quality of a predefined profile selected by "best matching" strategy algorithm. The additional streaming argument indicates if the chosen profile needs to have streaming enabled.

Parameters:

sourceUrl - source file location

userAgent - device's User-Agent string

mediaType - output media type

quality - quality of a selected predefined profile

isStreaming - true if the selected profile must have the streaming transformation set

Returns:

transcoding request with a "best matching" strategy job

Throws:

java.lang.IllegalArgumentException - if mediaType is not the class of Audio or Video type in case of streaming enabled

See Also:

TranscodingUtils.setBestMatchingQuality(TranscodingJob, Quality)