/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See License.txt in the project root for
 * license information.
 *
 * Code generated by Microsoft (R) AutoRest Code Generator.
 */

package com.microsoft.azure.cognitiveservices.vision.faceapi;

import com.microsoft.azure.cognitiveservices.vision.faceapi.models.CreatePersonGroupsOptionalParameter;
import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdatePersonGroupsOptionalParameter;
import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ListPersonGroupsOptionalParameter;
import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException;
import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersonGroup;
import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus;
import java.util.List;
import rx.Observable;

/**
 * An instance of this class provides access to all the operations defined
 * in PersonGroups.
 */
public interface PersonGroups {
    /**
     * Create a new person group with specified personGroupId, name and user-provided userData.
     *
     * @param personGroupId Id referencing a particular person group.
     * @param createOptionalParameter the object representing the optional parameters to be set before calling this API
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     */
    
    void create(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter);

    /**
     * Create a new person group with specified personGroupId, name and user-provided userData.
     *
     * @param personGroupId Id referencing a particular person group.
     * @param createOptionalParameter the object representing the optional parameters to be set before calling this API
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return a representation of the deferred computation of this call if successful.
     */
    
    Observable<Void> createAsync(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter);

    /**
     * Create a new person group with specified personGroupId, name and user-provided userData.
     *
     * @return the first stage of the create call
     */
    PersonGroupsCreateDefinitionStages.WithPersonGroupId create();

    /**
     * Grouping of create definition stages.
     */
    interface PersonGroupsCreateDefinitionStages {
        /**
         * The stage of the definition to be specify personGroupId.
         */
        interface WithPersonGroupId {
            /**
             * Id referencing a particular person group.
             *
             * @return next definition stage
             */
            PersonGroupsCreateDefinitionStages.WithExecute withPersonGroupId(String personGroupId);
        }

        /**
         * The stage of the definition which allows for any other optional settings to be specified.
         */
        interface WithAllOptions {
            /**
             * User defined name, maximum length is 128.
             *
             * @return next definition stage
             */
            PersonGroupsCreateDefinitionStages.WithExecute withName(String name);

            /**
             * User specified data. Length should not exceed 16KB.
             *
             * @return next definition stage
             */
            PersonGroupsCreateDefinitionStages.WithExecute withUserData(String userData);

        }

        /**
         * The last stage of the definition which will make the operation call.
        */
        interface WithExecute extends PersonGroupsCreateDefinitionStages.WithAllOptions {
            /**
             * Execute the request.
             *
             */
            void execute();

            /**
             * Execute the request asynchronously.
             *
             * @return a representation of the deferred computation of this call if successful.
             */
            Observable<Void> executeAsync();
        }
    }

    /**
     * The entirety of create definition.
     */
    interface PersonGroupsCreateDefinition extends
        PersonGroupsCreateDefinitionStages.WithPersonGroupId,
        PersonGroupsCreateDefinitionStages.WithExecute {
    }


    /**
     * Delete an existing person group. Persisted face images of all people in the person group will also
      *  be deleted.
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     */
    void delete(String personGroupId);

    /**
     * Delete an existing person group. Persisted face images of all people in the person group will also
      *  be deleted.
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return a representation of the deferred computation of this call if successful.
     */
    Observable<Void> deleteAsync(String personGroupId);



    /**
     * Retrieve the information of a person group, including its name and userData.
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     * @return the PersonGroup object if successful.
     */
    PersonGroup get(String personGroupId);

    /**
     * Retrieve the information of a person group, including its name and userData.
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return the observable to the PersonGroup object
     */
    Observable<PersonGroup> getAsync(String personGroupId);


    /**
     * Update an existing person group's display name and userData. The properties which does not appear in request
     *   body will not be updated.
     *
     * @param personGroupId Id referencing a particular person group.
     * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     */
    
    void update(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter);

    /**
     * Update an existing person group's display name and userData. The properties which does not appear in request
     *   body will not be updated.
     *
     * @param personGroupId Id referencing a particular person group.
     * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return a representation of the deferred computation of this call if successful.
     */
    
    Observable<Void> updateAsync(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter);

    /**
     * Update an existing person group's display name and userData. The properties which does not appear in request
     *   body will not be updated.
     *
     * @return the first stage of the update call
     */
    PersonGroupsUpdateDefinitionStages.WithPersonGroupId update();

    /**
     * Grouping of update definition stages.
     */
    interface PersonGroupsUpdateDefinitionStages {
        /**
         * The stage of the definition to be specify personGroupId.
         */
        interface WithPersonGroupId {
            /**
             * Id referencing a particular person group.
             *
             * @return next definition stage
             */
            PersonGroupsUpdateDefinitionStages.WithExecute withPersonGroupId(String personGroupId);
        }

        /**
         * The stage of the definition which allows for any other optional settings to be specified.
         */
        interface WithAllOptions {
            /**
             * User defined name, maximum length is 128.
             *
             * @return next definition stage
             */
            PersonGroupsUpdateDefinitionStages.WithExecute withName(String name);

            /**
             * User specified data. Length should not exceed 16KB.
             *
             * @return next definition stage
             */
            PersonGroupsUpdateDefinitionStages.WithExecute withUserData(String userData);

        }

        /**
         * The last stage of the definition which will make the operation call.
        */
        interface WithExecute extends PersonGroupsUpdateDefinitionStages.WithAllOptions {
            /**
             * Execute the request.
             *
             */
            void execute();

            /**
             * Execute the request asynchronously.
             *
             * @return a representation of the deferred computation of this call if successful.
             */
            Observable<Void> executeAsync();
        }
    }

    /**
     * The entirety of update definition.
     */
    interface PersonGroupsUpdateDefinition extends
        PersonGroupsUpdateDefinitionStages.WithPersonGroupId,
        PersonGroupsUpdateDefinitionStages.WithExecute {
    }


    /**
     * Retrieve the training status of a person group (completed or ongoing).
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     * @return the TrainingStatus object if successful.
     */
    TrainingStatus getTrainingStatus(String personGroupId);

    /**
     * Retrieve the training status of a person group (completed or ongoing).
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return the observable to the TrainingStatus object
     */
    Observable<TrainingStatus> getTrainingStatusAsync(String personGroupId);


    /**
     * List person groups and their information.
     *
     * @param listOptionalParameter the object representing the optional parameters to be set before calling this API
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     * @return the List&lt;PersonGroup&gt; object if successful.
     */
    
    List<PersonGroup> list(ListPersonGroupsOptionalParameter listOptionalParameter);

    /**
     * List person groups and their information.
     *
     * @param listOptionalParameter the object representing the optional parameters to be set before calling this API
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return the observable to the List&lt;PersonGroup&gt; object
     */
    
    Observable<List<PersonGroup>> listAsync(ListPersonGroupsOptionalParameter listOptionalParameter);

    /**
     * List person groups and their information.
     *
     * @return the first stage of the list call
     */
    PersonGroupsListDefinitionStages.WithExecute list();

    /**
     * Grouping of list definition stages.
     */
    interface PersonGroupsListDefinitionStages {

        /**
         * The stage of the definition which allows for any other optional settings to be specified.
         */
        interface WithAllOptions {
            /**
             * List person groups from the least personGroupId greater than the "start".
             *
             * @return next definition stage
             */
            PersonGroupsListDefinitionStages.WithExecute withStart(String start);

            /**
             * The number of person groups to list.
             *
             * @return next definition stage
             */
            PersonGroupsListDefinitionStages.WithExecute withTop(Integer top);

        }

        /**
         * The last stage of the definition which will make the operation call.
        */
        interface WithExecute extends PersonGroupsListDefinitionStages.WithAllOptions {
            /**
             * Execute the request.
             *
             * @return the List&lt;PersonGroup&gt; object if successful.
             */
            List<PersonGroup> execute();

            /**
             * Execute the request asynchronously.
             *
             * @return the observable to the List&lt;PersonGroup&gt; object
             */
            Observable<List<PersonGroup>> executeAsync();
        }
    }

    /**
     * The entirety of list definition.
     */
    interface PersonGroupsListDefinition extends
        PersonGroupsListDefinitionStages.WithExecute {
    }


    /**
     * Queue a person group training task, the training task may not be started immediately.
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @throws APIErrorException thrown if the request is rejected by server
     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent
     */
    void train(String personGroupId);

    /**
     * Queue a person group training task, the training task may not be started immediately.
     *
     * @param personGroupId Id referencing a particular person group.
     * @throws IllegalArgumentException thrown if parameters fail the validation
     * @return a representation of the deferred computation of this call if successful.
     */
    Observable<Void> trainAsync(String personGroupId);


}
