Attachment Validation API

Last modified by Admin on 2024/03/25 16:23

cogAPI dedicated to the validation of Attachments
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

14.10RC1+

Installable with the Extension Manager

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);
}

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;
}

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;
}

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)
   {
       // ...
   }
}

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.2.0):

Tags:
    

Get Connected