Attachment Validation API
Last modified by Admin on 2024/12/11 01:07
 | API dedicated to the validation of Attachments |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | 14.10RC1+ |
Table of contents
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)
{
// ...
}
}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-attachment-validation-api 16.10.1):
- org.xwiki.commons:xwiki-commons-component-api 16.10.1
- org.xwiki.commons:xwiki-commons-script 16.10.1
- org.xwiki.platform:xwiki-platform-bridge 16.10.1
