XmlAuthorResource.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.resources.catalogue.api;

import java.util.stream.Collectors;

import org.apache.commons.lang3.StringUtils;
import org.ctan.site.domain.Gender;
import org.ctan.site.stores.AuthorStore;

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import io.dropwizard.hibernate.UnitOfWork;
import jakarta.annotation.security.PermitAll;
import jakarta.ws.rs.DefaultValue;
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>XmlAuthorResource</code> contains the controller for the
 * author resource.
 *
 * @author <a href="mailto:gene@ctan.org">Gerd Neugebauer</a>
 */
@Path("/")
@Produces(MediaType.APPLICATION_XML)
public class XmlAuthorResource {

    /**
     * The field <code>store</code> contains the underlying repository.
     */
    private AuthorStore store;

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

        this.store = store;
    }

    /**
     * The method <code>getAuthorByKey</code> provides means to retrieve an
     * author.
     *
     * @param vers the version
     * @param id the key of the author
     * @param ref the indicator whether or not to return the references to the
     *     packages authored by the author
     * @return an author or {@code null}
     */
    @GET
    @Path("/xml/{vers}/author/{id}")
    @PermitAll
    @UnitOfWork(value = "siteDb")
    public String getAuthorByKey(
        @NonNull @PathParam("vers") String vers,
        @NonNull @PathParam("id") String id,
        @QueryParam("ref") @DefaultValue("false") Boolean ref,
        @QueryParam("no-dtd") @DefaultValue("false") Boolean noDtd,
        @QueryParam("no-xml") @DefaultValue("false") Boolean noXml) {

        switch (vers) {
            case "1.0", "1.1", "1.2", "1.3", "2.0", "2.1":
                break;
            default:
                throw new WebApplicationException(Status.NOT_FOUND);
        }
        var a = store.getByKey(id);
        if (a == null) {
            throw new WebApplicationException(Status.NOT_FOUND);
        }
        var xml = new XmlWriter();
        if (!noXml) {
            xml.out("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n");
        }
        if (!noDtd) {
            xml.out("<!DOCTYPE author SYSTEM 'http://www.ctan.org/xml/" + vers
                + "/catalogue.dtd'>\n");
        }
        xml.out("<author key=\"", id, "\"");
        var pseudonym = a.getPseudonym();
        var hasPseudonym = StringUtils.isNotEmpty(pseudonym);
        xml.out(" givenname=\"",
            hasPseudonym ? pseudonym : a.getGivenname(),
            "\"");
        xml.outName(hasPseudonym, "familyname", a.getFamilyname());
        switch (vers) {
            case "1.0", "1.1":
                break;
            case "1.2", "1.3", "2.0", "2.1":
                xml.outName(hasPseudonym, "von", a.getVon());
                xml.outName(hasPseudonym, "junior", a.getJunior());
                xml.outName(hasPseudonym, "title", a.getTitle());
                xml.outIf(a.getDied(), "died", "true");
                xml.outIf(a.getGender() == Gender.F, "female", "true");
                break;
            default:
                // This can not happen
        }
        if (ref) {
            xml.out(">\n");
            var packages = a.getRefs().stream()
                .map(r -> r.getPkg().getKey())
                .sorted()
                .collect(Collectors.toList())
                .toArray(new String[]{});
            for (var p : packages) {
                xml.out("  <package key=\"", p, "\" >\n");
            }
            xml.out("</author>\n");
        } else {
            xml.out(" />\n");
        }
        return xml.toString();
    }

    /**
     * The method <code>getAuthors</code> provides means to retrieve a list of
     * authors starting with a given pattern.
     *
     * @param vers the version number
     * @param key the key
     * @return a list of matching author summaries
     */
    @GET
    @Path("/xml/{vers}/authors")
    @PermitAll
    @UnitOfWork(value = "siteDb")
    public String getAuthors(
        @NonNull @PathParam("vers") String vers,
        @QueryParam("key") String key,
        @QueryParam("no-dtd") @DefaultValue("false") Boolean noDtd,
        @QueryParam("no-xml") @DefaultValue("false") Boolean noXml) {

        switch (vers) {
            case "1.0", "1.1", "1.2", "1.3", "2.0", "2.1":
                break;
            default:
                throw new WebApplicationException(Status.NOT_FOUND);
        }
        var xml = new XmlWriter();
        if (!noXml) {
            xml.out("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n");
        }
        if (!noDtd) {
            xml.out("<!DOCTYPE authors SYSTEM 'http://www.ctan.org/xml/" + vers
                + "/catalogue.dtd'>\n");
        }
        var list = store.findAllByKeyStartingWith(key != null ? key : "");
        xml.out("<authors>\n");
        for (var a : list) {
            var pseudonym = a.getPseudonym();
            var hasPseudonym = StringUtils.isNotEmpty(pseudonym);
            xml.out("  <author key=\"", a.getKey(), "\"");
            xml.out(" givenname=\"",
                hasPseudonym ? pseudonym : a.getGivenname(),
                "\"");
            xml.outName(hasPseudonym, "familyname", a.getFamilyname());
            switch (vers) {
                case "1.0", "1.1":
                    break;
                case "1.2":
                    xml.outIf(a.getGender() == Gender.F, "female", "true");
                    break;
                case "1.3", "2.0", "2.1":
                    xml.outIf(a.getGender() == Gender.F, "female", "true");
                    xml.outName(hasPseudonym, "von", a.getVon());
                    xml.outName(hasPseudonym, "junior", a.getJunior());
                    xml.outName(hasPseudonym, "title", a.getTitle());
                    xml.outIf(a.getDied(), "died", "true");
                    break;
                default:
                    // can not happen;
            }
            xml.out(" />\n");
        }
        xml.out("</authors>\n");
        return xml.toString();
    }
}