Headless Server Developer Manual / Version 2512.0
Table Of ContentsThe media endpoints are implemented by means of an internal REST controller with the url patterns statically defined. These patterns can't be changed by configuration. Other aspects of the media endpoints however can be customized by implementing certain interfaces which are provided as Extension Points. The following interfaces are available for customization:
ContentResolver- Allows to customize the resolution of content IDs to media content objects.FilenamesResolver- Allows to customize the resolution of valid media file names.BlobResolver- Allows to customize the resolution of media blobs.MediaUrlValidator- Allows to customize the validation of media URLs.MediaUrlValidationExceptionHandler- Allows to customize the handling of exceptions thrown by aMediaUrlValidator.
Content Resolving and Media URL Validation
The resolvers are invoked in the order listed above. Default implementations of all resolvers are provided out of the box.
The default implementations can be replaced by custom implementations by providing a bean of the respective type.
After invocation of the resolvers, an instance of ResolvedBlobInfo is created, which contains the results of the resolvers.
After the invocation of the resolvers, validation of the media URL is performed by several implementations of MediaUrlValidator.
The validation is performed by the provided default validators in the order listed below:
defaultPathValidator- Validates the given property path of the media URL. If the property path is invalid, an HTTP 404 Not Found is returned.defaultValidityDateValidator- Validates the validity dates of the resolved media content. If the validity dates are defined and not valid, an HTTP 404 Not Found is returned. If the validity dates are not defined, the validation is skipped.defaultFilenameValidator- Validates the filename from the request against the resolved valid filenames. If the given filename does not match one of the resolved filename, an HTTP 404 Not Found is returned.defaultCropNameValidator- Validates the crop name and width from the request against the existing crop names, available in the resolved blob. If the given crop name or width does not match, an HTTP 404 Not Found is returned.defaultBlobValidator- Validates if a resolved blob exists. If a blob is not found, an HTTP 404 Not Found is returned. If the media type isapplication/x.coremedia.encrypted, an HTTP 403 Forbidden is returned.defaultHashValidator- Validates the hash from the request against the hash from the resolved blob. If the given hash does not match, an HTTP 404 Not Found is returned. If the configuration propertycaas.strict-blob-hash-validationis set to false (default is true), and the given hash does not match but the rest of the URL is valid, an HTTP 301 Moved Permanently is invoked.
If necessary, all validators can be disabled by a property beginning with the prefix 'caas.media-controller'. Please see Section 3.3, “Headless Server Properties” in Deployment Manual for details.
Exception Handling
If a validation fails, an MediaUrlValidationException is thrown. The exception, which bears a message,
an HTTP-Status-Code and an optional redirect location, is handled by the MediaUrlValidationExceptionHandler.
The default implementation of the exception handler will return an HTTP response with the status code and the message from the exception.
If you want to customize the handling of validation errors, you can provide your own implementation of the MediaUrlValidationExceptionHandler.
The custom implementation will be invoked instead of the default implementation.
For details about any of the described interfaces, please also refer to the Javadoc.
