<commit_before>/*
 * Licensed to IAESTE A.s.b.l. (IAESTE) under one or more contributor
 * license agreements.  See the NOTICE file distributed with this work
 * for additional information regarding copyright ownership. The Authors
 * (See the AUTHORS file distributed with this work) licenses this file to
 * You under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License.  You may obtain a
 * copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.iaeste.iws.api;

import net.iaeste.iws.api.dtos.AuthenticationToken;
import net.iaeste.iws.api.requests.exchange.DeleteOfferRequest;
import net.iaeste.iws.api.requests.exchange.FetchEmployerRequest;
import net.iaeste.iws.api.requests.exchange.FetchOffersRequest;
import net.iaeste.iws.api.requests.exchange.FetchPublishGroupsRequest;
import net.iaeste.iws.api.requests.exchange.FetchPublishedGroupsRequest;
import net.iaeste.iws.api.requests.exchange.HideForeignOffersRequest;
import net.iaeste.iws.api.requests.exchange.OfferCSVUploadRequest;
import net.iaeste.iws.api.requests.exchange.OfferStatisticsRequest;
import net.iaeste.iws.api.requests.exchange.EmployerRequest;
import net.iaeste.iws.api.requests.exchange.OfferRequest;
import net.iaeste.iws.api.requests.exchange.ProcessPublishingGroupRequest;
import net.iaeste.iws.api.requests.exchange.PublishOfferRequest;
import net.iaeste.iws.api.requests.exchange.RejectOfferRequest;
import net.iaeste.iws.api.responses.FallibleResponse;
import net.iaeste.iws.api.responses.exchange.EmployerResponse;
import net.iaeste.iws.api.responses.exchange.FetchEmployerResponse;
import net.iaeste.iws.api.responses.exchange.FetchGroupsForSharingResponse;
import net.iaeste.iws.api.responses.exchange.FetchOffersResponse;
import net.iaeste.iws.api.responses.exchange.FetchPublishedGroupsResponse;
import net.iaeste.iws.api.responses.exchange.FetchPublishingGroupResponse;
import net.iaeste.iws.api.responses.exchange.OfferCSVDownloadResponse;
import net.iaeste.iws.api.responses.exchange.OfferCSVUploadResponse;
import net.iaeste.iws.api.responses.exchange.OfferResponse;
import net.iaeste.iws.api.responses.exchange.OfferStatisticsResponse;
import net.iaeste.iws.api.responses.exchange.PublishOfferResponse;

/**
 * <p>Exchange related functionality is covered with this interface. Only
 * exception here, the handling of students is done vai the {@link Students}
 * interface.</p>
 *
 * @author  <NAME> / last $Author:$
 * @version $Revision:$ / $Date:$
 * @since   IWS 1.0
 */
public interface Exchange {

    /**
     * <p>Retrieves the Offer Statistics information.</p>
     *
     * @param token   User Authentication Token
     * @param request Offer Statistics Request Object
     * @return Response Object with Error and Statistics information
     */
    OfferStatisticsResponse fetchOfferStatistics(AuthenticationToken token, OfferStatisticsRequest request);

    /**
     * <p>Processes a given Employer, meaning that if it exists, then it us
     * updated, otherwise it is being created.</p>
     *
     * @param token   User Authentication Token
     * @param request Request Object, with the Employer
     * @return Persisted Employer Object
     */
    EmployerResponse processEmployer(AuthenticationToken token, EmployerRequest request);

    /**
     * <p>Fetches a list of Employers, belonging to the requesting User, i.e.
     * which is associated with the Users National Group. The request can be
     * made either for a single Object (by providing the Id), for a partial
     * list (by providing a partial name) or for all Employers.</p>
     *
     * @param token   User Authentication Token
     * @param request Employer Request Object
     * @return List of requested Employers
     */
    FetchEmployerResponse fetchEmployers(AuthenticationToken token, FetchEmployerRequest request);

    /**
     * <p>Creates or updates an Offer, dependent on the {@code id}. If the id
     * is set, an update is assumed, otherwise a create will be performed.</p>
     *
     * <p>On error the {@link OfferResponse} object contains only error
     * information. No information about the Offer is returned.</p>
     *
     * @param token The valid authentication token provided by {@link Access#generateSession(net.iaeste.iws.api.requests.AuthenticationRequest)}
     * @param request contains a {@link net.iaeste.iws.api.dtos.exchange.Offer}
     * @return the persisted {@link net.iaeste.iws.api.dtos.exchange.Offer} including the generated Id
     */
    OfferResponse processOffer(AuthenticationToken token, OfferRequest request);

    /**
     * <p>Performs a deletion of the offer.</p>
     *
     * <p>Note; This should only be under certain circumstances: only if the
     * offer is in state new. Doesn't matter if it was once shared. But it
     * should never be able to be deleted once a student was nominated.</p>
     *
     * @param token The valid authentication token provided by {@link Access#generateSession(net.iaeste.iws.api.requests.AuthenticationRequest)}
     * @param request contains a field with the RefNo (will be changed to id #359)
     * @return empty {@link OfferResponse} (offer=null) on success
     */
    OfferResponse deleteOffer(AuthenticationToken token, DeleteOfferRequest request);

    /**
     * <p>IW3, IAESTE IntraWeb version 3, allowed users to upload their Offers
     * directly as a CSV file, to avoid typing it all again. Although IWS
     * provides better mechanisms in the form of a published API which will
     * allow a much greater control - it is still requested by Users, that they
     * can perform this action, as some countries do not have the capacity to
     * implement an IWS API Client otherwise.</p>
     *
     * @param token   The valid authentication token provided by {@link Access#generateSession(net.iaeste.iws.api.requests.AuthenticationRequest)}
     * @param request Offer CSV Upload Request
     * @return Response Object with error information from the uploading
     */
    OfferCSVUploadResponse uploadOffers(AuthenticationToken token, OfferCSVUploadRequest request);

    /**
     * <p>Retrieves a list of offers. This can be either the list of owned
     * offers or offers which are shared with your country.</p>
     *
g     * <dl>
     *   <dt>{@link net.iaeste.iws.api.enums.FetchType#DOMESTIC}</dt>
     *     <dd>Requests all own/domestic offers.</dd>
     *   <dt>{@link net.iaeste.iws.api.enums.FetchType#SHARED}</dt>
     *     <dd>Means that all shared offers are requested.</dd>
     * </dl><commit_msg>Made the deleteOffer request deprecated, it must be replaced by the processOffer request.<commit_after>/*
 * Licensed to IAESTE A.s.b.l. (IAESTE) under one or more contributor
 * license agreements.  See the NOTICE file distributed with this work
 * for additional information regarding copyright ownership. The Authors
 * (See the AUTHORS file distributed with this work) licenses this file to
 * You under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License.  You may obtain a
 * copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.iaeste.iws.api;

import net.iaeste.iws.api.dtos.AuthenticationToken;
import net.iaeste.iws.api.requests.exchange.DeleteOfferRequest;
import net.iaeste.iws.api.requests.exchange.FetchEmployerRequest;
import net.iaeste.iws.api.requests.exchange.FetchOffersRequest;
import net.iaeste.iws.api.requests.exchange.FetchPublishGroupsRequest;
import net.iaeste.iws.api.requests.exchange.FetchPublishedGroupsRequest;
import net.iaeste.iws.api.requests.exchange.HideForeignOffersRequest;
import net.iaeste.iws.api.requests.exchange.OfferCSVUploadRequest;
import net.iaeste.iws.api.requests.exchange.OfferStatisticsRequest;
import net.iaeste.iws.api.requests.exchange.EmployerRequest;
import net.iaeste.iws.api.requests.exchange.OfferRequest;
import net.iaeste.iws.api.requests.exchange.ProcessPublishingGroupRequest;
import net.iaeste.iws.api.requests.exchange.PublishOfferRequest;
import net.iaeste.iws.api.requests.exchange.RejectOfferRequest;
import net.iaeste.iws.api.responses.FallibleResponse;
import net.iaeste.iws.api.responses.exchange.EmployerResponse;
import net.iaeste.iws.api.responses.exchange.FetchEmployerResponse;
import net.iaeste.iws.api.responses.exchange.FetchGroupsForSharingResponse;
import net.iaeste.iws.api.responses.exchange.FetchOffersResponse;
import net.iaeste.iws.api.responses.exchange.FetchPublishedGroupsResponse;
import net.iaeste.iws.api.responses.exchange.FetchPublishingGroupResponse;
import net.iaeste.iws.api.responses.exchange.OfferCSVDownloadResponse;
import net.iaeste.iws.api.responses.exchange.OfferCSVUploadResponse;
import net.iaeste.iws.api.responses.exchange.OfferResponse;
import net.iaeste.iws.api.responses.exchange.OfferStatisticsResponse;
import net.iaeste.iws.api.responses.exchange.PublishOfferResponse;

/**
 * <p>Exchange related functionality is covered with this interface. Only
 * exception here, the handling of students is done vai the {@link Students}
 * interface.</p>
 *
 * @author  <NAME> / last $Author:$
 * @version $Revision:$ / $Date:$
 * @since   IWS 1.0
 */
public interface Exchange {

    /**
     * <p>Retrieves the Offer Statistics information.</p>
     *
     * @param token   User Authentication Token
     * @param request Offer Statistics Request Object
     * @return Response Object with Error and Statistics information
     */
    OfferStatisticsResponse fetchOfferStatistics(AuthenticationToken token, OfferStatisticsRequest request);

    /**
     * <p>Processes a given Employer, meaning that if it exists, then it us
     * updated, otherwise it is being created.</p>
     *
     * @param token   User Authentication Token
     * @param request Request Object, with the Employer
     * @return Persisted Employer Object
     */
    EmployerResponse processEmployer(AuthenticationToken token, EmployerRequest request);

    /**
     * <p>Fetches a list of Employers, belonging to the requesting User, i.e.
     * which is associated with the Users National Group. The request can be
     * made either for a single Object (by providing the Id), for a partial
     * list (by providing a partial name) or for all Employers.</p>
     *
     * @param token   User Authentication Token
     * @param request Employer Request Object
     * @return List of requested Employers
     */
    FetchEmployerResponse fetchEmployers(AuthenticationToken token, FetchEmployerRequest request);

    /**
     * <p>Creates or updates an Offer, dependent on the {@code id}. If the id
     * is set, an update is assumed, otherwise a create will be performed.</p>
     *
     * <p>On error the {@link OfferResponse} object contains only error
     * information. No information about the Offer is returned.</p>
     *
     * @param token The valid authentication token provided by {@link Access#generateSession(net.iaeste.iws.api.requests.AuthenticationRequest)}
     * @param request contains a {@link net.iaeste.iws.api.dtos.exchange.Offer}
     * @return the persisted {@link net.iaeste.iws.api.dtos.exchange.Offer} including the generated Id
     */
    OfferResponse processOffer(AuthenticationToken token, OfferRequest request);

    /**
     * <p>Performs a deletion of the offer.</p>
     *
     * <p>Note; This should only be under certain circumstances: only if the
     * offer is in state new. Doesn't matter if it was once shared. But it
     * should never be able to be deleted once a student was nominated.</p>
     *
     * @param token The valid authentication token provided by {@link Access#generateSession(net.iaeste.iws.api.requests.AuthenticationRequest)}
     * @param request contains a field with the RefNo (will be changed to id #359)
     * @return empty {@link OfferResponse} (offer=null) on success
     * @deprecated Please use the processOffer request instead.
     */
    @Deprecated
    OfferResponse deleteOffer(AuthenticationToken token, DeleteOfferRequest request);

    /**
     * <p>IW3, IAESTE IntraWeb version 3, allowed users to upload their Offers
     * directly as a CSV file, to avoid typing it all again. Although IWS
     * provides better mechanisms in the form of a published API which will
     * allow a much greater control - it is still requested by Users, that they
     * can perform this action, as some countries do not have the capacity to
     * implement an IWS API Client otherwise.</p>
     *
     * @param token   The valid authentication token provided by {@link Access#generateSession(net.iaeste.iws.api.requests.AuthenticationRequest)}
     * @param request Offer CSV Upload Request
     * @return Response Object with error information from the uploading
     */
    OfferCSVUploadResponse uploadOffers(AuthenticationToken token, OfferCSVUploadRequest request);

    /**
     * <p>Retrieves a list of offers. This can be either the list of owned
     * offers or offers which are shared with your country.</p>
     *
g     * <dl>
     *   <dt>{@link net.iaeste.iws.api.enums.FetchType#DOMESTIC}</dt>
     *     <dd>Requests all own/domestic offers.</dd>
     *   <dt>{@link net.iaeste.iws.api.enums.FetchType#SHARED}</dt>
     *     <dd>Means that all shared offers are requested.</dd>
     * </dl>
{'fraction_non_alphanumeric': 0.08745898130974461, 'fraction_numerical': 0.0015694107575973748, 'mean_word_length': 3.866018743491843, 'pattern_counts': {'":': 0, '<': 65, '<?xml version=': 0, '>': 65, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6884787', 'n_tokens_mistral': 4028, 'n_tokens_neox': 3857, 'n_words': 1281}