Attachment Validation API
Last modified by Manuel Leduc on 2022/12/19 09:56
 | API to validate attachment on upload |
| Type | JAR |
| Category | |
| Developed by | Unknown |
| Rating | |
| License | Unknown |
| Bundled With | XWiki Standard |
| Compatibility | 14.10RC1+ |
Description
This document present the API provided to validate attachment before upload. This is part of Attachment Validation Application.
Configuration
/**
* Configuration values for the attachment validation.
*
* @since 14.10
*/
@Role
@Unstable
public interface AttachmentValidationConfiguration
{
/**
* @return the list of allowed attachment mimetypes of the current document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
*/
List<String> getAllowedMimetypes();
/**
* @param documentReference the reference of a document
* @return the list of allowed attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., * "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
List<String> getAllowedMimetypes(DocumentReference documentReference);
/**
* @return the list of blocker attachment mimetype of the current document. A joker (@code '*') can be used to match
* any media (e.g., "image/png", "text/*")
*/
List<String> getBlockerMimetypes();
/**
* @param documentReference the reference of a document
* @return the list of blocker attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., * "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
List<String> getBlockerMimetypes(DocumentReference documentReference);
}
* Configuration values for the attachment validation.
*
* @since 14.10
*/
@Role
@Unstable
public interface AttachmentValidationConfiguration
{
/**
* @return the list of allowed attachment mimetypes of the current document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
*/
List<String> getAllowedMimetypes();
/**
* @param documentReference the reference of a document
* @return the list of allowed attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., * "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
List<String> getAllowedMimetypes(DocumentReference documentReference);
/**
* @return the list of blocker attachment mimetype of the current document. A joker (@code '*') can be used to match
* any media (e.g., "image/png", "text/*")
*/
List<String> getBlockerMimetypes();
/**
* @param documentReference the reference of a document
* @return the list of blocker attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., * "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
List<String> getBlockerMimetypes(DocumentReference documentReference);
}
Validation
The validation is handled by a global attachment validation, which is expected to be called by external code that wants to validate an attachment.
This validation is then split into validation steps, each validating a specific aspect (e.g., size, mimentype...) of an attachment.
Global Validation
/**
* Provide the operations to validate an attachment. For instance, by checking the size or the mimetype of the
* attachment.
*
* @since 14.10RC1
*/
@Role
@Unstable
public interface AttachmentValidator
{
/**
* Check if the part is a valid attachment in the current space.
*
* @param wrapper the attachment wrapper, containing the actual uploaded file input stream, and its required
* metadatas
* @throws AttachmentValidationException in case of error when validating the part
*/
void validateAttachment(AttachmentAccessWrapper wrapper) throws AttachmentValidationException;
}
* Provide the operations to validate an attachment. For instance, by checking the size or the mimetype of the
* attachment.
*
* @since 14.10RC1
*/
@Role
@Unstable
public interface AttachmentValidator
{
/**
* Check if the part is a valid attachment in the current space.
*
* @param wrapper the attachment wrapper, containing the actual uploaded file input stream, and its required
* metadatas
* @throws AttachmentValidationException in case of error when validating the part
*/
void validateAttachment(AttachmentAccessWrapper wrapper) throws AttachmentValidationException;
}
Validation Step
/**
* One attachment validation step. {@link AttachmentValidator} calls them one after the other and fails whenever a step
* fails.
*
* @since 14.10RC1
*/
@Role
@Unstable
public interface AttachmentValidationStep
{
/**
* Validate a single aspect of the attachment.
*
* @param wrapper the attachment wrapper
* @throws AttachmentValidationException in case of validation error
*/
void validate(AttachmentAccessWrapper wrapper) throws AttachmentValidationException;
}
* One attachment validation step. {@link AttachmentValidator} calls them one after the other and fails whenever a step
* fails.
*
* @since 14.10RC1
*/
@Role
@Unstable
public interface AttachmentValidationStep
{
/**
* Validate a single aspect of the attachment.
*
* @param wrapper the attachment wrapper
* @throws AttachmentValidationException in case of validation error
*/
void validate(AttachmentAccessWrapper wrapper) throws AttachmentValidationException;
}
Script Service
/**
* Script service for the attachment validation. Provide the attachment validation configuration values.
*
* @since 14.10
*/
@Component
@Singleton
@Named("attachmentValidation")
@Unstable
public class AttachmentValidationScriptService implements ScriptService
{
/**
* @return the list of allowed attachment mimetypes of the current document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
*/
public List<String> getAllowedMimetypes()
{
// ...
}
/**
* @param documentReference the reference of a document
* @return the list of allowed attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
public List<String> getAllowedMimetypes(DocumentReference documentReference)
{
// ...
}
/**
* @return the list of blocker attachment mimetype of the current document. A joker (@code '*') can be used to match
* any media (e.g., "image/png", "text/*")
*/
public List<String> getBlockerMimetypes()
{
// ...
}
/**
* @param documentReference the reference of a document
* @return the list of blocker attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
public List<String> getBlockerMimetypes(DocumentReference documentReference)
{
// ...
}
}
* Script service for the attachment validation. Provide the attachment validation configuration values.
*
* @since 14.10
*/
@Component
@Singleton
@Named("attachmentValidation")
@Unstable
public class AttachmentValidationScriptService implements ScriptService
{
/**
* @return the list of allowed attachment mimetypes of the current document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
*/
public List<String> getAllowedMimetypes()
{
// ...
}
/**
* @param documentReference the reference of a document
* @return the list of allowed attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
public List<String> getAllowedMimetypes(DocumentReference documentReference)
{
// ...
}
/**
* @return the list of blocker attachment mimetype of the current document. A joker (@code '*') can be used to match
* any media (e.g., "image/png", "text/*")
*/
public List<String> getBlockerMimetypes()
{
// ...
}
/**
* @param documentReference the reference of a document
* @return the list of blocker attachment mimetypes of the provided document. A joker (@code '*') can be used to
* match any media (e.g., "image/png", "text/*")
* @since 14.10.2
* @since 15.0RC1
*/
public List<String> getBlockerMimetypes(DocumentReference documentReference)
{
// ...
}
}
