Texarchive3Resource.java

/*
 * Copyright © 2022-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.resources.texarchive;

import java.util.Map;

import org.ctan.site.services.texarchive.TexArchiveService;
import org.ctan.site.services.texarchive.TexArchiveService.TexarchiveListTo;

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import io.dropwizard.hibernate.UnitOfWork;
import jakarta.annotation.security.PermitAll;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.WebApplicationException;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response.Status;
import lombok.NonNull;

/**
 * The class <code>TexArchive3Resource</code> contains the controller for the
 * <code>/api/«xxx»/tex-archive</code> resource.
 *
 * @author <a href="mailto:gene@ctan.org">Gerd Neugebauer</a>
 */
@Path("/3.0")
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public class Texarchive3Resource {

    /**
     * The field <code>service</code> contains the underlying service.
     */
    private TexArchiveService service;

    /**
     * This is the constructor for the class <code>TexArchive3Resource</code>.
     *
     * @param service the underlying service
     */
    @SuppressFBWarnings(value = {"CT_CONSTRUCTOR_THROW", "EI_EXPOSE_REP2"})
    public Texarchive3Resource(@NonNull TexArchiveService service) {

        this.service = service;
    }

    /**
     * The method <code>getList</code> provides means to retrieve the listing
     * for one directory.
     *
     * @param path the path in the <span>T<span style=
     *     "text-transform:uppercase;font-size:90%;vertical-align:-0.4ex;
     *     margin-left:-0.2em;margin-right:-0.1em;line-height: 0;" >e</span>
     *     X</span> archive
     * @param page the page segment
     * @param size the size of pages
     * @param lang the language
     * @return a list of files
     */
    @GET
    @Path("/tex-archive/list/{path:.*}")
    @PermitAll
    @UnitOfWork(value = "siteDb")
    public TexarchiveListTo getList(@PathParam("path") String path,
        @QueryParam("page") int page,
        @QueryParam("size") int size,
        @QueryParam("lang") String lang) {

        try {
            var list = service.getList(path, lang, page, size);
            if (list == null) {
                throw new WebApplicationException(Status.NOT_FOUND);
            }
            return list;
        } catch (IllegalArgumentException e) {
            throw new WebApplicationException(Status.BAD_REQUEST);
        }
    }

    /**
     * The method <code>getVersion</code> provides means to retrieve the version
     * number of the API.
     *
     * @return a Map with a single attribute <code>version</code> containing the
     *     version number as String.
     */
    @GET
    @Path("/admin/tex-archive/version")
    @PermitAll
    public Map<String, String> getVersion() {

        return Map.of("version", "3.0");
    }
    //
    // /**
    // * The method <code>list</code> provides means to retrieve a page of
    // notes.
    // *
    // * @param q the name pattern
    // * @param page the page
    // * @param size the page size
    // * @param orderBy the order
    // * @param asc the indicator for ascending
    // * @return the page for the user or {@code null}
    // */
    // @GET
    // @Path("/admin/tex-archive-notes")
    // @RolesAllowed("ADMIN")
    // @UnitOfWork(value = "siteDb")
    // public AbstractPage list(@QueryParam("q") String q,
    // @QueryParam("page") int page,
    // @QueryParam("size") int size,
    // @QueryParam("order") String orderBy,
    // @QueryParam("asc") boolean asc) {
    //
    // return store.list(q,
    // page <= 0 ? 0 : page - 1,
    // size > 0 ? size : 256,
    // orderBy,
    // asc);
    // }
    //
    // /**
    // * The method <code>note</code> provides means to retrieve a note.
    // *
    // * @param id the id
    // * @return {@code true} iff the user exists
    // */
    // @GET
    // @Path("/admin/tex-archive-note/{id}")
    // @RolesAllowed("ADMIN")
    // @UnitOfWork(value = "siteDb")
    // public TexArchiveNotes note(@PathParam("id") Long id) {
    //
    // return store.getById(id);
    // }
    //
    // /**
    // * The method <code>remove</code> provides an end-point to remove a note.
    // *
    // * @param id the id
    // * @return {@code true} iff the user has existed
    // */
    // @DELETE
    // @Path("/admin/tex-archive-note/{id}")
    // @RolesAllowed("ADMIN")
    // @UnitOfWork(value = "siteDb")
    // public boolean remove(@PathParam("id") long id) {
    //
    // return store.remove(id);
    // }
}