SubmitService.java

/*
 * Copyright © 2024-2025 The CTAN Team and individual authors
 *
 * This file is distributed under the 3-clause BSD license.
 * See file LICENSE for details.
 */
package org.ctan.site.services.upload;

import java.io.InputStream;

import org.ctan.site.domain.account.User;
import org.ctan.site.services.upload.util.Messages;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonInclude.Include;

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

/**
 * This class contains the submit service interface.
 *
 * @author <a href="mailto:gene@ctan.org">Gerd Neugebauer</a>
 */
public interface SubmitService {

    /**
     * The class <code>FieldOptions</code> contains the transport object for
     * field descriptions.
     */
    @Getter
    @Setter
    @Builder
    @AllArgsConstructor
    @JsonInclude(Include.NON_NULL)
    class FieldOptions {

        private Boolean blank;

        private Boolean email;

        private Boolean file;

        private Boolean list;

        private Integer maxsize;

        private Boolean nullable;

        private String text;

        private Boolean url;
    }

    /**
     * The class <code>Fields</code> contains the transport object for field
     * specifications.
     */
    @Getter
    @Setter
    @Builder
    @AllArgsConstructor
    @JsonInclude(Include.NON_NULL)
    @SuppressFBWarnings(value = "EI_EXPOSE_REP")
    class Fields {

        private FieldOptions pkg;

        private FieldOptions version;

        private FieldOptions author;

        private FieldOptions email;

        private FieldOptions uploader;

        private FieldOptions ctanPath;

        private FieldOptions license;

        private FieldOptions home;

        private FieldOptions bugtracker;

        private FieldOptions support;

        private FieldOptions repository;

        private FieldOptions announce;

        private FieldOptions development;

        private FieldOptions update;

        private FieldOptions topic;

        private FieldOptions announcement;

        private FieldOptions summary;

        private FieldOptions description;

        private FieldOptions note;

        private FieldOptions file;
    }

    /**
     * The class <code>UploadData</code> contains the transport object for the
     * upload meta data.
     */
    @Getter
    @Setter
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @SuppressFBWarnings(value = "EI_EXPOSE_REP")
    class UploadData {

        private String announce;

        private String announcement;

        private String authors;

        private String bugs;

        private String caption;

        private boolean confirm;

        private String ctanPath;

        private String description;

        private String development;

        private String home;

        private String[] licenses;

        private String mailinglist;

        private String name;

        private String notes;

        private String pkg;

        private String repository;

        private String support;

        private String[] topics;

        private String vers;

        private String update;

        private String uploader;

        private String email;

        /**
         * The method <code>isUpdate</code> provides means to retrieve the
         * update indicator.
         *
         * @return <code>true</code> iff the submit is an upload
         */
        public boolean isUpdate() {

            return "true".equals(update);
        }

        /**
         * The method <code>setLicenses</code> provides means to split the
         * argument and store the result as licenses.
         *
         * @param value the value
         */
        public void setLicenses(String value) {

            licenses = value.split("[,;] ");
        }

        /**
         * The method <code>setTopics</code> provides means to split the
         * argument and store the result as topics.
         *
         * @param value the value
         */
        public void setTopics(String value) {

            topics = value.split("[,;] ");
        }
    }

    /**
     * The method <code>getFields</code> provides means to retrieve the
     * supported fields and their attributes.
     *
     * @param api the number of the requested API
     * @return the fields
     * @throws UnsupportedOperationException if a wrong API version is given
     */
    Fields getFields(String api);

    /**
     * This is the getter for the version number.
     *
     * @return the version number
     */
    String getVersion();

    /**
     * This method performs a validation and a following upload if the
     * validation has succeeded.
     *
     * @param api the version of the API
     * @param data the parameters
     * @param fileName the name of the file
     * @param stream the file input stream
     * @param user the authenticated user or <code>null</code>
     * @return the list of messages
     */
    Messages upload(String api, UploadData data, String fileName,
        InputStream stream, User user);

    /**
     * This service method performs a validation and tries to store the data as
     * upload.
     *
     * @param api the version of the API
     * @param data the parameters
     * @param filename the file name
     * @param stream the input stream for the file
     * @return the messages
     */
    Messages validate(String api, UploadData data, String filename,
        InputStream stream);
}